diff options
| -rw-r--r-- | ChangeLog | 20 | ||||
| -rw-r--r-- | manual/argp.texi | 4 | ||||
| -rw-r--r-- | manual/conf.texi | 60 | ||||
| -rw-r--r-- | manual/contrib.texi | 2 | ||||
| -rw-r--r-- | manual/filesys.texi | 833 | ||||
| -rw-r--r-- | manual/install.texi | 79 | ||||
| -rw-r--r-- | manual/job.texi | 4 | ||||
| -rw-r--r-- | manual/lang.texi | 104 | ||||
| -rw-r--r-- | manual/llio.texi | 299 | ||||
| -rw-r--r-- | manual/math.texi | 204 | ||||
| -rw-r--r-- | manual/nss.texi | 28 | ||||
| -rw-r--r-- | manual/pipe.texi | 6 | ||||
| -rw-r--r-- | manual/signal.texi | 24 | ||||
| -rw-r--r-- | manual/socket.texi | 339 | ||||
| -rw-r--r-- | manual/stdio.texi | 105 | ||||
| -rw-r--r-- | manual/sysinfo.texi | 28 | ||||
| -rw-r--r-- | manual/users.texi | 26 |
17 files changed, 1078 insertions, 1087 deletions
@@ -1,3 +1,23 @@ +1999-08-27 Ulrich Drepper <drepper@cygnus.com> + + * manual/argp.texi: Fixing language and types. + * manual/conf.texi: Likewise. + * manual/contrib.texi: Likewise. + * manual/filesys.texi: Likewise. + * manual/install.texi: Likewise. + * manual/job.texi: Likewise. + * manual/lang.texi: Likewise. + * manual/llio.texi: Likewise. + * manual/math.texi: Likewise. + * manual/nss.texi: Likewise. + * manual/pipe.texi: Likewise. + * manual/signal.texi: Likewise. + * manual/socket.texi: Likewise. + * manual/stdio.texi: Likewise. + * manual/sysinfo.texi: Likewise. + * manual/users.texi: Likewise. + Patches by Neil Booth <NeilB@earthling.net>. + 1999-08-25 Ulrich Drepper <drepper@cygnus.com> * sysdeps/i386/fpu/bits/mathinline.h (__finite): Mark constant as diff --git a/manual/argp.texi b/manual/argp.texi index 4847468..0c4a85c 100644 --- a/manual/argp.texi +++ b/manual/argp.texi @@ -112,7 +112,7 @@ flag is used). @comment GNU @deftypevar {const char *} argp_program_bug_address If defined or set by the user program to a non-zero value, -@code{argp_program_bug_address} should point to string that is the +@code{argp_program_bug_address} should point to a string that is the bug-reporting address for the program. It will be printed at the end of the standard output for the @samp{--help} option, embedded in a sentence that says something like @samp{Report bugs to @var{address}.}. @@ -180,7 +180,7 @@ If non-zero, a string describing what non-option arguments are wanted by this parser; it is only used to print the @samp{Usage:} message. If it contains newlines, the strings separated by them are considered alternative usage patterns, and printed on separate lines (lines after -the first are prefix by @samp{ or: } instead of @samp{Usage:}). +the first are prefixed by @samp{ or: } instead of @samp{Usage:}). @item const char *doc If non-zero, a string containing extra text to be printed before and diff --git a/manual/conf.texi b/manual/conf.texi index 8815a16..bd866ec 100644 --- a/manual/conf.texi +++ b/manual/conf.texi @@ -446,7 +446,7 @@ Inquire about the parameter corresponding to @code{_POSIX_SEMAPHORES}. @comment unistd.h @comment POSIX.1 @item _SC_SHARED_MEMORY_OBJECTS -Inquire about the parameter corresponding to +Inquire about the parameter corresponding to@* @code{_POSIX_SHARED_MEMORY_OBJECTS}. @comment unistd.h @@ -580,7 +580,7 @@ Inquire about the parameter corresponding to @code{_POSIX_THREADS}. @comment unistd.h @comment POSIX.1 @item _SC_THREAD_SAFE_FUNCTIONS -Inquire about the parameter corresponding to +Inquire about the parameter corresponding to@* @code{_POSIX_THREAD_SAFE_FUNCTIONS}. @comment unistd.h @@ -627,13 +627,13 @@ Inquire about the parameter corresponding to @code{_POSIX_THREAD_THREADS_MAX}. @comment unistd.h @comment POSIX.1 @item _SC_THREAD_ATTR_STACKADDR -Inquire about the parameter corresponding to +Inquire about the parameter corresponding to@*a @code{_POSIX_THREAD_ATTR_STACKADDR}. @comment unistd.h @comment POSIX.1 @item _SC_THREAD_ATTR_STACKSIZE -Inquire about the parameter corresponding to +Inquire about the parameter corresponding to@* @code{_POSIX_THREAD_ATTR_STACKSIZE}. @comment unistd.h @@ -760,27 +760,27 @@ Inquire about the virtual memory page size of the machine. @comment unistd.h @comment GNU @item _SC_NPROCESSORS_CONF -Inquire about number of configured processors. +Inquire about the number of configured processors. @comment unistd.h @comment GNU @item _SC_NPROCESSORS_ONLN -Inquire about number of processors online. +Inquire about the number of processors online. @comment unistd.h @comment GNU @item _SC_PHYS_PAGES -Inquire about number of physical pages in the system. +Inquire about the number of physical pages in the system. @comment unistd.h @comment GNU @item _SC_AVPHYS_PAGES -Inquire about number of available physical pages in the system. +Inquire about the number of available physical pages in the system. @comment unistd.h @comment GNU @item _SC_ATEXIT_MAX -Inquire about number of functions which can be registered as termination +Inquire about the number of functions which can be registered as termination functions for @code{atexit}; @pxref{Cleanups on Exit}. @comment unistd.h @@ -831,41 +831,41 @@ Inquire about the parameter corresponding to @code{_XOPEN_XPG4}. @comment unistd.h @comment X/Open @item _SC_CHAR_BIT -Inquire about number of bits in a variable of type @code{char}. +Inquire about the number of bits in a variable of type @code{char}. @comment unistd.h @comment X/Open @item _SC_CHAR_MAX -Inquire about maximum value which can be stored in a variable of type +Inquire about the maximum value which can be stored in a variable of type @code{char}. @comment unistd.h @comment X/Open @item _SC_CHAR_MIN -Inquire about minimum value which can be stored in a variable of type +Inquire about the minimum value which can be stored in a variable of type @code{char}. @comment unistd.h @comment X/Open @item _SC_INT_MAX -Inquire about maximum value which can be stored in a variable of type +Inquire about the maximum value which can be stored in a variable of type @code{int}. @comment unistd.h @comment X/Open @item _SC_INT_MIN -Inquire about minimum value which can be stored in a variable of type +Inquire about the minimum value which can be stored in a variable of type @code{int}. @comment unistd.h @comment X/Open @item _SC_LONG_BIT -Inquire about number of bits in a variable of type @code{long int}. +Inquire about the number of bits in a variable of type @code{long int}. @comment unistd.h @comment X/Open @item _SC_WORD_BIT -Inquire about number of bits in a variable of a register word. +Inquire about the number of bits in a variable of a register word. @comment unistd.h @comment X/Open @@ -876,61 +876,61 @@ character value. @comment unistd.h @comment X/Open @item _SC_NZERO -Inquire value used to internally represent the zero priority level for +Inquire about the value used to internally represent the zero priority level for the process execution. @comment unistd.h @comment X/Open @item SC_SSIZE_MAX -Inquire about maximum value which can be stored in a variable of type +Inquire about the maximum value which can be stored in a variable of type @code{ssize_t}. @comment unistd.h @comment X/Open @item _SC_SCHAR_MAX -Inquire about maximum value which can be stored in a variable of type +Inquire about the maximum value which can be stored in a variable of type @code{signed char}. @comment unistd.h @comment X/Open @item _SC_SCHAR_MIN -Inquire about minimum value which can be stored in a variable of type +Inquire about the minimum value which can be stored in a variable of type @code{signed char}. @comment unistd.h @comment X/Open @item _SC_SHRT_MAX -Inquire about maximum value which can be stored in a variable of type +Inquire about the maximum value which can be stored in a variable of type @code{short int}. @comment unistd.h @comment X/Open @item _SC_SHRT_MIN -Inquire about minimum value which can be stored in a variable of type +Inquire about the minimum value which can be stored in a variable of type @code{short int}. @comment unistd.h @comment X/Open @item _SC_UCHAR_MAX -Inquire about maximum value which can be stored in a variable of type +Inquire about the maximum value which can be stored in a variable of type @code{unsigned char}. @comment unistd.h @comment X/Open @item _SC_UINT_MAX -Inquire about maximum value which can be stored in a variable of type +Inquire about the maximum value which can be stored in a variable of type @code{unsigned int}. @comment unistd.h @comment X/Open @item _SC_ULONG_MAX -Inquire about maximum value which can be stored in a variable of type +Inquire about the maximum value which can be stored in a variable of type @code{unsigned long int}. @comment unistd.h @comment X/Open @item _SC_USHRT_MAX -Inquire about maximum value which can be stored in a variable of type +Inquire about the maximum value which can be stored in a variable of type @code{unsigned short int}. @comment unistd.h @@ -956,12 +956,12 @@ Inquire about the parameter corresponding to @code{NL_NMAX}. @comment unistd.h @comment X/Open @item _SC_NL_SETMAX -Inquire about the parameter corresponding to @code{NL_SETMAX}. +Inquire about the parameter corresponding to @code{NL_SETMAX}. @comment unistd.h @comment X/Open @item _SC_NL_TEXTMAX -Inquire about the parameter corresponding to @code{NL_TEXTMAX}. +Inquire about the parameter corresponding to @code{NL_TEXTMAX}. @end table @node Examples of Sysconf @@ -1023,7 +1023,7 @@ system you are using can go that far. The most restrictive limit permitted by POSIX for the maximum number of I/O operations that can be specified in a list I/O call. The value of this constant is @code{2}; thus you can add up to two new entries -of the list of outstandard operations. +of the list of outstanding operations. @comment limits.h @comment POSIX.1 @@ -1191,7 +1191,7 @@ that big! Use dynamic allocation (@pxref{Memory Allocation}) instead. POSIX defines certain system-specific options in the system calls for operating on files. Some systems support these options and others do not. Since these options are provided in the kernel, not in the -library, simply using the GNU C library does not guarantee any of these +library, simply using the GNU C library does not guarantee that any of these features is supported; it depends on the system you are using. They can also vary between file systems on a single machine. diff --git a/manual/contrib.texi b/manual/contrib.texi index 55f2edb..c339d2a 100644 --- a/manual/contrib.texi +++ b/manual/contrib.texi @@ -8,7 +8,7 @@ contributed or worked on by other people. @itemize @bullet @item -The @code{getopt} function and related code were written by +The @code{getopt} function and related code was written by Richard Stallman, @w{David J.} MacKenzie, and @w{Roland McGrath}. @item diff --git a/manual/filesys.texi b/manual/filesys.texi index 29f2075..88ff636 100644 --- a/manual/filesys.texi +++ b/manual/filesys.texi @@ -5,7 +5,7 @@ This chapter describes the GNU C library's functions for manipulating files. Unlike the input and output functions (@pxref{I/O on Streams}; @pxref{Low-Level I/O}), these functions are concerned with operating -on the files themselves, rather than on their contents. +on the files themselves rather than on their contents. Among the facilities described in this chapter are functions for examining or modifying directories, functions for renaming and deleting @@ -251,8 +251,8 @@ The only way you can tell that the directory entries belong to a single file is that they have the same value for the @code{d_fileno} field. -File attributes such as size, modification times, and the like are part -of the file itself, not any particular directory entry. @xref{File +File attributes such as size, modification times etc., are part of the +file itself, not of any particular directory entry. @xref{File Attributes}. @end deftp @@ -320,7 +320,7 @@ returns a pointer to a structure containing information about the file. This structure is statically allocated and can be rewritten by a subsequent call. -@strong{Portability Note:} On some systems, @code{readdir} may not +@strong{Portability Note:} On some systems @code{readdir} may not return entries for @file{.} and @file{..}, even though these are always valid file names in any directory. @xref{File Name Resolution}. @@ -343,9 +343,9 @@ value. Use @code{readdir_r} when this is critical. @deftypefun int readdir_r (DIR *@var{dirstream}, struct dirent *@var{entry}, struct dirent **@var{result}) This function is the reentrant version of @code{readdir}. Like @code{readdir} it returns the next entry from the directory. But to -prevent conflicts for simultaneously running threads the result is not -stored in some internal memory. Instead the argument @var{entry} has to -point to a place where the result is stored. +prevent conflicts between simultaneously running threads the result is +not stored in statically allocated memory. Instead the argument +@var{entry} points to a place to store the result. The return value is @code{0} in case the next entry was read successfully. In this case a pointer to the result is returned in @@ -357,14 +357,14 @@ the function returns a value indicating the error (as described for If there are no more directory entries, @code{readdir_r}'s return value is @code{0}, and *@var{result} is set to @code{NULL}. -@strong{Portability Note:} On some systems, @code{readdir_r} may not -return a terminated string as the file name even if no @code{d_reclen} -element is available in @code{struct dirent} and the file name as the -maximal allowed size. Modern systems all have the @code{d_reclen} field -and on old systems multi threading is not critical. In any case, there -is no such problem with the @code{readdir} function so that even on -systems without @code{d_reclen} field one could use multiple threads by -using external locking. +@strong{Portability Note:} On some systems @code{readdir_r} may not +return a NUL terminated string for the file name, even when there is no +@code{d_reclen} field in @code{struct dirent} and the file +name is the maximum allowed size. Modern systems all have the +@code{d_reclen} field, and on old systems multi-threading is not +critical. In any case there is no such problem with the @code{readdir} +function, so that even on systems without the @code{d_reclen} member one +could use multiple threads by using external locking. @end deftypefun @comment dirent.h @@ -443,38 +443,38 @@ closing and reopening the directory can invalidate values returned by A higher-level interface to the directory handling functions is the @code{scandir} function. With its help one can select a subset of the -entries in a directory, possibly sort them and get as the result a list -of names. +entries in a directory, possibly sort them and get a list of names as +the result. @comment dirent.h @comment BSD/SVID @deftypefun int scandir (const char *@var{dir}, struct dirent ***@var{namelist}, int (*@var{selector}) (const struct dirent *), int (*@var{cmp}) (const void *, const void *)) The @code{scandir} function scans the contents of the directory selected -by @var{dir}. The result in @var{namelist} is an array of pointers to +by @var{dir}. The result in *@var{namelist} is an array of pointers to structure of type @code{struct dirent} which describe all selected directory entries and which is allocated using @code{malloc}. Instead of always getting all directory entries returned, the user supplied function @var{selector} can be used to decide which entries are in the -result. Only the entries for which @var{selector} returns a nonzero +result. Only the entries for which @var{selector} returns a non-zero value are selected. -Finally the entries in the @var{namelist} are sorted using the user -supplied function @var{cmp}. The arguments of the @var{cmp} function -are of type @code{struct dirent **}. I.e., one cannot directly use the -@code{strcmp} or @code{strcoll} function; see the functions -@code{alphasort} and @code{versionsort} below. +Finally the entries in *@var{namelist} are sorted using the +user-supplied function @var{cmp}. The arguments passed to the @var{cmp} +function are of type @code{struct dirent **}, therefore one cannot +directly use the @code{strcmp} or @code{strcoll} functions; instead see +the functions @code{alphasort} and @code{versionsort} below. -The return value of the function gives the number of entries placed in -@var{namelist}. If it is @code{-1} an error occurred (either the +The return value of the function is the number of entries placed in +*@var{namelist}. If it is @code{-1} an error occurred (either the directory could not be opened for reading or the malloc call failed) and the global variable @code{errno} contains more information on the error. @end deftypefun -As said above the fourth argument to the @code{scandir} function must be -a pointer to a sorting function. For the convenience of the programmer -the GNU C library contains implementations of functions which are very -helpful for this purpose. +As described above the fourth argument to the @code{scandir} function +must be a pointer to a sorting function. For the convenience of the +programmer the GNU C library contains implementations of functions which +are very helpful for this purpose. @comment dirent.h @comment BSD/SVID @@ -484,14 +484,14 @@ The @code{alphasort} function behaves like the @code{strcoll} function are not string pointers but instead they are of type @code{struct dirent **}. -Return value of @code{alphasort} is less than, equal to, or greater than -zero depending on the order of the two entries @var{a} and @var{b}. +The return value of @code{alphasort} is less than, equal to, or greater +than zero depending on the order of the two entries @var{a} and @var{b}. @end deftypefun @comment dirent.h @comment GNU @deftypefun int versionsort (const void *@var{a}, const void *@var{b}) -The @code{versionsort} function is like @code{alphasort}, excepted that it +The @code{versionsort} function is like @code{alphasort} except that it uses the @code{strverscmp} function internally. @end deftypefun @@ -504,20 +504,19 @@ dirent64}}. To use this we need a new function. @comment GNU @deftypefun int scandir64 (const char *@var{dir}, struct dirent64 ***@var{namelist}, int (*@var{selector}) (const struct dirent64 *), int (*@var{cmp}) (const void *, const void *)) The @code{scandir64} function works like the @code{scandir} function -only that the directory entries it returns are described by elements of -type @w{@code{struct dirent64}}. The function pointed to by -@var{selector} is again used to select the wanted entries only that +except that the directory entries it returns are described by elements +of type @w{@code{struct dirent64}}. The function pointed to by +@var{selector} is again used to select the desired entries, except that @var{selector} now must point to a function which takes a @w{@code{struct dirent64 *}} parameter. -The @var{cmp} now must be a function which expects its two arguments to -be of type @code{struct dirent64 **}. +Similarly the @var{cmp} function should expect its two arguments to be +of type @code{struct dirent64 **}. @end deftypefun -As just said the function expected as the fourth is different from the -function expected in @code{scandir}. Therefore we cannot use the -@code{alphasort} and @code{versionsort} functions anymore. Instead we -have two similar functions available. +As @var{cmp} is now a function of a different type, the functions +@code{alphasort} and @code{versionsort} cannot be supplied for that +argument. Instead we provide the two replacement functions below. @comment dirent.h @comment GNU @@ -538,7 +537,7 @@ The @code{versionsort64} function is like @code{alphasort64}, excepted that it uses the @code{strverscmp} function internally. @end deftypefun -It is important not to mix the use of @code{scandir} and the 64 bits +It is important not to mix the use of @code{scandir} and the 64-bit comparison functions or vice versa. There are systems on which this works but on others it will fail miserably. @@ -547,35 +546,37 @@ works but on others it will fail miserably. Here is a revised version of the directory lister found above (@pxref{Simple Directory Lister}). Using the @code{scandir} function we -can avoid using the functions which directly work with the directory -contents. After the call the found entries are available for direct -used. +can avoid the functions which work directly with the directory contents. +After the call the returned entries are available for direct use. @smallexample @include dir2.c.texi @end smallexample -Please note the simple selector function for this example. Since -we want to see all directory entries we always return @code{1}. +Note the simple selector function in this example. Since we want to see +all directory entries we always return @code{1}. -@node Working on Directory Trees -@section Working on Directory Trees +@node Working with Directory Trees +@section Working with Directory Trees @cindex directory hierarchy @cindex hierarchy, directory @cindex tree, directory -The functions to handle files in directories described so far allowed to -retrieve all the information in small pieces or process all files in a -directory (see @code{scandir}). Sometimes it is useful to process whole -hierarchies of directories and the contained files. The X/Open -specification define two functions to do this. The simpler form is -derived from an early definition in @w{System V} systems and therefore -this function is available on SVID derived systems. The prototypes and -required definitions can be found in the @file{ftw.h} header. - -Both functions of this @code{ftw} family take as one of the arguments a -reference to a callback function. The functions must be of these types. +The functions described so far for handling the files in a directory +have allowed you to either retrieve the information bit by bit, or to +process all the files as a group (see @code{scandir}). Sometimes it is +useful to process whole hierarchies of directories and their contained +files. The X/Open specification defines two functions to do this. The +simpler form is derived from an early definition in @w{System V} systems +and therefore this function is available on SVID-derived systems. The +prototypes and required definitions can be found in the @file{ftw.h} +header. + +There are four functions in this family: @code{ftw}, @code{nftw} and +their 64-bit counterparts @code{ftw64} and @code{nftw64}. These +functions take as one of their arguments a pointer to a callback +function of the appropriate type. @comment ftw.h @comment GNU @@ -585,25 +586,24 @@ reference to a callback function. The functions must be of these types. int (*) (const char *, const struct stat *, int) @end smallexample -Type for callback functions given to the @code{ftw} function. The first -parameter will contain a pointer to the filename, the second parameter -will point to an object of type @code{struct stat} which will be filled -for the file named by the first parameter. +The type of callback functions given to the @code{ftw} function. The +first parameter points to the file name, the second parameter to an +object of type @code{struct stat} which is filled in for the file named +in the first parameter. @noindent -The last parameter is a flag given more information about the current +The last parameter is a flag giving more information about the current file. It can have the following values: @vtable @code @item FTW_F -The current item is a normal file or files which do not fit into one of -the following categories. This means especially special files, sockets -etc. +The item is either a normal file or a file which does not fit into one +of the following categories. This could be special files, sockets etc. @item FTW_D -The current item is a directory. +The item is a directory. @item FTW_NS -The @code{stat} call to fill the object pointed to by the second -parameter failed and so the information is invalid. +The @code{stat} call failed and so the information pointed to by the +second paramater is invalid. @item FTW_DNR The item is a directory which cannot be read. @item FTW_SL @@ -617,11 +617,11 @@ the first header. The original SVID systems do not have symbolic links. @end vtable If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this -type is in fact @code{__ftw64_func_t} since this mode also changes +type is in fact @code{__ftw64_func_t} since this mode changes @code{struct stat} to be @code{struct stat64}. @end deftp -For the LFS interface and the use in the function @code{ftw64} the +For the LFS interface and for use in the function @code{ftw64}, the header @file{ftw.h} defines another function type. @comment ftw.h @@ -633,8 +633,8 @@ int (*) (const char *, const struct stat64 *, int) @end smallexample This type is used just like @code{__ftw_func_t} for the callback -function, but this time called from @code{ftw64}. The second parameter -to the function is this time a pointer to a variable of type +function, but this time is called from @code{ftw64}. The second +parameter to the function is a pointer to a variable of type @code{struct stat64} which is able to represent the larger values. @end deftp @@ -648,14 +648,14 @@ int (*) (const char *, const struct stat *, int, struct FTW *) @vindex FTW_DP @vindex FTW_SLN -The first three arguments have the same as for the @code{__ftw_func_t} -type. A difference is that for the third argument some additional -values are defined to allow finer differentiation: +The first three arguments are the same as for the @code{__ftw_func_t} +type. However for the third argument some additional values are defined +to allow finer differentiation: @table @code @item FTW_DP The current item is a directory and all subdirectories have already been visited and reported. This flag is returned instead of @code{FTW_D} if -the @code{FTW_DEPTH} flag is given to @code{nftw} (see below). +the @code{FTW_DEPTH} flag is passed to @code{nftw} (see below). @item FTW_SLN The current item is a stale symbolic link. The file it points to does not exist. @@ -665,7 +665,7 @@ The last parameter of the callback function is a pointer to a structure with some extra information as described below. If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this -type is in fact @code{__nftw64_func_t} since this mode also changes +type is in fact @code{__nftw64_func_t} since this mode changes @code{struct stat} to be @code{struct stat64}. @end deftp @@ -681,31 +681,31 @@ int (*) (const char *, const struct stat64 *, int, struct FTW *) @end smallexample This type is used just like @code{__nftw_func_t} for the callback -function, but this time called from @code{nftw64}. The second parameter -to the function is this time a pointer to a variable of type +function, but this time is called from @code{nftw64}. The second +parameter to the function is this time a pointer to a variable of type @code{struct stat64} which is able to represent the larger values. @end deftp @comment ftw.h @comment XPG4.2 @deftp {Data Type} {struct FTW} -The contained information helps to interpret the name parameter and -gives some information about current state of the traversal of the -directory hierarchy. +The information contained in this structure helps in interpreting the +name parameter and gives some information about the current state of the +traversal of the directory hierarchy. @table @code @item int base -The value specifies which part of the filename argument given in the -first parameter to the callback function is the name of the file. The -rest of the string is the path to locate the file. This information is -especially important if the @code{FTW_CHDIR} flag for @code{nftw} was -set since then the current directory is the one the current item is -found in. +The value is the offset into the string passed in the first parameter to +the callback function of the beginning of the file name. The rest of +the string is the path of the file. This information is especially +important if the @code{FTW_CHDIR} flag was set in calling @code{nftw} +since then the current directory is the one the current item is found +in. @item int level -While processing the directory the function tracks how many directories -have been examined to find the current item. This nesting level is -@math{0} for the item given starting item (file or directory) and is -incremented by one for each entered directory. +Whilst processing, the code tracks how many directories down it has gone +to find the current file. This nesting level starts at @math{0} for +files in the initial directory (or is zero for the initial file if a +file was passed). @end table @end deftp @@ -717,48 +717,46 @@ The @code{ftw} function calls the callback function given in the parameter @var{func} for every item which is found in the directory specified by @var{filename} and all directories below. The function follows symbolic links if necessary but does not process an item twice. -If @var{filename} names no directory this item is the only object -reported by calling the callback function. +If @var{filename} is not a directory then it itself is the only object +returned to the callback function. -The filename given to the callback function is constructed by taking the -@var{filename} parameter and appending the names of all passed +The file name passed to the callback function is constructed by taking +the @var{filename} parameter and appending the names of all passed directories and then the local file name. So the callback function can -use this parameter to access the file. Before the callback function is -called @code{ftw} calls @code{stat} for this file and passes the -information up to the callback function. If this @code{stat} call was -not successful the failure is indicated by setting the falg argument of -the callback function to @code{FTW_NS}. Otherwise the flag is set -according to the description given in the description of -@code{__ftw_func_t} above. +use this parameter to access the file. @code{ftw} also calls +@code{stat} for the file and passes that information on to the callback +function. If this @code{stat} call was not successful the failure is +indicated by setting the third argument of the callback function to +@code{FTW_NS}. Otherwise it is set according to the description given +in the account of @code{__ftw_func_t} above. The callback function is expected to return @math{0} to indicate that no -error occurred and the processing should be continued. If an error -occurred in the callback function or the call to @code{ftw} shall return -immediately the callback function can return a value other than +error occurred and that processing should continue. If an error +occurred in the callback function or it wants @code{ftw} to return +immediately, the callback function can return a value other than @math{0}. This is the only correct way to stop the function. The -program must not use @code{setjmp} or similar techniques to continue the -program in another place. This would leave the resources allocated in -the @code{ftw} function allocated. - -The @var{descriptors} parameter to the @code{ftw} function specifies how -many file descriptors the @code{ftw} function is allowed to consume. -The more descriptors can be used the faster the function can run. For -each level of directories at most one descriptor is used so that for -very deep directory hierarchies the limit on open file descriptors for -the process or the system can be exceeded. Beside this the limit on -file descriptors is counted together for all threads in a multi-threaded -program and therefore it is always good too limit the maximal number of -open descriptors to a reasonable number. +program must not use @code{setjmp} or similar techniques to continue +from another place. This would leave resources allocated by the +@code{ftw} function unfreed. + +The @var{descriptors} parameter to @code{ftw} specifies how many file +descriptors it is allowed to consume. The function runs faster the more +descriptors it can use. For each level in the directory hierarchy at +most one descriptor is used, but for very deep ones any limit on open +file descriptors for the process or the system may be exceeded. +Moreover, file descriptor limits in a multi-threaded program apply to +all the threads as a group, and therefore it is a good idea to supply a +reasonable limit to the number of open descriptors. The return value of the @code{ftw} function is @math{0} if all callback function calls returned @math{0} and all actions performed by the -@code{ftw} succeeded. If some function call failed (other than calling -@code{stat} on an item) the function return @math{-1}. If a callback +@code{ftw} succeeded. If a function call failed (other than calling +@code{stat} on an item) the function returns @math{-1}. If a callback function returns a value other than @math{0} this value is returned as the return value of @code{ftw}. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bits system this function is in fact @code{ftw64}. I.e., the LFS +32-bit system this function is in fact @code{ftw64}, i.e. the LFS interface transparently replaces the old interface. @end deftypefun @@ -766,63 +764,61 @@ interface transparently replaces the old interface. @comment Unix98 @deftypefun int ftw64 (const char *@var{filename}, __ftw64_func_t @var{func}, int @var{descriptors}) This function is similar to @code{ftw} but it can work on filesystems -with large files since the information about the files is reported using -a variable of type @code{struct stat64} which is passed by reference to -the callback function. +with large files. File information is reported using a variable of type +@code{struct stat64} which is passed by reference to the callback +function. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bits system this function is available under the name @code{ftw} and +32-bit system this function is available under the name @code{ftw} and transparently replaces the old implementation. @end deftypefun @comment ftw.h @comment XPG4.2 @deftypefun int nftw (const char *@var{filename}, __nftw_func_t @var{func}, int @var{descriptors}, int @var{flag}) -The @code{nftw} functions works like the @code{ftw} functions. It calls -the callback function @var{func} for all items it finds in the directory +The @code{nftw} function works like the @code{ftw} functions. They call +the callback function @var{func} for all items found in the directory @var{filename} and below. At most @var{descriptors} file descriptors are consumed during the @code{nftw} call. -The differences are that for one the callback function is of a different -type. It is of type @w{@code{struct FTW *}} and provides the callback -functions the information described above. +One difference is that the callback function is of a different type. It +is of type @w{@code{struct FTW *}} and provides the callback function +with the extra information described above. -The second difference is that @code{nftw} takes an additional fourth -argument which is @math{0} or a combination of any of the following -values, combined using bitwise OR. +A second difference is that @code{nftw} takes a fourth argument, which +is @math{0} or a bitwise-OR combination of any of the following values. @vtable @code @item FTW_PHYS -While traversing the directory symbolic links are not followed. I.e., -if this flag is given symbolic links are reported using the -@code{FTW_SL} value for the type parameter to the callback function. -Please note that if this flag is used the appearance of @code{FTW_SL} in -a callback function does not mean the referenced file does not exist. -To indicate this the extra value @code{FTW_SLN} exists. +While traversing the directory symbolic links are not followed. Instead +symbolic links are reported using the @code{FTW_SL} value for the type +parameter to the callback function. If the file referenced by a +symbolic link does not exist {FTW_SLN} is returned instead. @item FTW_MOUNT The callback function is only called for items which are on the same -mounted filesystem as the directory given as the @var{filename} +mounted filesystem as the directory given by the @var{filename} parameter to @code{nftw}. @item FTW_CHDIR If this flag is given the current working directory is changed to the -directory containing the reported object before the callback function is -called. +directory of the reported object before the callback function is called. +When @code{ntfw} finally returns the current directory is restored to +its original value. @item FTW_DEPTH -If this option is given the function visits first all files and -subdirectories before the callback function is called for the directory -itself (depth-first processing). This also means the type flag given to -the callback function is @code{FTW_DP} and not @code{FTW_D}. +If this option is specified then all subdirectories and files within +them are processed before processing the top directory itself +(depth-first processing). This also means the type flag given to the +callback function is @code{FTW_DP} and not @code{FTW_D}. @end vtable The return value is computed in the same way as for @code{ftw}. -@code{nftw} return @math{0} if no failure occurred in @code{nftw} and -all callback function call return values are also @math{0}. For -internal errors such as memory problems @math{-1} is returned and -@var{errno} is set accordingly. If the return value of a callback -invocation is nonzero this very same value is returned. +@code{nftw} returns @math{0} if no failures occurred and all callback +functions returned @math{0}. In case of internal errors, such as memory +problems, the return value is @math{-1} and @var{errno} is set +accordingly. If the return value of a callback invocation was non-zero +then that value is returned. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bits system this function is in fact @code{nftw64}. I.e., the LFS +32-bit system this function is in fact @code{nftw64}, i.e. the LFS interface transparently replaces the old interface. @end deftypefun @@ -830,12 +826,12 @@ interface transparently replaces the old interface. @comment Unix98 @deftypefun int nftw64 (const char *@var{filename}, __nftw64_func_t @var{func}, int @var{descriptors}, int @var{flag}) This function is similar to @code{nftw} but it can work on filesystems -with large files since the information about the files is reported using -a variable of type @code{struct stat64} which is passed by reference to -the callback function. +with large files. File information is reported using a variable of type +@code{struct stat64} which is passed by reference to the callback +function. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bits system this function is available under the name @code{nftw} and +32-bit system this function is available under the name @code{nftw} and transparently replaces the old implementation. @end deftypefun @@ -882,8 +878,8 @@ following @code{errno} error conditions are defined for this function: @table @code @item EACCES -You are not allowed to write the directory in which the new link is to -be written. +You are not allowed to write to the directory in which the new link is +to be written. @ignore Some implementations also require that the existing file be accessible by the caller, and use this error to report failure for that reason. @@ -951,8 +947,8 @@ of on the link itself. By contrast, other operations such as deleting or renaming the file operate on the link itself. The functions @code{readlink} and @code{lstat} also refrain from following symbolic links, because their -purpose is to obtain information about the link. So does @code{link}, -the function that makes a hard link---it makes a hard link to the +purpose is to obtain information about the link. @code{link}, the +function that makes a hard link, does too. It makes a hard link to the symbolic link, which one rarely wants. Prototypes for the functions listed in this section are in @@ -1049,11 +1045,11 @@ A hardware error occurred while reading or writing data on the disk. @cindex removing a file @cindex unlinking a file -You can delete a file with the functions @code{unlink} or @code{remove}. +You can delete a file with @code{unlink} or @code{remove}. Deletion actually deletes a file name. If this is the file's only name, -then the file is deleted as well. If the file has other names as well -(@pxref{Hard Links}), it remains accessible under its other names. +then the file is deleted as well. If the file has other remaining names +(@pxref{Hard Links}), it remains accessible under those names. @comment unistd.h @comment POSIX.1 @@ -1086,14 +1082,14 @@ system. The file name to be deleted doesn't exist. @item EPERM -On some systems, @code{unlink} cannot be used to delete the name of a -directory, or can only be used this way by a privileged user. -To avoid such problems, use @code{rmdir} to delete directories. -(In the GNU system @code{unlink} can never delete the name of a directory.) +On some systems @code{unlink} cannot be used to delete the name of a +directory, or at least can only be used this way by a privileged user. +To avoid such problems, use @code{rmdir} to delete directories. (In the +GNU system @code{unlink} can never delete the name of a directory.) @item EROFS -The directory in which the file name is to be deleted is on a read-only -file system, and can't be modified. +The directory containing the file name to be deleted is on a read-only +file system and can't be modified. @end table @end deftypefun @@ -1142,40 +1138,39 @@ The @code{rename} function is used to change a file's name. @comment stdio.h @comment ISO @deftypefun int rename (const char *@var{oldname}, const char *@var{newname}) -The @code{rename} function renames the file name @var{oldname} with +The @code{rename} function renames the file @var{oldname} to @var{newname}. The file formerly accessible under the name -@var{oldname} is afterward accessible as @var{newname} instead. (If the -file had any other names aside from @var{oldname}, it continues to have -those names.) +@var{oldname} is afterwards accessible as @var{newname} instead. (If +the file had any other names aside from @var{oldname}, it continues to +have those names.) -The directory containing the name @var{newname} must be on the same -file system as the file (as indicated by the name @var{oldname}). +The directory containing the name @var{newname} must be on the same file +system as the directory containing the name @var{oldname}. One special case for @code{rename} is when @var{oldname} and @var{newname} are two names for the same file. The consistent way to -handle this case is to delete @var{oldname}. However, POSIX requires -that in this case @code{rename} do nothing and report success---which is -inconsistent. We don't know what your operating system will do. +handle this case is to delete @var{oldname}. However, in this case +POSIX requires that @code{rename} do nothing and report success---which +is inconsistent. We don't know what your operating system will do. -If the @var{oldname} is not a directory, then any existing file named +If @var{oldname} is not a directory, then any existing file named @var{newname} is removed during the renaming operation. However, if @var{newname} is the name of a directory, @code{rename} fails in this case. -If the @var{oldname} is a directory, then either @var{newname} must not +If @var{oldname} is a directory, then either @var{newname} must not exist or it must name a directory that is empty. In the latter case, the existing directory named @var{newname} is deleted first. The name @var{newname} must not specify a subdirectory of the directory @code{oldname} which is being renamed. -One useful feature of @code{rename} is that the meaning of the name -@var{newname} changes ``atomically'' from any previously existing file -by that name to its new meaning (the file that was called -@var{oldname}). There is no instant at which @var{newname} is -nonexistent ``in between'' the old meaning and the new meaning. If -there is a system crash during the operation, it is possible for both -names to still exist; but @var{newname} will always be intact if it -exists at all. +One useful feature of @code{rename} is that the meaning of @var{newname} +changes ``atomically'' from any previously existing file by that name to +its new meaning (i.e. the file that was called @var{oldname}). There is +no instant at which @var{newname} is non-existent ``in between'' the old +meaning and the new meaning. If there is a system crash during the +operation, it is possible for both names to still exist; but +@var{newname} will always be intact if it exists at all. If @code{rename} fails, it returns @code{-1}. In addition to the usual file name errors (@pxref{File Name Errors}), the following @@ -1199,16 +1194,17 @@ The directory @var{newname} isn't empty. The GNU system always returns @code{ENOTEMPTY} for this, but some other systems return @code{EEXIST}. @item EINVAL -The @var{oldname} is a directory that contains @var{newname}. +@var{oldname} is a directory that contains @var{newname}. @item EISDIR -The @var{newname} names a directory, but the @var{oldname} doesn't. +@var{newname} is a directory but the @var{oldname} isn't. @item EMLINK -The parent directory of @var{newname} would have too many links. +The parent directory of @var{newname} would have too many links +(entries). @item ENOENT -The file named by @var{oldname} doesn't exist. +The file @var{oldname} doesn't exist. @item ENOSPC The directory that would contain @var{newname} has no room for another @@ -1219,7 +1215,7 @@ The operation would involve writing to a directory on a read-only file system. @item EXDEV -The two file names @var{newname} and @var{oldnames} are on different +The two file names @var{newname} and @var{oldname} are on different file systems. @end table @end deftypefun @@ -1237,7 +1233,7 @@ a shell command @code{mkdir} which does the same thing.) @comment sys/stat.h @comment POSIX.1 @deftypefun int mkdir (const char *@var{filename}, mode_t @var{mode}) -The @code{mkdir} function creates a new, empty directory whose name is +The @code{mkdir} function creates a new, empty directory with name @var{filename}. The argument @var{mode} specifies the file permissions for the new @@ -1258,7 +1254,7 @@ directory is to be added. A file named @var{filename} already exists. @item EMLINK -The parent directory has too many links. +The parent directory has too many links (entries). Well-designed file systems never report this error, because they permit more links than your disk could possibly hold. However, you must still @@ -1270,7 +1266,7 @@ The file system doesn't have enough room to create the new directory. @item EROFS The parent directory of the directory being created is on a read-only -file system, and cannot be modified. +file system and cannot be modified. @end table To use this function, your program should include the header file @@ -1284,12 +1280,11 @@ To use this function, your program should include the header file @pindex ls When you issue an @samp{ls -l} shell command on a file, it gives you information about the size of the file, who owns it, when it was last -modified, and the like. This kind of information is called the -@dfn{file attributes}; it is associated with the file itself and not a -particular one of its names. +modified, etc. These are called the @dfn{file attributes}, and are +associated with the file itself and not a particular one of its names. This section contains information about how you can inquire about and -modify these attributes of files. +modify the attributes of a file. @menu * Attribute Meanings:: The names of the file attributes, @@ -1311,7 +1306,7 @@ modify these attributes of files. @end menu @node Attribute Meanings -@subsection What the File Attribute Values Mean +@subsection The meaning of the File Attributes @cindex status of a file @cindex attributes of a file @cindex file attributes @@ -1361,10 +1356,9 @@ The user ID of the file's owner. @xref{File Owner}. The group ID of the file. @xref{File Owner}. @item off_t st_size -This specifies the size of a regular file in bytes. For files that -are really devices and the like, this field isn't usually meaningful. -For symbolic links, this specifies the length of the file name the link -refers to. +This specifies the size of a regular file in bytes. For files that are +really devices this field isn't usually meaningful. For symbolic links +this specifies the length of the file name the link refers to. @item time_t st_atime This is the last access time for the file. @xref{File Times}. @@ -1378,7 +1372,7 @@ This is the time of the last modification to the contents of the file. @xref{File Times}. @item unsigned long int st_mtime_usec -This is the fractional part of the time of last modification to the +This is the fractional part of the time of the last modification to the contents of the file. @xref{File Times}. @item time_t st_ctime @@ -1386,7 +1380,7 @@ This is the time of the last modification to the attributes of the file. @xref{File Times}. @item unsigned long int st_ctime_usec -This is the fractional part of the time of last modification to the +This is the fractional part of the time of the last modification to the attributes of the file. @xref{File Times}. @c !!! st_rdev @@ -1418,9 +1412,9 @@ writing the file. (This is unrelated to @code{st_blocks}.) @end table @end deftp -The extensions for the Large File Support (LFS) require even on 32 bits -machine types which can handle file sizes up to @math{2^63}. Therefore -a new definition of @code{struct stat} is necessary. +The extensions for the Large File Support (LFS) require, even on 32-bit +machines, types which can handle file sizes up to @math{2^63}. +Therefore a new definition of @code{struct stat} is necessary. @comment sys/stat.h @comment LFS @@ -1460,10 +1454,9 @@ The user ID of the file's owner. @xref{File Owner}. The group ID of the file. @xref{File Owner}. @item off64_t st_size -This specifies the size of a regular file in bytes. For files that -are really devices and the like, this field isn't usually meaningful. -For symbolic links, this specifies the length of the file name the link -refers to. +This specifies the size of a regular file in bytes. For files that are +really devices this field isn't usually meaningful. For symbolic links +this specifies the length of the file name the link refers to. @item time_t st_atime This is the last access time for the file. @xref{File Times}. @@ -1477,7 +1470,7 @@ This is the time of the last modification to the contents of the file. @xref{File Times}. @item unsigned long int st_mtime_usec -This is the fractional part of the time of last modification to the +This is the fractional part of the time of the last modification to the contents of the file. @xref{File Times}. @item time_t st_ctime @@ -1485,7 +1478,7 @@ This is the time of the last modification to the attributes of the file. @xref{File Times}. @item unsigned long int st_ctime_usec -This is the fractional part of the time of last modification to the +This is the fractional part of the time of the last modification to the attributes of the file. @xref{File Times}. @c !!! st_rdev @@ -1583,15 +1576,15 @@ header file @file{sys/stat.h}. @comment POSIX.1 @deftypefun int stat (const char *@var{filename}, struct stat *@var{buf}) The @code{stat} function returns information about the attributes of the -file named by @w{@var{filename}} in the structure pointed at by @var{buf}. +file named by @w{@var{filename}} in the structure pointed to by @var{buf}. If @var{filename} is the name of a symbolic link, the attributes you get describe the file that the link points to. If the link points to a -nonexistent file name, then @code{stat} fails, reporting a nonexistent +nonexistent file name, then @code{stat} fails reporting a nonexistent file. -The return value is @code{0} if the operation is successful, and @code{-1} -on failure. In addition to the usual file name errors +The return value is @code{0} if the operation is successful, or +@code{-1} on failure. In addition to the usual file name errors (@pxref{File Name Errors}, the following @code{errno} error conditions are defined for this function: @@ -1609,13 +1602,13 @@ replaces the normal implementation. @comment Unix98 @deftypefun int stat64 (const char *@var{filename}, struct stat64 *@var{buf}) This function is similar to @code{stat} but it is also able to work on -file larger then @math{2^31} bytes on 32 bits systems. To be able to do +files larger then @math{2^31} bytes on 32-bit systems. To be able to do this the result is stored in a variable of type @code{struct stat64} to which @var{buf} must point. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this function is available under the name @code{stat} and so transparently -replaces the interface for small fiels on 32 bits machines. +replaces the interface for small files on 32-bit machines. @end deftypefun @comment sys/stat.h @@ -1642,15 +1635,15 @@ replaces the normal implementation. @comment sys/stat.h @comment Unix98 @deftypefun int fstat64 (int @var{filedes}, struct stat64 *@var{buf}) -This function is similar to @code{fstat} but it is prepared to work on -large files on 32 bits platforms. For large files the file descriptor -@var{filedes} should be returned by @code{open64} or @code{creat64}. +This function is similar to @code{fstat} but is able to work on large +files on 32-bit platforms. For large files the file descriptor +@var{filedes} should be obtained by @code{open64} or @code{creat64}. The @var{buf} pointer points to a variable of type @code{struct stat64} which is able to represent the larger values. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this function is available under the name @code{fstat} and so transparently -replaces the interface for small fiels on 32 bits machines. +replaces the interface for small files on 32-bit machines. @end deftypefun @comment sys/stat.h @@ -1658,7 +1651,7 @@ replaces the interface for small fiels on 32 bits machines. @deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf}) The @code{lstat} function is like @code{stat}, except that it does not follow symbolic links. If @var{filename} is the name of a symbolic -link, @code{lstat} returns information about the link itself; otherwise, +link, @code{lstat} returns information about the link itself; otherwise @code{lstat} works like @code{stat}. @xref{Symbolic Links}. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this @@ -1670,13 +1663,13 @@ replaces the normal implementation. @comment Unix98 @deftypefun int lstat64 (const char *@var{filename}, struct stat64 *@var{buf}) This function is similar to @code{lstat} but it is also able to work on -file larger then @math{2^31} bytes on 32 bits systems. To be able to do +files larger then @math{2^31} bytes on 32-bit systems. To be able to do this the result is stored in a variable of type @code{struct stat64} to which @var{buf} must point. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this function is available under the name @code{lstat} and so transparently -replaces the interface for small fiels on 32 bits machines. +replaces the interface for small files on 32-bit machines. @end deftypefun @node Testing File Type @@ -1685,17 +1678,16 @@ replaces the interface for small fiels on 32 bits machines. The @dfn{file mode}, stored in the @code{st_mode} field of the file attributes, contains two kinds of information: the file type code, and the access permission bits. This section discusses only the type code, -which you can use to tell whether the file is a directory, whether it is -a socket, and so on. For information about the access permission, +which you can use to tell whether the file is a directory, socket, +symbolic link, and so on. For details about access permissions see @ref{Permission Bits}. -There are two predefined ways you can access the file type portion of -the file mode. First of all, for each type of file, there is a -@dfn{predicate macro} which examines a file mode value and returns -true or false---is the file of that type, or not. Secondly, you can -mask out the rest of the file mode to get just a file type code. -You can compare this against various constants for the supported file -types. +There are two ways you can access the file type information in a file +mode. Firstly, for each file type there is a @dfn{predicate macro} +which examines a given file mode and returns whether it is of that type +or not. Secondly, you can mask out the rest of the file mode to leave +just the file type code, and compare this against constants for each of +the supported file types. All of the symbols listed in this section are defined in the header file @file{sys/stat.h}. @@ -1708,53 +1700,53 @@ that file: @comment sys/stat.h @comment POSIX @deftypefn Macro int S_ISDIR (mode_t @var{m}) -This macro returns nonzero if the file is a directory. +This macro returns non-zero if the file is a directory. @end deftypefn @comment sys/stat.h @comment POSIX @deftypefn Macro int S_ISCHR (mode_t @var{m}) -This macro returns nonzero if the file is a character special file (a +This macro returns non-zero if the file is a character special file (a device like a terminal). @end deftypefn @comment sys/stat.h @comment POSIX @deftypefn Macro int S_ISBLK (mode_t @var{m}) -This macro returns nonzero if the file is a block special file (a device +This macro returns non-zero if the file is a block special file (a device like a disk). @end deftypefn @comment sys/stat.h @comment POSIX @deftypefn Macro int S_ISREG (mode_t @var{m}) -This macro returns nonzero if the file is a regular file. +This macro returns non-zero if the file is a regular file. @end deftypefn @comment sys/stat.h @comment POSIX @deftypefn Macro int S_ISFIFO (mode_t @var{m}) -This macro returns nonzero if the file is a FIFO special file, or a +This macro returns non-zero if the file is a FIFO special file, or a pipe. @xref{Pipes and FIFOs}. @end deftypefn @comment sys/stat.h @comment GNU @deftypefn Macro int S_ISLNK (mode_t @var{m}) -This macro returns nonzero if the file is a symbolic link. +This macro returns non-zero if the file is a symbolic link. @xref{Symbolic Links}. @end deftypefn @comment sys/stat.h @comment GNU @deftypefn Macro int S_ISSOCK (mode_t @var{m}) -This macro returns nonzero if the file is a socket. @xref{Sockets}. +This macro returns non-zero if the file is a socket. @xref{Sockets}. @end deftypefn An alternate non-POSIX method of testing the file type is supported for -compatibility with BSD. The mode can be bitwise ANDed with +compatibility with BSD. The mode can be bitwise AND-ed with @code{S_IFMT} to extract the file type code, and compared to the -appropriate type code constant. For example, +appropriate constant. For example, @smallexample S_ISCHR (@var{mode}) @@ -1770,8 +1762,7 @@ is equivalent to: @comment sys/stat.h @comment BSD @deftypevr Macro int S_IFMT -This is a bit mask used to extract the file type code portion of a mode -value. +This is a bit mask used to extract the file type code from a mode value. @end deftypevr These are the symbolic names for the different file type codes: @@ -1781,45 +1772,43 @@ These are the symbolic names for the different file type codes: @comment BSD @item S_IFDIR @vindex S_IFDIR -This macro represents the value of the file type code for a directory file. +This is the file type constant of a directory file. @comment sys/stat.h @comment BSD @item S_IFCHR @vindex S_IFCHR -This macro represents the value of the file type code for a -character-oriented device file. +This is the file type constant of a character-oriented device file. @comment sys/stat.h @comment BSD @item S_IFBLK @vindex S_IFBLK -This macro represents the value of the file type code for a block-oriented -device file. +This is the file type constant of a block-oriented device file. @comment sys/stat.h @comment BSD @item S_IFREG @vindex S_IFREG -This macro represents the value of the file type code for a regular file. +This is the file type constant of a regular file. @comment sys/stat.h @comment BSD @item S_IFLNK @vindex S_IFLNK -This macro represents the value of the file type code for a symbolic link. +This is the file type constant of a symbolic link. @comment sys/stat.h @comment BSD @item S_IFSOCK @vindex S_IFSOCK -This macro represents the value of the file type code for a socket. +This is the file type constant of a socket. @comment sys/stat.h @comment BSD @item S_IFIFO @vindex S_IFIFO -This macro represents the value of the file type code for a FIFO or pipe. +This is the file type constant of a FIFO or pipe. @end table @node File Owner @@ -1829,26 +1818,25 @@ This macro represents the value of the file type code for a FIFO or pipe. @cindex group owner of a file Every file has an @dfn{owner} which is one of the registered user names -defined on the system. Each file also has a @dfn{group}, which is one -of the defined groups. The file owner can often be useful for showing -you who edited the file (especially when you edit with GNU Emacs), but -its main purpose is for access control. +defined on the system. Each file also has a @dfn{group} which is one of +the defined groups. The file owner can often be useful for showing you +who edited the file (especially when you edit with GNU Emacs), but its +main purpose is for access control. The file owner and group play a role in determining access because the -file has one set of access permission bits for the user that is the -owner, another set that apply to users who belong to the file's group, -and a third set of bits that apply to everyone else. @xref{Access -Permission}, for the details of how access is decided based on this -data. - -When a file is created, its owner is set from the effective user ID of -the process that creates it (@pxref{Process Persona}). The file's group -ID may be set from either effective group ID of the process, or the -group ID of the directory that contains the file, depending on the -system where the file is stored. When you access a remote file system, -it behaves according to its own rule, not according to the system your +file has one set of access permission bits for the owner, another set +that applies to users who belong to the file's group, and a third set of +bits that applies to everyone else. @xref{Access Permission} for the +details of how access is decided based on this data. + +When a file is created, its owner is set to the effective user ID of the +process that creates it (@pxref{Process Persona}). The file's group ID +may be set to either the effective group ID of the process, or the group +ID of the directory that contains the file, depending on the system +where the file is stored. When you access a remote file system, it +behaves according to its own rules, not according to the system your program is running on. Thus, your program must be prepared to encounter -either kind of behavior, no matter what kind of system you run it on. +either kind of behavior no matter what kind of system you run it on. @pindex chown @pindex chgrp @@ -1866,9 +1854,9 @@ The @code{chown} function changes the owner of the file @var{filename} to @var{owner}, and its group owner to @var{group}. Changing the owner of the file on certain systems clears the set-user-ID -and set-group-ID bits of the file's permissions. (This is because those -bits may not be appropriate for the new owner.) The other file -permission bits are not changed. +and set-group-ID permission bits. (This is because those bits may not +be appropriate for the new owner.) Other file permission bits are not +changed. The return value is @code{0} on success and @code{-1} on failure. In addition to the usual file name errors (@pxref{File Name Errors}), @@ -1896,8 +1884,8 @@ The file is on a read-only file system. @comment unistd.h @comment BSD @deftypefun int fchown (int @var{filedes}, int @var{owner}, int @var{group}) -This is like @code{chown}, except that it changes the owner of the file -with open file descriptor @var{filedes}. +This is like @code{chown}, except that it changes the owner of the open +file with descriptor @var{filedes}. The return value from @code{fchown} is @code{0} on success and @code{-1} on failure. The following @code{errno} error codes are defined for this @@ -1912,8 +1900,8 @@ The @var{filedes} argument corresponds to a pipe or socket, not an ordinary file. @item EPERM -This process lacks permission to make the requested change. For -details, see @code{chmod}, above. +This process lacks permission to make the requested change. For details +see @code{chmod} above. @item EROFS The file resides on a read-only file system. @@ -1927,7 +1915,7 @@ The @dfn{file mode}, stored in the @code{st_mode} field of the file attributes, contains two kinds of information: the file type code, and the access permission bits. This section discusses only the access permission bits, which control who can read or write the file. -@xref{Testing File Type}, for information about the file type code. +@xref{Testing File Type} for information about the file type code. All of the symbols listed in this section are defined in the header file @file{sys/stat.h}. @@ -1946,8 +1934,8 @@ access permission for the file: @comment BSD @itemx S_IREAD @vindex S_IREAD -Read permission bit for the owner of the file. On many systems, this -bit is 0400. @code{S_IREAD} is an obsolete synonym provided for BSD +Read permission bit for the owner of the file. On many systems this bit +is 0400. @code{S_IREAD} is an obsolete synonym provided for BSD compatibility. @comment sys/stat.h @@ -2049,16 +2037,16 @@ This is the set-group-ID on execute bit, usually 02000. @vindex S_ISVTX This is the @dfn{sticky} bit, usually 01000. -On a directory, it gives permission to delete a file in the directory -only if you own that file. Ordinarily, a user either can delete all the -files in the directory or cannot delete any of them (based on whether -the user has write permission for the directory). The same restriction -applies---you must both have write permission for the directory and own +For a directory it gives permission to delete a file in that directory +only if you own that file. Ordinarily, a user can either delete all the +files in a directory or cannot delete any of them (based on whether the +user has write permission for the directory). The same restriction +applies---you must have both write permission for the directory and own the file you want to delete. The one exception is that the owner of the directory can delete any file in the directory, no matter who owns it (provided the owner has given himself write permission for the directory). This is commonly used for the @file{/tmp} directory, where -anyone may create files, but not delete files created by other users. +anyone may create files but not delete files created by other users. Originally the sticky bit on an executable file modified the swapping policies of the system. Normally, when a program terminated, its pages @@ -2082,10 +2070,10 @@ it means the opposite: never cache the pages of this file at all. The main use of this is for the files on an NFS server machine which are used as the swap area of diskless client machines. The idea is that the pages of the file will be cached in the client's memory, so it is a -waste of the server's memory to cache them a second time. In this use -the sticky bit also says that the filesystem may fail to record the -file's modification time onto disk reliably (the idea being that no-one -cares for a swap file). +waste of the server's memory to cache them a second time. With this +usage the sticky bit also implies that the filesystem may fail to record +the file's modification time onto disk reliably (the idea being that +no-one cares for a swap file). This bit is only available on BSD systems (and those derived from them). Therefore one has to use the @code{_BSD_SOURCE} feature select @@ -2098,9 +2086,9 @@ These bit values are correct for most systems, but they are not guaranteed. @strong{Warning:} Writing explicit numbers for file permissions is bad -practice. It is not only non-portable, it also requires everyone who -reads your program to remember what the bits mean. To make your -program clean, use the symbolic names. +practice. Not only is it not portable, it also requires everyone who +reads your program to remember what the bits mean. To make your program +clean use the symbolic names. @node Access Permission @subsection How Your Access to a File is Decided @@ -2109,10 +2097,10 @@ program clean, use the symbolic names. @cindex file access permission Recall that the operating system normally decides access permission for -a file based on the effective user and group IDs of the process, and its +a file based on the effective user and group IDs of the process and its supplementary group IDs, together with the file's owner, group and -permission bits. These concepts are discussed in detail in -@ref{Process Persona}. +permission bits. These concepts are discussed in detail in @ref{Process +Persona}. If the effective user ID of the process matches the owner user ID of the file, then permissions for read, write, and execute/search are @@ -2122,10 +2110,9 @@ process matches the group owner ID of the file, then permissions are controlled by the ``group'' bits. Otherwise, permissions are controlled by the ``other'' bits. -Privileged users, like @samp{root}, can access any file, regardless of -its file permission bits. As a special case, for a file to be -executable even for a privileged user, at least one of its execute bits -must be set. +Privileged users, like @samp{root}, can access any file regardless of +its permission bits. As a special case, for a file to be executable +even by a privileged user, at least one of its execute bits must be set. @node Setting Permissions @subsection Assigning File Permissions @@ -2134,18 +2121,17 @@ must be set. @cindex umask The primitive functions for creating files (for example, @code{open} or @code{mkdir}) take a @var{mode} argument, which specifies the file -permissions for the newly created file. But the specified mode is -modified by the process's @dfn{file creation mask}, or @dfn{umask}, -before it is used. +permissions to give the newly created file. This mode is modified by +the process's @dfn{file creation mask}, or @dfn{umask}, before it is +used. The bits that are set in the file creation mask identify permissions that are always to be disabled for newly created files. For example, if you set all the ``other'' access bits in the mask, then newly created -files are not accessible at all to processes in the ``other'' -category, even if the @var{mode} argument specified to the creation -function would permit such access. In other words, the file creation -mask is the complement of the ordinary access permissions you want to -grant. +files are not accessible at all to processes in the ``other'' category, +even if the @var{mode} argument passed to the create function would +permit such access. In other words, the file creation mask is the +complement of the ordinary access permissions you want to grant. Programs that create files typically specify a @var{mode} argument that includes all the permissions that make sense for the particular file. @@ -2155,22 +2141,21 @@ specified by the individual user's own file creation mask. @findex chmod To change the permission of an existing file given its name, call -@code{chmod}. This function ignores the file creation mask; it uses -exactly the specified permission bits. +@code{chmod}. This function uses the specified permission bits and +ignores the file creation mask. @pindex umask -In normal use, the file creation mask is initialized in the user's login +In normal use, the file creation mask is initialized by the user's login shell (using the @code{umask} shell command), and inherited by all subprocesses. Application programs normally don't need to worry about -the file creation mask. It will do automatically what it is supposed to +the file creation mask. It will automatically do what it is supposed to do. -When your program should create a file and bypass the umask for its +When your program needs to create a file and bypass the umask for its access permissions, the easiest way to do this is to use @code{fchmod} -after opening the file, rather than changing the umask. - -In fact, changing the umask is usually done only by shells. They use -the @code{umask} function. +after opening the file, rather than changing the umask. In fact, +changing the umask is usually done only by shells. They use the +@code{umask} function. The functions in this section are declared in @file{sys/stat.h}. @pindex sys/stat.h @@ -2197,7 +2182,7 @@ read_umask (void) @noindent However, it is better to use @code{getumask} if you just want to read -the mask value, because that is reentrant (at least if you use the GNU +the mask value, because it is reentrant (at least if you use the GNU operating system). @end deftypefun @@ -2214,8 +2199,8 @@ process. This function is a GNU extension. The @code{chmod} function sets the access permission bits for the file named by @var{filename} to @var{mode}. -If the @var{filename} names a symbolic link, @code{chmod} changes the -permission of the file pointed to by the link, not those of the link +If @var{filename} is a symbolic link, @code{chmod} changes the +permissions of the file pointed to by the link, not those of the link itself. This function returns @code{0} if successful and @code{-1} if not. In @@ -2228,9 +2213,9 @@ this function: The named file doesn't exist. @item EPERM -This process does not have permission to change the access permission of -this file. Only the file's owner (as judged by the effective user ID of -the process) or a privileged user can change them. +This process does not have permission to change the access permissions +of this file. Only the file's owner (as judged by the effective user ID +of the process) or a privileged user can change them. @item EROFS The file resides on a read-only file system. @@ -2251,8 +2236,8 @@ for full details on the sticky bit. @comment sys/stat.h @comment BSD @deftypefun int fchmod (int @var{filedes}, int @var{mode}) -This is like @code{chmod}, except that it changes the permissions of -the file currently open via descriptor @var{filedes}. +This is like @code{chmod}, except that it changes the permissions of the +currently open file given by @var{filedes}. The return value from @code{fchmod} is @code{0} on success and @code{-1} on failure. The following @code{errno} error codes are defined for this @@ -2267,9 +2252,9 @@ The @var{filedes} argument corresponds to a pipe or socket, or something else that doesn't really have access permissions. @item EPERM -This process does not have permission to change the access permission of -this file. Only the file's owner (as judged by the effective user ID of -the process) or a privileged user can change them. +This process does not have permission to change the access permissions +of this file. Only the file's owner (as judged by the effective user ID +of the process) or a privileged user can change them. @item EROFS The file resides on a read-only file system. @@ -2288,11 +2273,9 @@ files off-limits to ordinary users---for example, to modify access such files use the setuid bit feature so that they always run with @code{root} as the effective user ID. -Such a program may also access files specified by the user, files which -conceptually are being accessed explicitly by the user. Since the -program runs as @code{root}, it has permission to access whatever file -the user specifies---but usually the desired behavior is to permit only -those files which the user could ordinarily access. +Since the program runs as @code{root}, it has permission to access +whatever file the user specifies---but usually the desired behavior is +to permit only those files which the user could ordinarily access. The program therefore must explicitly check whether @emph{the user} would have the necessary access to a file, before it reads or writes the @@ -2328,8 +2311,8 @@ argument. The @var{how} argument either can be the bitwise OR of the flags @code{R_OK}, @code{W_OK}, @code{X_OK}, or the existence test @code{F_OK}. -This function uses the @emph{real} user and group ID's of the calling -process, rather than the @emph{effective} ID's, to check for access +This function uses the @emph{real} user and group IDs of the calling +process, rather than the @emph{effective} IDs, to check for access permission. As a result, if you use the function from a @code{setuid} or @code{setgid} program (@pxref{How Change Persona}), it gives information relative to the user who actually ran the program. @@ -2362,25 +2345,25 @@ are integer constants. @comment unistd.h @comment POSIX.1 @deftypevr Macro int R_OK -Argument that means, test for read permission. +Flag meaning test for read permission. @end deftypevr @comment unistd.h @comment POSIX.1 @deftypevr Macro int W_OK -Argument that means, test for write permission. +Flag meaning test for write permission. @end deftypevr @comment unistd.h @comment POSIX.1 @deftypevr Macro int X_OK -Argument that means, test for execute/search permission. +Flag meaning test for execute/search permission. @end deftypevr @comment unistd.h @comment POSIX.1 @deftypevr Macro int F_OK -Argument that means, test for existence of the file. +Flag meaning test for existence of the file. @end deftypevr @node File Times @@ -2410,13 +2393,13 @@ Adding a new name for a file with the @code{link} function updates the attribute change time field of the file being linked, and both the attribute change time and modification time fields of the directory containing the new name. These same fields are affected if a file name -is deleted with @code{unlink}, @code{remove}, or @code{rmdir}. Renaming +is deleted with @code{unlink}, @code{remove} or @code{rmdir}. Renaming a file with @code{rename} affects only the attribute change time and modification time fields of the two parent directories involved, and not the times for the file being renamed. -Changing attributes of a file (for example, with @code{chmod}) updates -its attribute change time field. +Changing the attributes of a file (for example, with @code{chmod}) +updates its attribute change time field. You can also change some of the time stamps of a file explicitly using the @code{utime} function---all except the attribute change time. You @@ -2448,7 +2431,7 @@ named @var{filename}. If @var{times} is a null pointer, then the access and modification times of the file are set to the current time. Otherwise, they are set to the values from the @code{actime} and @code{modtime} members (respectively) -of the @code{utimbuf} structure pointed at by @var{times}. +of the @code{utimbuf} structure pointed to by @var{times}. The attribute modification time for the file is set to the current time in either case (since changing the time stamps is itself a modification @@ -2464,15 +2447,14 @@ are defined for this function: There is a permission problem in the case where a null pointer was passed as the @var{times} argument. In order to update the time stamp on the file, you must either be the owner of the file, have write -permission on the file, or be a privileged user. +permission for the file, or be a privileged user. @item ENOENT The file doesn't exist. @item EPERM If the @var{times} argument is not a null pointer, you must either be -the owner of the file or be a privileged user. This error is used to -report the problem. +the owner of the file or be a privileged user. @item EROFS The file lives on a read-only file system. @@ -2494,8 +2476,8 @@ in the header file @file{sys/time.h}. @comment sys/time.h @comment BSD @deftypefun int utimes (const char *@var{filename}, struct timeval @var{tvp}@t{[2]}) -This function sets the file access and modification times for the file -named by @var{filename}. The new file access time is specified by +This function sets the file access and modification times of the file +@var{filename}. The new file access time is specified by @code{@var{tvp}[0]}, and the new modification time by @code{@var{tvp}[1]}. This function comes from BSD. @@ -2507,11 +2489,11 @@ function. @subsection File Size Normally file sizes are maintained automatically. A file begins with a -size of @math{0} and is automatically extended when data is written -past its end. It is also possible to empty a file completely in an +size of @math{0} and is automatically extended when data is written past +its end. It is also possible to empty a file completely by an @code{open} or @code{fopen} call. -However, sometimes it is neccessary to @emph{reduce} the size of a file. +However, sometimes it is necessary to @emph{reduce} the size of a file. This can be done with the @code{truncate} and @code{ftruncate} functions. They were introduced in BSD Unix. @code{ftruncate} was later added to POSIX.1. @@ -2519,8 +2501,8 @@ POSIX.1. Some systems allow you to extend a file (creating holes) with these functions. This is useful when using memory-mapped I/O (@pxref{Memory-mapped I/O}), where files are not automatically extended. -However it is not portable but must be implemented if @code{mmap} allows -mapping of files (i.e., @code{_POSIX_MAPPED_FILES} is defined). +However, it is not portable but must be implemented if @code{mmap} +allows mapping of files (i.e., @code{_POSIX_MAPPED_FILES} is defined). Using these functions on anything other than a regular file gives @emph{undefined} results. On many systems, such a call will appear to @@ -2558,7 +2540,7 @@ The file is a directory or not writable. The operation would extend the file beyond the limits of the operating system. @item EIO -A hardware I/O error occured. +A hardware I/O error occurred. @item EPERM The file is "append-only" or "immutable". @@ -2620,7 +2602,7 @@ following errors may occur: @var{fd} does not correspond to an open file. @item EACCES -@var{fd} is a directory or not open for write. +@var{fd} is a directory or not open for writing. @item EINVAL @var{length} is negative. @@ -2631,7 +2613,7 @@ The operation would extend the file beyond the limits of the operating system. @c files with extra-large offsets. @item EIO -A hardware I/O error occured. +A hardware I/O error occurred. @item EPERM The file is "append-only" or "immutable". @@ -2660,7 +2642,7 @@ When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a @code{ftruncate} and so transparently replaces the 32 bits interface. @end deftypefun -As announced here is a little example how to use @code{ftruncate} in +As announced here is a little example of how to use @code{ftruncate} in combination with @code{mmap}: @smallexample @@ -2690,12 +2672,12 @@ add (off_t at, void *block, size_t size) @} @end smallexample -The function @code{add} allows to add at arbitrary positions in the file -given blocks of memory. If the current size of the file is too small it -is extended. Please note the it is extended in multiples of a pagesize. -This is a requirement of @code{mmap}. The program has to track the real -size and once the program finished to work a final @code{ftruncate} call -should set the real size of the file. +The function @code{add} writes a block of memory at an arbitrary +position in the file. If the current size of the file is too small it +is extended. Note the it is extended by a round number of pages. This +is a requirement of @code{mmap}. The program has to keep track of the +real size, and when it has finished a final @code{ftruncate} call should +set the real size of the file. @node Making Special Files @section Making Special Files @@ -2748,13 +2730,13 @@ this file, you must remove the old file explicitly first. If you need to use a temporary file in your program, you can use the @code{tmpfile} function to open it. Or you can use the @code{tmpnam} -(better: @code{tmpnam_r}) function to make a name for a temporary file and -then you can open it in the usual way with @code{fopen}. +(better: @code{tmpnam_r}) function to provide a name for a temporary +file and then you can open it in the usual way with @code{fopen}. The @code{tempnam} function is like @code{tmpnam} but lets you choose what directory temporary files will go in, and something about what -their file names will look like. Important for multi threaded programs -is that @code{tempnam} is reentrant while @code{tmpnam} is not since it +their file names will look like. Important for multi-threaded programs +is that @code{tempnam} is reentrant, while @code{tmpnam} is not since it returns a pointer to a static buffer. These facilities are declared in the header file @file{stdio.h}. @@ -2772,16 +2754,16 @@ terminates abnormally). This function is reentrant. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bits system this function is in fact @code{tmpfile64}. I.e., the -LFS interface transparently replaces the old interface. +32-bit system this function is in fact @code{tmpfile64}, i.e. the LFS +interface transparently replaces the old interface. @end deftypefun @comment stdio.h @comment Unix98 @deftypefun {FILE *} tmpfile64 (void) -This function is similar to @code{tmpfile} but the stream it returns a -pointer for is opened using @code{tmpfile64}. Therefore this stream can be -used even on files larger then @math{2^31} bytes on 32 bits machines. +This function is similar to @code{tmpfile}, but the stream it returns a +pointer to was opened using @code{tmpfile64}. Therefore this stream can +be used for files larger then @math{2^31} bytes on 32-bit machines. Please note that the return type is still @code{FILE *}. There is no special @code{FILE} type for the LFS interface. @@ -2794,44 +2776,43 @@ and so transparently replaces the old interface. @comment stdio.h @comment ISO @deftypefun {char *} tmpnam (char *@var{result}) -This function constructs and returns a file name that is a valid file -name and that does not name any existing file. If the @var{result} -argument is a null pointer, the return value is a pointer to an internal -static string, which might be modified by subsequent calls and therefore -makes this function non-reentrant. Otherwise, the @var{result} argument -should be a pointer to an array of at least @code{L_tmpnam} characters, -and the result is written into that array. +This function constructs and returns a valid file name that does not +refer to any existing file. If the @var{result} argument is a null +pointer, the return value is a pointer to an internal static string, +which might be modified by subsequent calls and therefore makes this +function non-reentrant. Otherwise, the @var{result} argument should be +a pointer to an array of at least @code{L_tmpnam} characters, and the +result is written into that array. It is possible for @code{tmpnam} to fail if you call it too many times -without removing previously created files. This is because the fixed -length of a temporary file name gives room for only a finite number of -different names. If @code{tmpnam} fails, it returns a null pointer. - -@strong{Warning:} Since between the time the pathname is constructed and -the file is created another process might have created a file with this -name using @code{tmpnam} is a possible security hole. The -implementation generates names which hardly can be predicted but opening -the file in any case should use the @code{O_EXCL} flag. Using +without removing previously-created files. This is because the limited +length of the temporary file names gives room for only a finite number +of different names. If @code{tmpnam} fails it returns a null pointer. + +@strong{Warning:} Between the time the pathname is constructed and the +file is created another process might have created a file with the same +name using @code{tmpnam}, leading to a possible security hole. The +implementation generates names which can hardly be predicted, but when +opening the file you should use the @code{O_EXCL} flag. Using @code{tmpfile} is a safe way to avoid this problem. @end deftypefun @comment stdio.h @comment GNU @deftypefun {char *} tmpnam_r (char *@var{result}) -This function is nearly identical to the @code{tmpnam} function. But it -does not allow @var{result} to be a null pointer. In the later case a -null pointer is returned. +This function is nearly identical to the @code{tmpnam} function, except +that if @var{result} is a null pointer it returns a null pointer. -This function is reentrant because the non-reentrant situation of +This guarantees reentrancy because the non-reentrant situation of @code{tmpnam} cannot happen here. @end deftypefun @comment stdio.h @comment ISO @deftypevr Macro int L_tmpnam -The value of this macro is an integer constant expression that represents -the minimum allocation size of a string large enough to hold the -file name generated by the @code{tmpnam} function. +The value of this macro is an integer constant expression that +represents the minimum size of a string large enough to hold a file name +generated by the @code{tmpnam} function. @end deftypevr @comment stdio.h @@ -2843,26 +2824,26 @@ you can create with @code{tmpnam}. You can rely on being able to call have made too many temporary file names. With the GNU library, you can create a very large number of temporary -file names---if you actually create the files, you will probably run out -of disk space before you run out of names. Some other systems have a -fixed, small limit on the number of temporary files. The limit is never -less than @code{25}. +file names. If you actually created the files, you would probably run +out of disk space before you ran out of names. Some other systems have +a fixed, small limit on the number of temporary files. The limit is +never less than @code{25}. @end deftypevr @comment stdio.h @comment SVID @deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix}) -This function generates a unique temporary filename. If @var{prefix} is -not a null pointer, up to five characters of this string are used as a -prefix for the file name. The return value is a string newly allocated -with @code{malloc}; you should release its storage with @code{free} when -it is no longer needed. +This function generates a unique temporary file name. If @var{prefix} +is not a null pointer, up to five characters of this string are used as +a prefix for the file name. The return value is a string newly +allocated with @code{malloc}, so you should release its storage with +@code{free} when it is no longer needed. Because the string is dynamically allocated this function is reentrant. -The directory prefix for the temporary file name is determined by testing -each of the following, in sequence. The directory must exist and be -writable. +The directory prefix for the temporary file name is determined by +testing each of the following in sequence. The directory must exist and +be writable. @itemize @bullet @item @@ -2914,11 +2895,11 @@ name, it makes @var{template} an empty string and returns that. If @var{template} does not end with @samp{XXXXXX}, @code{mktemp} returns a null pointer. -@strong{Warning:} Since between the time the pathname is constructed and -the file is created another process might have created a file with this -name using @code{mktemp} is a possible security hole. The -implementation generates names which hardly can be predicted but opening -the file in any case should use the @code{O_EXCL} flag. Using +@strong{Warning:} Between the time the pathname is constructed and the +file is created another process might have created a file with the same +name using @code{mktemp}, leading to a possible security hole. The +implementation generates names which can hardly be predicted, but when +opening the file you should use the @code{O_EXCL} flag. Using @code{mkstemp} is a safe way to avoid this problem. @end deftypefun @@ -2928,21 +2909,21 @@ the file in any case should use the @code{O_EXCL} flag. Using The @code{mkstemp} function generates a unique file name just as @code{mktemp} does, but it also opens the file for you with @code{open} (@pxref{Opening and Closing Files}). If successful, it modifies -@var{template} in place and returns a file descriptor open on that file +@var{template} in place and returns a file descriptor for that file open for reading and writing. If @code{mkstemp} cannot create a uniquely-named file, it returns @code{-1}. If @var{template} does not end with @samp{XXXXXX}, @code{mkstemp} returns @code{-1} and does not modify @var{template}. The file is opened using mode @code{0600}. If the file is meant to be -used by other users the mode must be changed explicitly. +used by other users this mode must be changed explicitly. @end deftypefun Unlike @code{mktemp}, @code{mkstemp} is actually guaranteed to create a unique file that cannot possibly clash with any other program trying to create a temporary file. This is because it works by calling -@code{open} with the @code{O_EXCL} flag bit, which says you want to -always create a new file, and get an error if the file already exists. +@code{open} with the @code{O_EXCL} flag, which says you want to create a +new file and get an error if the file already exists. @comment stdlib.h @comment BSD diff --git a/manual/install.texi b/manual/install.texi index 2905b05..a72eee6 100644 --- a/manual/install.texi +++ b/manual/install.texi @@ -49,8 +49,8 @@ GNU Make, and possibly others. @xref{Tools for Compilation}, below. @cindex configuring @cindex compiling -GNU Libc can be compiled in the source directory but we strongly advise to -build in a separate build directory. For example, if you have unpacked +GNU libc can be compiled in the source directory, but we strongly advise to +build it in a separate build directory. For example, if you have unpacked the glibc sources in @file{/src/gnu/glibc-2.1.0}, create a directory @file{/src/gnu/glibc-build} to put the object files in. This allows to remove the whole build directory in case an error occurs which is the @@ -64,7 +64,7 @@ $ ../glibc-2.1.0/configure @var{args...} @end smallexample Please note that even if you're building in a separate build directory, -the compiliation needs to modify a few files in the source +the compilation needs to modify a few files in the source directory, especially some files in the manual subdirectory. @noindent @@ -74,14 +74,14 @@ only two: @samp{--prefix} and @samp{--enable-add-ons}. The This defaults to @file{/usr/local}. The @samp{--enable-add-ons} option tells configure to use all the add-on bundles it finds in the source directory. Since important functionality is provided in add-ons, you -should always give this option. +should always specify this option. It may also be useful to set the @var{CC} and @var{CFLAGS} variables in the environment when running @code{configure}. @var{CC} selects the C compiler that will be used, and @var{CFLAGS} sets optimization options for the compiler. -Here are all the useful options known by @code{configure}: +The following list describes all of the available options for @code{configure}: @table @samp @item --prefix=@var{directory} @@ -91,13 +91,13 @@ Install machine-independent data files in subdirectories of @item --exec-prefix=@var{directory} Install the library and other machine-dependent files in subdirectories of @file{@var{directory}}. The default is to the @samp{--prefix} -directory if that option is given, or @file{/usr/local} otherwise. +directory if that option is specified, or @file{/usr/local} otherwise. @item --with-headers=@var{directory} Look for kernel header files in @var{directory}, not @file{/usr/include}. Glibc needs information from the kernel's private header files. It will normally look in @file{/usr/include} for them, -but if you give this option, it will look in @var{DIRECTORY} instead. +but if you specify this option, it will look in @var{DIRECTORY} instead. This option is primarily of use on a system where the headers in @file{/usr/include} come from an older version of glibc. Conflicts can @@ -107,7 +107,7 @@ compile glibc with a newer set of kernel headers than the ones found in @file{/usr/include}. @item --enable-add-ons[=@var{list}] -Enable add-on packages in your source tree. If this option is given +Enable add-on packages in your source tree. If this option is specified with no list, it enables all the add-on packages it finds. If you do not wish to use some add-on package that you have present in your source tree, give this option a list of the add-ons that you @emph{do} want @@ -117,10 +117,10 @@ used, like this: @samp{--enable-add-ons=crypt,linuxthreads} Use the binutils (assembler and linker) in @file{@var{directory}}, not the ones the C compiler would default to. You could use this option if the default binutils on your system cannot deal with all the constructs -in the GNU C library. (@code{configure} will detect the problem and -suppress these constructs, so the library will still be usable, but -functionality may be lost---for example, you can not build a shared libc -with old binutils.) +in the GNU C library. In that case, @code{configure} will detect the problem and +suppress these constructs, so that the library will still be usable, but +functionality may be lost---for example, you can't build a shared libc +with old binutils. @item --without-fp Use this option if your computer lacks hardware floating-point support @@ -132,7 +132,7 @@ and your operating system does not emulate an FPU. @c days, but we recommend you build them in case you need them. @item --disable-shared -Don't build shared libraries even if we could. Not all systems support +Don't build shared libraries even if it is possible. Not all systems support shared libraries; you need ELF support and (currently) the GNU linker. @item --disable-profile @@ -148,7 +148,7 @@ you won't be able to trace bugs through the C library. @item --disable-versioning Don't compile the shared libraries with symbol version information. -Doing this will make the library that's built incompatible with old +Doing this will make the resulting library incompatible with old binaries, so it's not recommended. @item --enable-static-nss @@ -159,22 +159,22 @@ reconfigured to use a different name database. @item --build=@var{build-system} @itemx --host=@var{host-system} -These options are for cross-compiling. If you give them both and +These options are for cross-compiling. If you specify both options and @var{build-system} is different from @var{host-system}, @code{configure} will prepare to cross-compile glibc from @var{build-system} to be used on @var{host-system}. You'll probably need the @samp{--with-headers} option too, and you may have to override @var{configure}'s selection of the compiler and/or binutils. -If you give just @samp{--host}, configure will prepare for a native -compile but use what you say instead of guessing what your system is. +If you only specify @samp{--host}, configure will prepare for a native +compile but use what you specify instead of guessing what your system is. This is most useful to change the CPU submodel. For example, if configure guesses your machine as @code{i586-pc-linux-gnu} but you want to compile a library for 386es, give @samp{--host=i386-pc-linux-gnu} or just @samp{--host=i386-linux} and add the appropriate compiler flags (@samp{-mcpu=i386} will do the trick) to @var{CFLAGS}. -If you give just @samp{--build}, configure will get confused. +If you specify just @samp{--build}, configure will get confused. @end table To build the library and related programs, type @code{make}. This will @@ -200,17 +200,18 @@ Instead, edit the generated @file{Makefile} and uncomment the line @noindent You can change the @samp{4} to some other number as appropriate for your system. Instead of changing the @file{Makefile}, you could give -this option directly to @code{make} and call it as, e.g. +this option directly to @code{make} and call it as, for example, @code{make PARALLELMFLAGS=-j4}. If you're building in the source -directory, you've got to use the latter approach since in this case no -new @file{Makefile} is generated which you can change. +directory, you must use the latter approach since in this case no +new @file{Makefile} is generated for you to change. -To build and run some test programs which exercise some of the library -facilities, type @code{make check}. This should complete successfully; -if it doesn't, do not use the built library, and report a bug. -@xref{Reporting Bugs}, for how to do that. Note that some of the tests -assume they are not being run by @code{root}. We recommend you compile -and test glibc as an unprivileged user. +To build and run test programs which exercise some of the library +facilities, type @code{make check}. If it does not complete +successfully, do not use the built library, and report a bug after +verifying that the problem is not already known. @xref{Reporting Bugs}, +for instructions on reporting bugs. Note that some of the tests assume +they are not being run by @code{root}. We recommend you compile and +test glibc as an unprivileged user. To format the @cite{GNU C Library Reference Manual} for printing, type @w{@code{make dvi}}. You need a working @TeX{} installation to do this. @@ -224,8 +225,8 @@ info}}, but it shouldn't be necessary. To install the library and its header files, and the Info files of the manual, type @code{make install}. This will build things if necessary, -before installing them. Don't rely on that; compile everything first. -If you are installing glibc as your primary C library, we recommend you +before installing them. However, you should still compile everything first. +If you are installing glibc as your primary C library, we recommend that you shut the system down to single-user mode first, and reboot afterward. This minimizes the risk of breaking things when the library changes out from underneath. @@ -233,8 +234,8 @@ from underneath. If you are upgrading from a previous installation of glibc 2.0 or 2.1, @samp{make install} will do the entire job. If you're upgrading from Linux libc5 or some other C library, you need to rename the old -@file{/usr/include} directory out of the way before running @samp{make -install}, or you will end up with a mixture of header files from both +@file{/usr/include} directory before running @samp{make install}, +or you will end up with a mixture of header files from both libraries, and you won't be able to compile anything. You may also need to reconfigure GCC to work with the new library. The easiest way to do that is to figure out the compiler switches to make it work again @@ -279,7 +280,7 @@ build the GNU C library: GNU @code{make} 3.75 You need the latest version of GNU @code{make}. Modifying the GNU C -Library to work with other @code{make} programs would be so hard that we +Library to work with other @code{make} programs would be so difficult that we recommend you port GNU @code{make} instead. @strong{Really.} We recommend version GNU @code{make} version 3.75 or 3.77. All earlier versions have severe bugs or lack features. Version 3.76 is known to @@ -418,8 +419,8 @@ they definitely don't work anymore. Porting the library is not hard. If you are interested in doing a port, please contact the glibc maintainers by sending electronic mail to @email{bug-glibc@@gnu.org}. -Each case of @samp{i@var{x}86} can be @samp{i386}, @samp{i486}, -@samp{i586}, or @samp{i686}. All of those configurations produce a +Valid cases of @samp{i@var{x}86} include @samp{i386}, @samp{i486}, +@samp{i586}, and @samp{i686}. All of those configurations produce a library that can run on this processor and newer processors. The GCC compiler by default generates code that's optimized for the machine it's configured for and will use the instructions available on that machine. @@ -436,7 +437,7 @@ switches via @var{CFLAGS}. If you are installing GNU libc on a Linux system, you need to have the header files from a 2.2 kernel around for reference. You do not -need to use the 2.2 kernel, just have its headers where glibc can get +need to use the 2.2 kernel, just have its headers where glibc can access at them. The easiest way to do this is to unpack it in a directory such as @file{/usr/src/linux-2.2.1}. In that directory, run @samp{make config} and accept all the defaults. Then run @samp{make @@ -483,8 +484,8 @@ errors and omissions in this manual. If you report them, they will get fixed. If you don't, no one will ever know about them and they will remain unfixed for all eternity, if not longer. -It is a good idea to check first that the problem was not reported -before. Bugs are documented in two places: The file @file{BUGS} +It is a good idea to verify that the problem has not already been +reported. Bugs are documented in two places: The file @file{BUGS} describes a number of well known bugs and the bug tracking system has a WWW interface at @url{http://www-gnats.gnu.org:8080/cgi-bin/wwwgnats.pl}. The WWW @@ -525,5 +526,5 @@ function's behavior disagrees with the manual, then either the library or the manual has a bug, so report the disagreement. If you find any errors or omissions in this manual, please report them to the Internet address @email{bug-glibc-manual@@gnu.org}. If you refer to specific -sections when reporting on the manual, please include the section names -for easier identification. +sections of the manual, please include the section names for easier +identification. diff --git a/manual/job.texi b/manual/job.texi index 24e1c94..d19a8d4 100644 --- a/manual/job.texi +++ b/manual/job.texi @@ -1298,7 +1298,7 @@ process. @comment Unix98 @deftypefun pid_t tcgetsid (int @var{fildes}) This function is used to obtain the process group ID of the session -for which terminal specified by @var{fildes} is the controlling terminal. +for which the terminal specified by @var{fildes} is the controlling terminal. If the call is successful the group ID is returned. Otherwise the return value is @code{(pid_t) -1} and the global variable @var{errno} is set to the following value: @@ -1308,6 +1308,6 @@ The @var{filedes} argument is not a valid file descriptor. @item ENOTTY The calling process does not have a controlling terminal, or the file -ins not the controlling terminal. +is not the controlling terminal. @end table @end deftypefun diff --git a/manual/lang.texi b/manual/lang.texi index e085dcb..ecde184 100644 --- a/manual/lang.texi +++ b/manual/lang.texi @@ -51,8 +51,8 @@ without indicating anything might be wrong. @comment assert.h @comment ISO @deftypefn Macro void assert (int @var{expression}) -Verify the programmer's belief that @var{expression} should be nonzero -at this point in the program. +Verify the programmer's belief that @var{expression} is nonzero at +this point in the program. If @code{NDEBUG} is not defined, @code{assert} tests the value of @var{expression}. If it is false (zero), @code{assert} aborts the @@ -67,7 +67,7 @@ form: on the standard error stream @code{stderr} (@pxref{Standard Streams}). The filename and line number are taken from the C preprocessor macros @code{__FILE__} and @code{__LINE__} and specify where the call to -@code{assert} was written. When using the GNU C compiler, the name of +@code{assert} was made. When using the GNU C compiler, the name of the function which calls @code{assert} is taken from the built-in variable @code{__PRETTY_FUNCTION__}; with older compilers, the function name and following colon are omitted. @@ -95,7 +95,7 @@ Similar to @code{assert}, but verifies that @var{errnum} is zero. If @code{NDEBUG} is defined, @code{assert_perror} tests the value of @var{errnum}. If it is nonzero, @code{assert_perror} aborts the program -after a printing a message of the form: +after printing a message of the form: @smallexample @file{@var{file}}:@var{linenum}: @var{function}: @var{error text} @@ -109,7 +109,7 @@ name are as for @code{assert}. The error text is the result of Like @code{assert}, if @code{NDEBUG} is defined before @file{assert.h} is included, the @code{assert_perror} macro does absolutely nothing. It does not evaluate the argument, so @var{errnum} should not have any side -effects. It is best for @var{errnum} to be a just simple variable +effects. It is best for @var{errnum} to be just a simple variable reference; often it will be @code{errno}. This macro is a GNU extension. @@ -117,20 +117,17 @@ This macro is a GNU extension. @strong{Usage note:} The @code{assert} facility is designed for detecting @emph{internal inconsistency}; it is not suitable for -reporting invalid input or improper usage by @emph{the user} of the +reporting invalid input or improper usage by the @emph{user} of the program. The information in the diagnostic messages printed by the @code{assert} -macro is intended to help you, the programmer, track down the cause of a -bug, but is not really useful for telling a user of your program why his -or her input was invalid or why a command could not be carried out. So -you can't use @code{assert} or @code{assert_perror} to print the error -messages for these eventualities. - -What's more, your program should not abort when given invalid input, as -@code{assert} would do---it should exit with nonzero status (@pxref{Exit -Status}) after printing its error messages, or perhaps read another -command or move on to the next input file. +and @code{assert_perror} macro is intended to help you, the programmer, +track down the cause of a bug, but is not really useful for telling a user +of your program why his or her input was invalid or why a command could not +be carried out. What's more, your program should not abort when given +invalid input, as @code{assert} would do---it should exit with nonzero +status (@pxref{Exit Status}) after printing its error messages, or perhaps +read another command or move on to the next input file. @xref{Error Messages}, for information on printing error messages for problems that @emph{do not} represent bugs in the program. @@ -256,10 +253,9 @@ func (const char *a, int b, @dots{}) @end smallexample @noindent -outlines a definition of a function @code{func} which returns an -@code{int} and takes two required arguments, a @code{const char *} and -an @code{int}. These are followed by any number of anonymous -arguments. +defines a function @code{func} which returns an @code{int} and takes two +required arguments, a @code{const char *} and an @code{int}. These are +followed by any number of anonymous arguments. @strong{Portability note:} For some C compilers, the last required argument must not be declared @code{register} in the function @@ -303,10 +299,10 @@ values if you try to access too many arguments. You indicate that you are finished with the argument pointer variable by calling @code{va_end}. -(In practice, with most C compilers, calling @code{va_end} does nothing -and you do not really need to call it. This is always true in the GNU C -compiler. But you might as well call @code{va_end} just in case your -program is someday compiled with a peculiar compiler.) +(In practice, with most C compilers, calling @code{va_end} does nothing. +This is always true in the GNU C compiler. But you might as well call +@code{va_end} just in case your program is someday compiled with a peculiar +compiler.) @end enumerate @xref{Argument Macros}, for the full definitions of @code{va_start}, @@ -317,7 +313,7 @@ optional arguments. However, you can pass the @code{va_list} variable as an argument to another function and perform all or part of step 2 there. -You can perform the entire sequence of the three steps multiple times +You can perform the entire sequence of three steps multiple times within a single function invocation. If you want to ignore the optional arguments, you can do these steps zero times. @@ -342,10 +338,9 @@ regardless. There is no general way for a function to determine the number and type of the optional arguments it was called with. So whoever designs the -function typically designs a convention for the caller to tell it how -many arguments it has, and what kind. It is up to you to define an -appropriate calling convention for each variadic function, and write all -calls accordingly. +function typically designs a convention for the caller to specify the number +and type of arguments. It is up to you to define an appropriate calling +convention for each variadic function, and write all calls accordingly. One kind of calling convention is to pass the number of optional arguments as one of the fixed arguments. This convention works provided @@ -375,11 +370,10 @@ in just this way; see @ref{Executing a File}. @cindex calling variadic functions @cindex declaring variadic functions -You don't have to write anything special when you call a variadic function. -Just write the arguments (required arguments, followed by optional ones) -inside parentheses, separated by commas, as usual. But you should prepare -by declaring the function with a prototype, and you must know how the -argument values are converted. +You don't have to do anything special to call a variadic function. +Just put the arguments (required arguments, followed by optional ones) +inside parentheses, separated by commas, as usual. But you must declare +the function with a prototype and know how the argument values are converted. In principle, functions that are @emph{defined} to be variadic must also be @emph{declared} to be variadic using a function prototype whenever @@ -406,7 +400,7 @@ type @code{char} or @w{@code{short int}} (whether signed or not) are promoted to either @code{int} or @w{@code{unsigned int}}, as appropriate; and that objects of type @code{float} are promoted to type @code{double}. So, if the caller passes a @code{char} as an optional -argument, it is promoted to an @code{int}, and the function should get +argument, it is promoted to an @code{int}, and the function can access it with @code{va_arg (@var{ap}, int)}. Conversion of the required arguments is controlled by the function @@ -467,16 +461,16 @@ use it except for reasons of portability. Sometimes it is necessary to parse the list of parameters more than once or one wants to remember a certain position in the parameter list. To -do this one will have to make a copy of the current value of the -argument. But @code{va_list} is an opaque type and it is not guaranteed -that one can simply assign the value of a variable to another one of -type @code{va_list} +do this, one will have to make a copy of the current value of the +argument. But @code{va_list} is an opaque type and one cannot necessarily +assign the value of one variable of type @code{va_list} to another variable +of the same type. @comment stdarg.h @comment GNU @deftypefn {Macro} void __va_copy (va_list @var{dest}, va_list @var{src}) The @code{__va_copy} macro allows copying of objects of type -@code{va_list} even if this is no integral type. The argument pointer +@code{va_list} even if this is not an integral type. The argument pointer in @var{dest} is initialized to point to the same argument as the pointer in @var{src}. @@ -484,10 +478,10 @@ This macro is a GNU extension but it will hopefully also be available in the next update of the ISO C standard. @end deftypefn -If you want to use @code{__va_copy} you should always be prepared that -this macro is not available. On architectures where a simple assignment -is invalid it hopefully is and so one should always write something like -this: +If you want to use @code{__va_copy} you should always be prepared for the +possibility that this macro will not be available. On architectures where a +simple assignment is invalid, hopefully @code{__va_copy} @emph{will} be available, +so one should always write something like this: @smallexample @{ @@ -540,7 +534,7 @@ build (va_alist) @{ @end smallexample -Secondly, you must give @code{va_start} just one argument, like this: +Secondly, you must give @code{va_start} only one argument, like this: @smallexample va_list p; @@ -643,7 +637,7 @@ arguments or variables that hold the size of an object. In the GNU system @code{size_t} is equivalent to either @w{@code{unsigned int}} or @w{@code{unsigned long int}}. These types -have identical properties on the GNU system, and for most purposes, you +have identical properties on the GNU system and, for most purposes, you can use them interchangeably. However, they are distinct as data types, which makes a difference in certain contexts. @@ -938,7 +932,7 @@ follows. @item @cindex mantissa (of floating point number) @cindex significand (of floating point number) -The @dfn{mantissa} or @dfn{significand}, an unsigned integer which is a +The @dfn{mantissa} or @dfn{significand} is an unsigned integer which is a part of each floating point number. @item @@ -957,12 +951,12 @@ Again, the GNU library provides no facilities for dealing with such low-level aspects of the representation. @end itemize -The mantissa of a floating point number actually represents an implicit -fraction whose denominator is the base raised to the power of the -precision. Since the largest representable mantissa is one less than -this denominator, the value of the fraction is always strictly less than -@code{1}. The mathematical value of a floating point number is then the -product of this fraction, the sign, and the base raised to the exponent. +The mantissa of a floating point number represents an implicit fraction +whose denominator is the base raised to the power of the precision. Since +the largest representable mantissa is one less than this denominator, the +value of the fraction is always strictly less than @code{1}. The +mathematical value of a floating point number is then the product of this +fraction, the sign, and the base raised to the exponent. @cindex normalized floating point number We say that the floating point number is @dfn{normalized} if the @@ -1054,7 +1048,7 @@ the IEEE single-precision standard. @comment float.h @comment ISO @item FLT_RADIX -This is the value of the base, or radix, of exponent representation. +This is the value of the base, or radix, of the exponent representation. This is guaranteed to be a constant expression, unlike the other macros described in this section. The value is 2 on all machines we know of except the IBM 360 and derivatives. @@ -1208,7 +1202,7 @@ macro's value is the same as the type it describes. @comment ISO @item FLT_EPSILON -This is the minimum positive floating point number of type @code{float} +This is the maximum positive floating point number of type @code{float} such that @code{1.0 + FLT_EPSILON != 1.0} is true. It's supposed to be no greater than @code{1E-5}. diff --git a/manual/llio.texi b/manual/llio.texi index 01fb95f..df3838c 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -97,8 +97,8 @@ for this function: @table @code @item EACCES -The file exists but is not readable/writable as requested by the @var{flags} -argument, the file does not exist and the directory is unwritable so +The file exists but is not readable/writeable as requested by the @var{flags} +argument, the file does not exist and the directory is unwriteable so it cannot be created. @item EEXIST @@ -142,19 +142,19 @@ or @code{O_CREAT} is set and the file does not already exist. @c !!! umask -If on a 32 bits machine the sources are translated with +If on a 32 bit machine the sources are translated with @code{_FILE_OFFSET_BITS == 64} the function @code{open} returns a file descriptor opened in the large file mode which enables the file handling functions to use files up to @math{2^63} bytes in size and offset from @math{-2^63} to @math{2^63}. This happens transparently for the user since all of the lowlevel file handling functions are equally replaced. -This function is a cancelation point in multi-threaded programs. This +This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time @code{open} is -called. If the thread gets canceled these resources stay allocated +called. If the thread gets cancelled these resources stay allocated until the program ends. To avoid this calls to @code{open} should be -protected using cancelation handlers. +protected using cancellation handlers. @c ref pthread_cleanup_push / pthread_cleanup_pop The @code{open} function is the underlying primitive for the @code{fopen} @@ -166,7 +166,7 @@ and @code{freopen} functions, that create streams. @deftypefun int open64 (const char *@var{filename}, int @var{flags}[, mode_t @var{mode}]) This function is similar to @code{open}. It returns a file descriptor which can be used to access the file named by @var{filename}. The only -the difference is that on 32 bits systems the file is opened in the +difference is that on 32 bit systems the file is opened in the large file mode. I.e., file length and file offsets can exceed 31 bits. When the sources are translated with @code{_FILE_OFFSET_BITS == 64} this @@ -191,7 +191,7 @@ is equivalent to: open (@var{filename}, O_WRONLY | O_CREAT | O_TRUNC, @var{mode}) @end smallexample -If on a 32 bits machine the sources are translated with +If on a 32 bit machine the sources are translated with @code{_FILE_OFFSET_BITS == 64} the function @code{creat} returns a file descriptor opened in the large file mode which enables the file handling functions to use files up to @math{2^63} in size and offset from @@ -204,7 +204,7 @@ since all of the lowlevel file handling functions are equally replaced. @deftypefn {Obsolete function} int creat64 (const char *@var{filename}, mode_t @var{mode}) This function is similar to @code{creat}. It returns a file descriptor which can be used to access the file named by @var{filename}. The only -the difference is that on 32 bits systems the file is opened in the +the difference is that on 32 bit systems the file is opened in the large file mode. I.e., file length and file offsets can exceed 31 bits. To use this file descriptor one must not use the normal operations but @@ -234,12 +234,12 @@ When all file descriptors associated with a pipe or FIFO have been closed, any unread data is discarded. @end itemize -This function is a cancelation point in multi-threaded programs. This +This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time @code{close} is -called. If the thread gets canceled these resources stay allocated -until the program ends. To avoid this calls to @code{close} should be -protected using cancelation handlers. +called. If the thread gets cancelled these resources stay allocated +until the program ends. To avoid this, calls to @code{close} should be +protected using cancellation handlers. @c ref pthread_cleanup_push / pthread_cleanup_pop The normal return value from @code{close} is @math{0}; a value of @math{-1} @@ -270,7 +270,7 @@ on their meaning. Please note that there is @emph{no} separate @code{close64} function. This is not necessary since this function does not determine nor depend on the mode of the file. The kernel which performs the @code{close} -operation knows for which mode the descriptor is used and can handle +operation knows which mode the descriptor is used for and can handle this situation. @end deftypefun @@ -302,8 +302,8 @@ but must be a signed type. @deftypefun ssize_t read (int @var{filedes}, void *@var{buffer}, size_t @var{size}) The @code{read} function reads up to @var{size} bytes from the file with descriptor @var{filedes}, storing the results in the @var{buffer}. -(This is not necessarily a character string and there is no terminating -null character added.) +(This is not necessarily a character string, and no terminating null +character is added.) @cindex end-of-file, on a file descriptor The return value is the number of bytes actually read. This might be @@ -365,7 +365,7 @@ a hardware error. @code{EIO} also occurs when a background process tries to read from the controlling terminal, and the normal action of stopping the process by sending it a @code{SIGTTIN} signal isn't working. This might happen if -signal is being blocked or ignored, or because the process group is +the signal is being blocked or ignored, or because the process group is orphaned. @xref{Job Control}, for more information about job control, and @ref{Signal Handling}, for information about signals. @end table @@ -373,14 +373,14 @@ and @ref{Signal Handling}, for information about signals. Please note that there is no function named @code{read64}. This is not necessary since this function does not directly modify or handle the possibly wide file offset. Since the kernel handles this state -internally the @code{read} function can be used for all cases. +internally, the @code{read} function can be used for all cases. -This function is a cancelation point in multi-threaded programs. This +This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time @code{read} is -called. If the thread gets canceled these resources stay allocated -until the program ends. To avoid this calls to @code{read} should be -protected using cancelation handlers. +called. If the thread gets cancelled these resources stay allocated +until the program ends. To avoid this, calls to @code{read} should be +protected using cancellation handlers. @c ref pthread_cleanup_push / pthread_cleanup_pop The @code{read} function is the underlying primitive for all of the @@ -391,23 +391,24 @@ functions that read from streams, such as @code{fgetc}. @comment Unix98 @deftypefun ssize_t pread (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off_t @var{offset}) The @code{pread} function is similar to the @code{read} function. The -first three arguments are identical and also the return values and error -codes correspond. +first three arguments are identical, and the return values and error +codes also correspond. The difference is the fourth argument and its handling. The data block is not read from the current position of the file descriptor @code{filedes}. Instead the data is read from the file starting at position @var{offset}. The position of the file descriptor itself is -not effected by the operation. The value is the same as before the call. +not affected by the operation. The value is the same as before the call. When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the @code{pread} function is in fact @code{pread64} and the type -@code{off_t} has 64 bits which makes it possible to handle files up to +@code{off_t} has 64 bits, which makes it possible to handle files up to @math{2^63} bytes in length. The return value of @code{pread} describes the number of bytes read. In the error case it returns @math{-1} like @code{read} does and the -error codes are also the same. Only there are a few more error codes: +error codes are also the same, with these additions: + @table @code @item EINVAL The value given for @var{offset} is negative and therefore illegal. @@ -426,15 +427,15 @@ version 2. @deftypefun ssize_t pread64 (int @var{filedes}, void *@var{buffer}, size_t @var{size}, off64_t @var{offset}) This function is similar to the @code{pread} function. The difference is that the @var{offset} parameter is of type @code{off64_t} instead of -@code{off_t} which makes it possible on 32 bits machines to address +@code{off_t} which makes it possible on 32 bit machines to address files larger than @math{2^31} bytes and up to @math{2^63} bytes. The file descriptor @code{filedes} must be opened using @code{open64} since otherwise the large offsets possible with @code{off64_t} will lead to errors with a descriptor in small file mode. When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a -32 bits machine this function is actually available under the name -@code{pread} and so transparently replaces the 32 bits interface. +32 bit machine this function is actually available under the name +@code{pread} and so transparently replaces the 32 bit interface. @end deftypefun @cindex writing to a file descriptor @@ -470,7 +471,7 @@ In the case of an error, @code{write} returns @math{-1}. The following @item EAGAIN Normally, @code{write} blocks until the write operation is complete. But if the @code{O_NONBLOCK} flag is set for the file (@pxref{Control -Operations}), it returns immediately without writing any data, and +Operations}), it returns immediately without writing any data and reports this error. An example of a situation that might cause the process to block on output is writing to a terminal device that supports flow control, where output has been suspended by receipt of a STOP @@ -498,7 +499,7 @@ The size of the file would become larger than the implementation can support. @item EINTR The @code{write} operation was interrupted by a signal while it was -blocked waiting for completion. A signal will not necessary cause +blocked waiting for completion. A signal will not necessarily cause @code{write} to return @code{EINTR}; it may instead result in a successful @code{write} which writes fewer bytes than requested. @xref{Interrupted Primitives}. @@ -531,12 +532,12 @@ necessary since this function does not directly modify or handle the possibly wide file offset. Since the kernel handles this state internally the @code{write} function can be used for all cases. -This function is a cancelation point in multi-threaded programs. This +This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time @code{write} is -called. If the thread gets canceled these resources stay allocated -until the program ends. To avoid this calls to @code{write} should be -protected using cancelation handlers. +called. If the thread gets cancelled these resources stay allocated +until the program ends. To avoid this, calls to @code{write} should be +protected using cancellation handlers. @c ref pthread_cleanup_push / pthread_cleanup_pop The @code{write} function is the underlying primitive for all of the @@ -547,29 +548,30 @@ functions that write to streams, such as @code{fputc}. @comment Unix98 @deftypefun ssize_t pwrite (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off_t @var{offset}) The @code{pwrite} function is similar to the @code{write} function. The -first three arguments are identical and also the return values and error -codes correspond. +first three arguments are identical, and the return values and error codes +also correspond. The difference is the fourth argument and its handling. The data block is not written to the current position of the file descriptor @code{filedes}. Instead the data is written to the file starting at position @var{offset}. The position of the file descriptor itself is -not effected by the operation. The value is the same as before the call. +not affected by the operation. The value is the same as before the call. When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the @code{pwrite} function is in fact @code{pwrite64} and the type -@code{off_t} has 64 bits which makes it possible to handle files up to +@code{off_t} has 64 bits, which makes it possible to handle files up to @math{2^63} bytes in length. The return value of @code{pwrite} describes the number of written bytes. In the error case it returns @math{-1} like @code{write} does and the -error codes are also the same. Only there are a few more error codes: +error codes are also the same, with these additions: + @table @code @item EINVAL The value given for @var{offset} is negative and therefore illegal. @item ESPIPE -The file descriptor @var{filedes} is associate with a pipe or a FIFO and +The file descriptor @var{filedes} is associated with a pipe or a FIFO and this device does not allow positioning of the file pointer. @end table @@ -582,15 +584,15 @@ version 2. @deftypefun ssize_t pwrite64 (int @var{filedes}, const void *@var{buffer}, size_t @var{size}, off64_t @var{offset}) This function is similar to the @code{pwrite} function. The difference is that the @var{offset} parameter is of type @code{off64_t} instead of -@code{off_t} which makes it possible on 32 bits machines to address +@code{off_t} which makes it possible on 32 bit machines to address files larger than @math{2^31} bytes and up to @math{2^63} bytes. The file descriptor @code{filedes} must be opened using @code{open64} since otherwise the large offsets possible with @code{off64_t} will lead to errors with a descriptor in small file mode. When the source file is compiled using @code{_FILE_OFFSET_BITS == 64} on a -32 bits machine this function is actually available under the name -@code{pwrite} and so transparently replaces the 32 bits interface. +32 bit machine this function is actually available under the name +@code{pwrite} and so transparently replaces the 32 bit interface. @end deftypefun @@ -616,8 +618,8 @@ The @code{lseek} function is used to change the file position of the file with descriptor @var{filedes}. The @var{whence} argument specifies how the @var{offset} should be -interpreted in the same way as for the @code{fseek} function, and must be -one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or +interpreted, in the same way as for the @code{fseek} function, and it must +be one of the symbolic constants @code{SEEK_SET}, @code{SEEK_CUR}, or @code{SEEK_END}. @table @code @@ -684,12 +686,12 @@ When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the @code{off_t} has 64 bits which makes it possible to handle files up to @math{2^63} bytes in length. -This function is a cancelation point in multi-threaded programs. This +This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time @code{lseek} is -called. If the thread gets canceled these resources stay allocated +called. If the thread gets cancelled these resources stay allocated until the program ends. To avoid this calls to @code{lseek} should be -protected using cancelation handlers. +protected using cancellation handlers. @c ref pthread_cleanup_push / pthread_cleanup_pop The @code{lseek} function is the underlying primitive for the @@ -703,7 +705,7 @@ descriptors. @deftypefun off64_t lseek64 (int @var{filedes}, off64_t @var{offset}, int @var{whence}) This function is similar to the @code{lseek} function. The difference is that the @var{offset} parameter is of type @code{off64_t} instead of -@code{off_t} which makes it possible on 32 bits machines to address +@code{off_t} which makes it possible on 32 bit machines to address files larger than @math{2^31} bytes and up to @math{2^63} bytes. The file descriptor @code{filedes} must be opened using @code{open64} since otherwise the large offsets possible with @code{off64_t} will lead to @@ -711,7 +713,7 @@ errors with a descriptor in small file mode. When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a 32 bits machine this function is actually available under the name -@code{lseek} and so transparently replaces the 32 bits interface. +@code{lseek} and so transparently replaces the 32 bit interface. @end deftypefun You can have multiple descriptors for the same file if you open the file @@ -775,7 +777,7 @@ is transparently replaced by @code{off64_t}. @comment Unix98 @deftp {Data Type} off64_t This type is used similar to @code{off_t}. The difference is that even -on 32 bits machines, where the @code{off_t} type would have 32 bits, +on 32 bit machines, where the @code{off_t} type would have 32 bits, @code{off64_t} has 64 bits and so is able to address files up to @math{2^63} bytes in length. @@ -820,7 +822,7 @@ The @var{opentype} argument is interpreted in the same way as for the @code{fopen} function (@pxref{Opening Streams}), except that the @samp{b} option is not permitted; this is because GNU makes no distinction between text and binary files. Also, @code{"w"} and -@code{"w+"} do not cause truncation of the file; these have affect only +@code{"w+"} do not cause truncation of the file; these have an effect only when opening a file, and in this case the file has already been opened. You must make sure that the @var{opentype} argument matches the actual mode of the open file descriptor. @@ -1027,7 +1029,7 @@ Modes}. @cindex scatter-gather Some applications may need to read or write data to multiple buffers, -which are seperated in memory. Although this can be done easily enough +which are separated in memory. Although this can be done easily enough with multiple calls to @code{read} and @code{write}, it is inefficent because there is overhead associated with each kernel call. @@ -1102,8 +1104,8 @@ On modern operating systems, it is possible to @dfn{mmap} (pronounced ``em-map'') a file to a region of memory. When this is done, the file can be accessed just like an array in the program. -This is more efficent than @code{read} or @code{write}, as only regions -of the file a program actually accesses are loaded. Accesses to +This is more efficent than @code{read} or @code{write}, as only the regions +of the file that a program actually accesses are loaded. Accesses to not-yet-loaded parts of the mmapped region are handled in the same way as swapped out pages. @@ -1245,9 +1247,9 @@ The file is on a filesystem that doesn't support mapping. @code{munmap} removes any memory maps from (@var{addr}) to (@var{addr} + @var{length}). @var{length} should be the length of the mapping. -It is safe to un-map multiple mappings in one command, or include unmapped +It is safe to unmap multiple mappings in one command, or include unmapped space in the range. It is also possible to unmap only part of an existing -mapping, however only entire pages can be removed. If @var{length} is not +mapping. However, only entire pages can be removed. If @var{length} is not an even number of pages, it will be rounded up. It returns @math{0} for success and @math{-1} for an error. @@ -1257,7 +1259,7 @@ One error is possible: @table @code @item EINVAL -The memory range given was outside the user mmap range, or wasn't page +The memory range given was outside the user mmap range or wasn't page aligned. @end table @@ -1314,8 +1316,7 @@ There is no existing mapping in at least part of the given region. This function can be used to change the size of an existing memory area. @var{address} and @var{length} must cover a region entirely mapped in the same @code{mmap} statement. A new mapping with the same -characteristics will be returned, but a with the length @var{new_length} -instead. +characteristics will be returned with the length @var{new_length}. One option is possible, @code{MREMAP_MAYMOVE}. If it is given in @var{flags}, the system may remove the existing mapping and create a new @@ -1324,8 +1325,6 @@ one of the desired length in another location. The address of the resulting mapping is returned, or @math{-1}. Possible error codes include: -This function is only available on a few systems. Except for performing -optional optimizations one should not rely on this function. @table @code @item EFAULT @@ -1340,7 +1339,7 @@ The region has pages locked, and if extended it would exceed the process's resource limit for locked pages. @xref{Limits on Resources}. @item ENOMEM -The region is private writable, and insufficent virtual memory is +The region is private writeable, and insufficent virtual memory is available to extend it. Also, this error will occur if @code{MREMAP_MAYMOVE} is not given and the extension would collide with another mapped region. @@ -1348,6 +1347,9 @@ another mapped region. @end table @end deftypefun +This function is only available on a few systems. Except for performing +optional optimizations one should not rely on this function. + Not all file descriptors may be mapped. Sockets, pipes, and most devices only allow sequential access and do not fit into the mapping abstraction. In addition, some regular files may not be mmapable, and older kernels may @@ -1533,20 +1535,20 @@ input from multiple sockets in @ref{Server Example}. @section Synchronizing I/O operations @cindex synchronizing -In most modern operation systems the normal I/O operations are not +In most modern operating systems the normal I/O operations are not executed synchronously. I.e., even if a @code{write} system call returns this does not mean the data is actually written to the media, e.g., the disk. -In situations where synchronization points are necessary the user can -use special functions which ensure that all operations finished before +In situations where synchronization points are necessary,you can use +special functions which ensure that all operations finish before they return. @comment unistd.h @comment X/Open @deftypefun int sync (void) A call to this function will not return as long as there is data which -that is not written to the device. All dirty buffers in the kernel will +has not been written to the device. All dirty buffers in the kernel will be written and so an overall consistent system can be achieved (if no other process in parallel writes data). @@ -1555,9 +1557,9 @@ A prototype for @code{sync} can be found in @file{unistd.h}. The return value is zero to indicate no error. @end deftypefun -More often it is wanted that not all data in the system is committed. -Programs want to ensure that data written to a given file are all -committed and in this situation @code{sync} is overkill. +Programs more often want to ensure that data written to a given file is +committed, rather than all data in the system. For this, @code{sync} is overkill. + @comment unistd.h @comment POSIX @@ -1569,12 +1571,12 @@ finished. A prototype for @code{fsync} can be found in @file{unistd.h}. -This function is a cancelation point in multi-threaded programs. This +This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time @code{fsync} is -called. If the thread gets canceled these resources stay allocated -until the program ends. To avoid this calls to @code{fsync} should be -protected using cancelation handlers. +called. If the thread gets cancelled these resources stay allocated +until the program ends. To avoid this, calls to @code{fsync} should be +protected using cancellation handlers. @c ref pthread_cleanup_push / pthread_cleanup_pop The return value of the function is zero if no error occured. Otherwise @@ -1599,9 +1601,9 @@ recovering of the file in case of a problem. @comment unistd.h @comment POSIX @deftypefun int fdatasync (int @var{fildes}) -When a call to the @code{fdatasync} function returns it is made sure +When a call to the @code{fdatasync} function returns, it is ensured that all of the file data is written to the device. For all pending I/O -operations the parts guaranteeing data integrity finished. +operations, the parts guaranteeing data integrity finished. Not all systems implement the @code{fdatasync} operation. On systems missing this functionality @code{fdatasync} is emulated by a call to @@ -1627,10 +1629,10 @@ No synchronization is possible since the system does not implement this. @section Perform I/O Operations in Parallel The POSIX.1b standard defines a new set of I/O operations which can -reduce the time an application spends waiting at I/O significantly. The +significantly reduce the time an application spends waiting at I/O. The new functions allow a program to initiate one or more I/O operations and -then immediately resume the normal work while the I/O operations are -executed in parallel. The functionality is available if the +then immediately resume normal work while the I/O operations are +executed in parallel. This functionality is available if the @file{unistd.h} file defines the symbol @code{_POSIX_ASYNCHRONOUS_IO}. These functions are part of the library with realtime functions named @@ -1641,7 +1643,7 @@ userlevel. In the latter case it might be necessary to link applications with the thread library @file{libpthread} in addition to @file{librt}. All AIO operations operate on files which were opened previously. There -might be arbitrary many operations for one file running. The +might be arbitrarily many operations running for one file. The asynchronous I/O operations are controlled using a data structure named @code{struct aiocb} (@dfn{AIO control block}). It is defined in @file{aio.h} as follows. @@ -1651,14 +1653,14 @@ asynchronous I/O operations are controlled using a data structure named @deftp {Data Type} {struct aiocb} The POSIX.1b standard mandates that the @code{struct aiocb} structure contains at least the members described in the following table. There -might be more elements which are used by the implementation but +might be more elements which are used by the implementation, but depending on these elements is not portable and is highly deprecated. @table @code @item int aio_fildes This element specifies the file descriptor which is used for the operation. It must be a legal descriptor since otherwise the operation -fails for obvious reasons. +fails. The device on which the file is opened must allow the seek operation. I.e., it is not possible to use any of the AIO operations on devices @@ -1696,9 +1698,9 @@ is created which starts executing the function pointed to by @item int aio_lio_opcode This element is only used by the @code{lio_listio} and -@code{lio_listio64} functions. Since these functions allow to start an -arbitrary number of operations at once and since each operation can be -input or output (or nothing) the information must be stored in the +@code{lio_listio64} functions. Since these functions allow an +arbitrary number of operations to start at once, and each operation can be +input or output (or nothing), the information must be stored in the control block. The possible values are: @vtable @code @@ -1720,13 +1722,13 @@ values must not be handled although the whole array is presented to the @end table When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a -32 bits machine this type is in fact @code{struct aiocb64} since the LFS +32 bit machine this type is in fact @code{struct aiocb64} since the LFS interface transparently replaces the @code{struct aiocb} definition. @end deftp For use with the AIO functions defined in the LFS there is a similar type defined which replaces the types of the appropriate members with larger -types but otherwise is equivalent to @code{struct aiocb}. Especially +types but otherwise is equivalent to @code{struct aiocb}. Particularly, all member names are the same. @comment aio.h @@ -1743,7 +1745,7 @@ I.e., it is not possible to use any of the AIO operations on devices like terminals where an @code{lseek} call would lead to an error. @item off64_t aio_offset -This element specified at which offset in the file the operation (input +This element specifies at which offset in the file the operation (input or output) is performed. Since the operation are carried in arbitrary order and more than one operation for one file descriptor can be started, one cannot expect a current read/write position of the file @@ -1758,7 +1760,7 @@ This element specifies the length of the buffer pointed to by @code{aio_buf}. @item int aio_reqprio If for the platform @code{_POSIX_PRIORITIZED_IO} and -@code{_POSIX_PRIORITY_SCHEDULING} is defined the AIO requests are +@code{_POSIX_PRIORITY_SCHEDULING} are defined the AIO requests are processed based on the current scheduling priority. The @code{aio_reqprio} element can then be used to lower the priority of the AIO operation. @@ -1766,23 +1768,23 @@ AIO operation. @item struct sigevent aio_sigevent This element specifies how the calling process is notified once the operation terminates. If the @code{sigev_notify} element is -@code{SIGEV_NONE} no notification is send. If it is @code{SIGEV_SIGNAL} -the signal determined by @code{sigev_signo} is send. Otherwise +@code{SIGEV_NONE} no notification is sent. If it is @code{SIGEV_SIGNAL} +the signal determined by @code{sigev_signo} is sent. Otherwise @code{sigev_notify} must be @code{SIGEV_THREAD} in which case a thread -which starts executing the function pointeed to by +which starts executing the function pointed to by @code{sigev_notify_function}. @item int aio_lio_opcode This element is only used by the @code{lio_listio} and -@code{[lio_listio64} functions. Since these functions allow to start an -arbitrary number of operations at once and since each operation can be -input or output (or nothing) the information must be stored in the +@code{[lio_listio64} functions. Since these functions allow an +arbitrary number of operations to start at once, and since each operation can be +input or output (or nothing), the information must be stored in the control block. See the description of @code{struct aiocb} for a description of the possible values. @end table When the sources are compiled using @code{_FILE_OFFSET_BITS == 64} on a -32 bits machine this type is available under the name @code{struct +32 bit machine this type is available under the name @code{struct aiocb64} since the LFS replaces transparently the old interface. @end deftp @@ -1790,7 +1792,7 @@ aiocb64} since the LFS replaces transparently the old interface. * Asynchronous Reads/Writes:: Asynchronous Read and Write Operations. * Status of AIO Operations:: Getting the Status of AIO Operations. * Synchronizing AIO Operations:: Getting into a consistent state. -* Cancel AIO Operations:: Cancelation of AIO Operations. +* Cancel AIO Operations:: Cancellation of AIO Operations. * Configuration of AIO:: How to optimize the AIO implementation. @end menu @@ -1800,8 +1802,8 @@ aiocb64} since the LFS replaces transparently the old interface. @comment aio.h @comment POSIX.1b @deftypefun int aio_read (struct aiocb *@var{aiocbp}) -This function initiates an asynchronous read operation. The function -call immediately returns after the operation was enqueued or when an +This function initiates an asynchronous read operation. It +immediately returns after the operation was enqueued or when an error was encountered. The first @code{aiocbp->aio_nbytes} bytes of the file for which @@ -1816,10 +1818,10 @@ the request is actually enqueued. The calling process is notified about the termination of the read request according to the @code{aiocbp->aio_sigevent} value. -When @code{aio_read} returns the return value is zero if no error +When @code{aio_read} returns, the return value is zero if no error occurred that can be found before the process is enqueued. If such an -early error is found the function returns @math{-1} and sets -@code{errno} to one of the following values. +early error is found, the function returns @math{-1} and sets +@code{errno} to one of the following values: @table @code @item EAGAIN @@ -1829,7 +1831,7 @@ limitations. The @code{aio_read} function is not implemented. @item EBADF The @code{aiocbp->aio_fildes} descriptor is not valid. This condition -needs not be recognized before enqueueing the request and so this error +need not be recognized before enqueueing the request and so this error might also be signaled asynchronously. @item EINVAL The @code{aiocbp->aio_offset} or @code{aiocbp->aio_reqpiro} value is @@ -1837,22 +1839,21 @@ invalid. This condition need not be recognized before enqueueing the request and so this error might also be signaled asynchrously. @end table -In the case @code{aio_read} returns zero the current status of the -request can be queried using @code{aio_error} and @code{aio_return} -functions. As long as the value returned by @code{aio_error} is -@code{EINPROGRESS} the operation has not yet completed. If -@code{aio_error} returns zero the operation successfully terminated, -otherwise the value is to be interpreted as an error code. If the -function terminated the result of the operation can be get using a call -to @code{aio_return}. The returned value is the same as an equivalent -call to @code{read} would have returned. Possible error codes returned -by @code{aio_error} are: +If @code{aio_read} returns zero, the current status of the request +can be queried using @code{aio_error} and @code{aio_return} functions. +As long as the value returned by @code{aio_error} is @code{EINPROGRESS} +the operation has not yet completed. If @code{aio_error} returns zero, +the operation successfully terminated, otherwise the value is to be +interpreted as an error code. If the function terminated, the result of +the operation can be obtained using a call to @code{aio_return}. The +returned value is the same as an equivalent call to @code{read} would +have returned. Possible error codes returned by @code{aio_error} are: @table @code @item EBADF The @code{aiocbp->aio_fildes} descriptor is not valid. @item ECANCELED -The operation was canceled before the operation was finished +The operation was cancelled before the operation was finished (@pxref{Cancel AIO Operations}) @item EINVAL The @code{aiocbp->aio_offset} value is invalid. @@ -1867,7 +1868,7 @@ replaces the normal implementation. @comment Unix98 @deftypefun int aio_read64 (struct aiocb *@var{aiocbp}) This function is similar to the @code{aio_read} function. The only -difference is that on @w{32 bits} machines the file descriptor should +difference is that on @w{32 bit} machines the file descriptor should be opened in the large file mode. Internally @code{aio_read64} uses functionality equivalent to @code{lseek64} (@pxref{File Position Primitive}) to position the file descriptor correctly for the reading, @@ -1875,7 +1876,7 @@ as opposed to @code{lseek} functionality used in @code{aio_read}. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this function is available under the name @code{aio_read} and so transparently -replaces the interface for small files on 32 bits machines. +replaces the interface for small files on 32 bit machines. @end deftypefun To write data asynchronously to a file there exists an equivalent pair @@ -1936,7 +1937,7 @@ by @code{aio_error} are: @item EBADF The @code{aiocbp->aio_fildes} descriptor is not valid. @item ECANCELED -The operation was canceled before the operation was finished +The operation was cancelled before the operation was finished (@pxref{Cancel AIO Operations}) @item EINVAL The @code{aiocbp->aio_offset} value is invalid. @@ -1951,7 +1952,7 @@ replaces the normal implementation. @comment Unix98 @deftypefun int aio_write64 (struct aiocb *@var{aiocbp}) This function is similar to the @code{aio_write} function. The only -difference is that on @w{32 bits} machines the file descriptor should +difference is that on @w{32 bit} machines the file descriptor should be opened in the large file mode. Internally @code{aio_write64} uses functionality equivalent to @code{lseek64} (@pxref{File Position Primitive}) to position the file descriptor correctly for the writing, @@ -1959,7 +1960,7 @@ as opposed to @code{lseek} functionality used in @code{aio_write}. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this function is available under the name @code{aio_write} and so transparently -replaces the interface for small files on 32 bits machines. +replaces the interface for small files on 32 bit machines. @end deftypefun Beside these functions with the more or less traditional interface @@ -2055,7 +2056,7 @@ transparently replaces the normal implementation. @comment Unix98 @deftypefun int lio_listio64 (int @var{mode}, struct aiocb *const @var{list}, int @var{nent}, struct sigevent *@var{sig}) This function is similar to the @code{aio_listio} function. The only -difference is that only @w{32 bits} machines the file descriptor should +difference is that only @w{32 bit} machines the file descriptor should be opened in the large file mode. Internally @code{lio_listio64} uses functionality equivalent to @code{lseek64} (@pxref{File Position Primitive}) to position the file descriptor correctly for the reading or @@ -2064,7 +2065,7 @@ writing, as opposed to @code{lseek} functionality used in When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this function is available under the name @code{lio_listio} and so -transparently replaces the interface for small files on 32 bits +transparently replaces the interface for small files on 32 bit machines. @end deftypefun @@ -2072,12 +2073,12 @@ machines. @subsection Getting the Status of AIO Operations As already described in the documentation of the functions in the last -section it must be possible to get information about the status of a I/O -request. When the operation is performed really asynchronous (as with +section, it must be possible to get information about the status of an I/O +request. When the operation is performed truly asynchronously (as with @code{aio_read} and @code{aio_write} and with @code{aio_listio} when the mode is @code{LIO_NOWAIT}) one sometimes needs to know whether a -specific request already terminated and if yes, what the result was.. -The following two function allow to get this kind of information. +specific request already terminated and if yes, what the result was. +The following two functions allow you to get this kind of information. @comment aio.h @comment POSIX.1b @@ -2109,7 +2110,7 @@ aiocb64}. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this function is available under the name @code{aio_error} and so -transparently replaces the interface for small files on 32 bits +transparently replaces the interface for small files on 32 bit machines. @end deftypefun @@ -2145,7 +2146,7 @@ aiocb64}. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this function is available under the name @code{aio_return} and so -transparently replaces the interface for small files on 32 bits +transparently replaces the interface for small files on 32 bit machines. @end deftypefun @@ -2156,7 +2157,7 @@ When dealing with asynchronous operations it is sometimes necessary to get into a consistent state. This would mean for AIO that one wants to know whether a certain request or a group of request were processed. This could be done by waiting for the notification sent by the system -after the operation terminated but this sometimes would mean wasting +after the operation terminated, but this sometimes would mean wasting resources (mainly computation time). Instead POSIX.1b defines two functions which will help with most kinds of consistency. @@ -2171,12 +2172,12 @@ defined. Calling this function forces all I/O operations operating queued at the time of the function call operating on the file descriptor @code{aiocbp->aio_fildes} into the synchronized I/O completion state -(@pxref{Synchronizing I/O}). The @code{aio_fsync} function return +(@pxref{Synchronizing I/O}). The @code{aio_fsync} function returns immediately but the notification through the method described in @code{aiocbp->aio_sigevent} will happen only after all requests for this -file descriptor terminated and the file is synchronized. This also +file descriptor have terminated and the file is synchronized. This also means that requests for this very same file descriptor which are queued -after the synchronization request are not effected. +after the synchronization request are not affected. If @var{op} is @code{O_DSYNC} the synchronization happens as with a call to @code{fdatasync}. Otherwise @var{op} should be @code{O_SYNC} and @@ -2222,7 +2223,7 @@ aiocb64}. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this function is available under the name @code{aio_fsync} and so -transparently replaces the interface for small files on 32 bits +transparently replaces the interface for small files on 32 bit machines. @end deftypefun @@ -2286,12 +2287,12 @@ aiocb64}. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this function is available under the name @code{aio_suspend} and so -transparently replaces the interface for small files on 32 bits +transparently replaces the interface for small files on 32 bit machines. @end deftypefun @node Cancel AIO Operations -@subsection Cancelation of AIO Operations +@subsection Cancellation of AIO Operations When one or more requests are asynchronously processed it might be useful in some situations to cancel a selected operation, e.g., if it @@ -2300,7 +2301,7 @@ have to be overwritten soon. As an example assume an application, which writes data in files in a situation where new incoming data would have to be written in a file which will be updated by an enqueued request. The POSIX AIO implementation provides such a function but this function -is not capable to force the cancelation of the request. It is up to the +is not capable to force the cancellation of the request. It is up to the implementation to decide whether it is possible to cancel the operation or not. Therefore using this function is merely a hint. @@ -2312,26 +2313,26 @@ outstanding requests. If the @var{aiocbp} parameter is @code{NULL} the function tries to cancel all outstanding requests which would process the file descriptor @var{fildes} (i.e.,, whose @code{aio_fildes} member is @var{fildes}). If @var{aiocbp} is not @code{NULL} the very specific -request pointed to by @var{aiocbp} is tried to be canceled. +request pointed to by @var{aiocbp} is tried to be cancelled. -For requests which were successfully canceled the normal notification +For requests which were successfully cancelled the normal notification about the termination of the request should take place. I.e., depending on the @code{struct sigevent} object which controls this, nothing happens, a signal is sent or a thread is started. If the request cannot -be canceled it terminates the usual way after performing te operation. +be cancelled it terminates the usual way after performing te operation. -After a request is successfully canceled a call to @code{aio_error} with +After a request is successfully cancelled a call to @code{aio_error} with a reference to this request as the parameter will return @code{ECANCELED} and a call to @code{aio_return} will return @math{-1}. -If the request wasn't canceled and is still running the error status is +If the request wasn't cancelled and is still running the error status is still @code{EINPROGRESS}. The return value of the function is @code{AIO_CANCELED} if there were -requests which haven't terminated and which successfully were canceled. -If there is one or more request left which couldn't be canceled the +requests which haven't terminated and which successfully were cancelled. +If there is one or more request left which couldn't be cancelled the return value is @code{AIO_NOTCANCELED}. In this case @code{aio_error} must be used to find out which of the perhaps multiple requests (in -@var{aiocbp} is @code{NULL}) wasn't successfully canceled. If all +@var{aiocbp} is @code{NULL}) wasn't successfully cancelled. If all requests already terminated at the time @code{aio_cancel} is called the return value is @code{AIO_ALLDONE}. @@ -2360,7 +2361,7 @@ aiocb64}. When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this function is available under the name @code{aio_cancel} and so -transparently replaces the interface for small files on 32 bits +transparently replaces the interface for small files on 32 bit machines. @end deftypefun @@ -2486,12 +2487,12 @@ Set process or process group ID to receive @code{SIGIO} signals. @xref{Interrupt Input}. @end table -This function is a cancelation point in multi-threaded programs. This +This function is a cancellation point in multi-threaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time @code{fcntl} is -called. If the thread gets canceled these resources stay allocated +called. If the thread gets cancelled these resources stay allocated until the program ends. To avoid this calls to @code{fcntl} should be -protected using cancelation handlers. +protected using cancellation handlers. @c ref pthread_cleanup_push / pthread_cleanup_pop @end deftypefun diff --git a/manual/math.texi b/manual/math.texi index 945ba50..f2736c2 100644 --- a/manual/math.texi +++ b/manual/math.texi @@ -49,7 +49,7 @@ Which of the three versions of a function should be used depends on the situation. For most calculations, the @code{float} functions are the fastest. On the other hand, the @code{long double} functions have the highest precision. @code{double} is somewhere in between. It is -usually wise to pick the narrowest type that can accomodate your data. +usually wise to pick the narrowest type that can accommodate your data. Not all machines have a distinct @code{long double} type; it may be the same as @code{double}. @@ -87,7 +87,7 @@ The natural logarithm of @code{2}. @item M_LN10 The natural logarithm of @code{10}. @item M_PI -Pi, the ratio of a circle's circumrefence to its diameter. +Pi, the ratio of a circle's circumference to its diameter. @item M_PI_2 Pi divided by two. @item M_PI_4 @@ -105,7 +105,7 @@ The reciprocal of the square root of two (also the square root of 1/2). @end vtable These constants come from the Unix98 standard and were also available in -4.4BSD; therefore, they are only defined if @code{_BSD_SOURCE} or +4.4BSD; therefore they are only defined if @code{_BSD_SOURCE} or @code{_XOPEN_SOURCE=500}, or a more general feature select macro, is defined. The default set of features includes these constants. @xref{Feature Test Macros}. @@ -294,7 +294,7 @@ pole. @cindex inverse trigonometric functions These are the usual arc sine, arc cosine and arc tangent functions, -which are the inverses of the sine, cosine and tangent functions, +which are the inverses of the sine, cosine and tangent functions respectively. @comment math.h @@ -544,7 +544,7 @@ These functions extract the exponent of @var{x} and return it as a floating-point value. If @code{FLT_RADIX} is two, @code{logb} is equal to @code{floor (log2 (x))}, except it's probably faster. -If @var{x} is denormalized, @code{logb} returns the exponent @var{x} +If @var{x} is de-normalized, @code{logb} returns the exponent @var{x} would have if it were normalized. If @var{x} is infinity (positive or negative), @code{logb} returns @math{@infinity{}}. If @var{x} is zero, @code{logb} returns @math{@infinity{}}. It does not signal. @@ -685,7 +685,7 @@ much smaller. See also the function @code{cabs} in @ref{Absolute Value}. @deftypefunx {long double} expm1l (long double @var{x}) These functions return a value equivalent to @code{exp (@var{x}) - 1}. They are computed in a way that is accurate even if @var{x} is -near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due +near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate owing to subtraction of two numbers that are nearly equal. @end deftypefun @@ -720,7 +720,7 @@ logarithm functions. @deftypefunx {complex long double} cexpl (complex long double @var{z}) These functions return @code{e} (the base of natural logarithms) raised to the power of @var{z}. -Mathematically this corresponds to the value +Mathematically, this corresponds to the value @ifinfo @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))} @@ -740,7 +740,7 @@ $$\exp(z) = e^z = e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$ @comment ISO @deftypefunx {complex long double} clogl (complex long double @var{z}) These functions return the natural logarithm of @var{z}. -Mathematically this corresponds to the value +Mathematically, this corresponds to the value @ifinfo @math{log (z) = log (cabs (z)) + I * carg (z)} @@ -766,7 +766,7 @@ or is very close to 0. It is well-defined for all other values of @comment GNU @deftypefunx {complex long double} clog10l (complex long double @var{z}) These functions return the base 10 logarithm of the complex value -@var{z}. Mathematically this corresponds to the value +@var{z}. Mathematically, this corresponds to the value @ifinfo @math{log (z) = log10 (cabs (z)) + I * carg (z)} @@ -992,7 +992,7 @@ the real-valued functions, there are no restrictions on the value of @cindex Bessel functions @cindex gamma function -These are some more exotic mathematical functions, which are sometimes +These are some more exotic mathematical functions which are sometimes useful. Currently they only have real-valued versions. @comment math.h @@ -1052,7 +1052,7 @@ gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt @vindex signgam The sign of the gamma function is stored in the global variable @var{signgam}, which is declared in @file{math.h}. It is @code{1} if -the intermediate result was positive or zero, and, @code{-1} if it was +the intermediate result was positive or zero, or @code{-1} if it was negative. To compute the real gamma function you can use the @code{tgamma} @@ -1062,7 +1062,7 @@ lgam = lgamma(x); gam = signgam*exp(lgam); @end smallexample -The gamma function has singularities at the nonpositive integers. +The gamma function has singularities at the non-positive integers. @code{lgamma} will raise the zero divide exception if evaluated at a singularity. @end deftypefun @@ -1078,7 +1078,7 @@ singularity. @deftypefunx {long double} lgammal_r (long double @var{x}, int *@var{signp}) @code{lgamma_r} is just like @code{lgamma}, but it stores the sign of the intermediate result in the variable pointed to by @var{signp} -instead of in the @var{signgam} global. +instead of in the @var{signgam} global. This means it is reentrant. @end deftypefun @comment math.h @@ -1092,7 +1092,7 @@ instead of in the @var{signgam} global. @deftypefunx {long double} gammal (long double @var{x}) These functions exist for compatibility reasons. They are equivalent to @code{lgamma} etc. It is better to use @code{lgamma} since for one the -name reflects better the actual computation and @code{lgamma} is also +name reflects better the actual computation, moreover @code{lgamma} is standardized in @w{ISO C 9x} while @code{gamma} is not. @end deftypefun @@ -1225,7 +1225,7 @@ pseudo-random series each time your program runs, you must specify a different seed each time. For ordinary purposes, basing the seed on the current time works well. -You can get repeatable sequences of numbers on a particular machine type +You can obtain repeatable sequences of numbers on a particular machine type by specifying the same initial seed value for the random number generator. There is no standard meaning for a particular seed value; the same seed, used in different C libraries or on different CPU types, @@ -1322,10 +1322,10 @@ The prototypes for these functions are in @file{stdlib.h}. This function returns the next pseudo-random number in the sequence. The value returned ranges from @code{0} to @code{RAND_MAX}. -@strong{Note:} Historically this function returned a @code{long -int} value. On 64bit systems @code{long int} would have been larger -than programs expected, so @code{random} is now defined to return -exactly 32 bits. +@strong{Note:} Historically this function returned a @code{long int} +value. On 64-bit systems @code{long int} would have been larger than +programs expected, so @code{random} is now defined to return exactly 32 +bits. @end deftypefun @comment stdlib.h @@ -1374,10 +1374,10 @@ generator functions. They use a state of 48 bits of data. The user can choose among a collection of functions which return the random bits in different forms. -Generally there are two kinds of functions: those which use a state of +Generally there are two kinds of function. The first uses a state of the random number generator which is shared among several functions and -by all threads of the process. The second group of functions require -the user to handle the state. +by all threads of the process. The second requires the user to handle +the state. All functions have in common that they use the same congruential formula with the same constants. The formula is @@ -1389,7 +1389,7 @@ Y = (a * X + c) mod m @noindent where @var{X} is the state of the generator at the beginning and @var{Y} the state at the end. @code{a} and @code{c} are constants -determining the way the generator work. By default they are +determining the way the generator works. By default they are @smallexample a = 0x5DEECE66D = 25214903917 @@ -1398,7 +1398,7 @@ c = 0xb = 11 @noindent but they can also be changed by the user. @code{m} is of course 2^48 -since the state consists of a 48 bit array. +since the state consists of a 48-bit array. @comment stdlib.h @@ -1408,7 +1408,7 @@ This function returns a @code{double} value in the range of @code{0.0} to @code{1.0} (exclusive). The random bits are determined by the global state of the random number generator in the C library. -Since the @code{double} type according to @w{IEEE 754} has a 52 bit +Since the @code{double} type according to @w{IEEE 754} has a 52-bit mantissa this means 4 bits are not initialized by the random number generator. These are (of course) chosen to be the least significant bits and they are initialized to @code{0}. @@ -1418,20 +1418,20 @@ bits and they are initialized to @code{0}. @comment SVID @deftypefun double erand48 (unsigned short int @var{xsubi}[3]) This function returns a @code{double} value in the range of @code{0.0} -to @code{1.0} (exclusive), similar to @code{drand48}. The argument is +to @code{1.0} (exclusive), similarly to @code{drand48}. The argument is an array describing the state of the random number generator. This function can be called subsequently since it updates the array to guarantee random numbers. The array should have been initialized before -using to get reproducible results. +initial use to obtain reproducible results. @end deftypefun @comment stdlib.h @comment SVID @deftypefun {long int} lrand48 (void) -The @code{lrand48} functions return an integer value in the range of +The @code{lrand48} function returns an integer value in the range of @code{0} to @code{2^31} (exclusive). Even if the size of the @code{long -int} type can take more than 32 bits no higher numbers are returned. +int} type can take more than 32 bits, no higher numbers are returned. The random bits are determined by the global state of the random number generator in the C library. @end deftypefun @@ -1444,10 +1444,10 @@ returns a number in the range of @code{0} to @code{2^31} (exclusive) but the state of the random number generator used to produce the random bits is determined by the array provided as the parameter to the function. -The numbers in the array are afterwards updated so that subsequent calls -to this function yield to different results (as it is expected by a -random number generator). The array should have been initialized before -the first call to get reproducible results. +The numbers in the array are updated afterwards so that subsequent calls +to this function yield different results (as is expected of a random +number generator). The array should have been initialized before the +first call to obtain reproducible results. @end deftypefun @comment stdlib.h @@ -1468,33 +1468,33 @@ requirements are necessary. @end deftypefun The internal state of the random number generator can be initialized in -several ways. The functions differ in the completeness of the +several ways. The methods differ in the completeness of the information provided. @comment stdlib.h @comment SVID -@deftypefun void srand48 (long int @var{seedval})) +@deftypefun void srand48 (long int @var{seedval}) The @code{srand48} function sets the most significant 32 bits of the -state internal state of the random number generator to the least +internal state of the random number generator to the least significant 32 bits of the @var{seedval} parameter. The lower 16 bits are initialized to the value @code{0x330E}. Even if the @code{long -int} type contains more the 32 bits only the lower 32 bits are used. +int} type contains more than 32 bits only the lower 32 bits are used. -Due to this limitation the initialization of the state using this -function of not very useful. But it makes it easy to use a construct +Owing to this limitation, initialization of the state of this +function is not very useful. But it makes it easy to use a construct like @code{srand48 (time (0))}. A side-effect of this function is that the values @code{a} and @code{c} from the internal state, which are used in the congruential formula, are reset to the default values given above. This is of importance once -the user called the @code{lcong48} function (see below). +the user has called the @code{lcong48} function (see below). @end deftypefun @comment stdlib.h @comment SVID @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3]) The @code{seed48} function initializes all 48 bits of the state of the -internal random number generator from the content of the parameter +internal random number generator from the contents of the parameter @var{seed16v}. Here the lower 16 bits of the first element of @var{see16v} initialize the least significant 16 bits of the internal state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order @@ -1507,15 +1507,15 @@ of the state. The value returned by @code{seed48} is a pointer to an array containing the values of the internal state before the change. This might be useful to restart the random number generator at a certain state. -Otherwise, the value can simply be ignored. +Otherwise the value can simply be ignored. As for @code{srand48}, the values @code{a} and @code{c} from the congruential formula are reset to the default values. @end deftypefun There is one more function to initialize the random number generator -which allows to specify even more information by allowing to change the -parameters in the congruential formula. +which enables you to specify even more information by allowing you to +change the parameters in the congruential formula. @comment stdlib.h @comment SVID @@ -1527,9 +1527,9 @@ congruential formula. From the seven elements in the array @var{param} the least significant 16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]} -determine the initial state, the least 16 bits of +determine the initial state, the least significant 16 bits of @code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit -constant @code{a} and @code{@var{param}[6]} determines the 16 bit value +constant @code{a} and @code{@var{param}[6]} determines the 16-bit value @code{c}. @end deftypefun @@ -1544,22 +1544,21 @@ Please note that it is no problem if several threads use the global state if all threads use the functions which take a pointer to an array containing the state. The random numbers are computed following the same loop but if the state in the array is different all threads will -get an individual random number generator. +obtain an individual random number generator. -The user supplied buffer must be of type @code{struct drand48_data}. -This type should be regarded as opaque and no member should be used -directly. +The user-supplied buffer must be of type @code{struct drand48_data}. +This type should be regarded as opaque and not manipulated directly. @comment stdlib.h @comment GNU @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result}) This function is equivalent to the @code{drand48} function with the -difference it does not modify the global random number generator -parameters but instead the parameters is the buffer supplied by the -buffer through the pointer @var{buffer}. The random number is return in -the variable pointed to by @var{result}. +difference that it does not modify the global random number generator +parameters but instead the parameters in the buffer supplied through the +pointer @var{buffer}. The random number is returned in the variable +pointed to by @var{result}. -The return value of the function indicate whether the call succeeded. +The return value of the function indicates whether the call succeeded. If the value is less than @code{0} an error occurred and @var{errno} is set to indicate the problem. @@ -1570,14 +1569,14 @@ programs. @comment stdlib.h @comment GNU @deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result}) -The @code{erand48_r} function works like the @code{erand48} and it takes -an argument @var{buffer} which describes the random number generator. -The state of the random number generator is taken from the @code{xsubi} -array, the parameters for the congruential formula from the global -random number generator data. The random number is return in the -variable pointed to by @var{result}. +The @code{erand48_r} function works like @code{erand48}, but in addition +it takes an argument @var{buffer} which describes the random number +generator. The state of the random number generator is taken from the +@code{xsubi} array, the parameters for the congruential formula from the +global random number generator data. The random number is returned in +the variable pointed to by @var{result}. -The return value is non-negative is the call succeeded. +The return value is non-negative if the call succeeded. This function is a GNU extension and should not be used in portable programs. @@ -1586,9 +1585,9 @@ programs. @comment stdlib.h @comment GNU @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result}) -This function is similar to @code{lrand48} and it takes a pointer to a -buffer describing the state of the random number generator as a -parameter just like @code{drand48}. +This function is similar to @code{lrand48}, but in addition it takes a +pointer to a buffer describing the state of the random number generator +just like @code{drand48}. If the return value of the function is non-negative the variable pointed to by @var{result} contains the result. Otherwise an error occurred. @@ -1601,7 +1600,7 @@ programs. @comment GNU @deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result}) The @code{nrand48_r} function works like @code{nrand48} in that it -produces a random number in range @code{0} to @code{2^31}. But instead +produces a random number in the range @code{0} to @code{2^31}. But instead of using the global parameters for the congruential formula it uses the information from the buffer pointed to by @var{buffer}. The state is described by the values in @var{xsubi}. @@ -1616,8 +1615,8 @@ programs. @comment stdlib.h @comment GNU @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result}) -This function is similar to @code{mrand48} but as the other reentrant -function it uses the random number generator described by the value in +This function is similar to @code{mrand48} but like the other reentrant +functions it uses the random number generator described by the value in the buffer pointed to by @var{buffer}. If the return value is non-negative the variable pointed to by @@ -1630,7 +1629,7 @@ programs. @comment stdlib.h @comment GNU @deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result}) -The @code{jrand48_r} function is similar to @code{jrand48}. But as the +The @code{jrand48_r} function is similar to @code{jrand48}. Like the other reentrant functions of this function family it uses the congruential formula parameters from the buffer pointed to by @var{buffer}. @@ -1642,9 +1641,9 @@ This function is a GNU extension and should not be used in portable programs. @end deftypefun -Before any of the above functions should be used the buffer of type -@code{struct drand48_data} should initialized. The easiest way is to -fill the whole buffer with null bytes, e.g., using +Before any of the above functions are used the buffer of type +@code{struct drand48_data} should be initialized. The easiest way to do +this is to fill the whole buffer with null bytes, e.g. by @smallexample memset (buffer, '\0', sizeof (struct drand48_data)); @@ -1655,9 +1654,9 @@ Using any of the reentrant functions of this family now will automatically initialize the random number generator to the default values for the state and the parameters of the congruential formula. -The other possibility is too use any of the functions which explicitely +The other possibility is to use any of the functions which explicitly initialize the buffer. Though it might be obvious how to initialize the -buffer from the data given as parameter from the function it is highly +buffer from looking at the parameter to the function, it is highly recommended to use these functions since the result might not always be what you expect. @@ -1665,10 +1664,10 @@ what you expect. @comment GNU @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer}) The description of the random number generator represented by the -information in @var{buffer} is initialized similar to what the function +information in @var{buffer} is initialized similarly to what the function @code{srand48} does. The state is initialized from the parameter @var{seedval} and the parameters for the congruential formula are -initialized to the default values. +initialized to their default values. If the return value is non-negative the function call succeeded. @@ -1684,8 +1683,8 @@ initializes all 48 bits of the state from the parameter @var{seed16v}. If the return value is non-negative the function call succeeded. It does not return a pointer to the previous state of the random number -generator like the @code{seed48} function does. if the user wants to -preserve the state for a later rerun s/he can copy the whole buffer +generator like the @code{seed48} function does. If the user wants to +preserve the state for a later re-run s/he can copy the whole buffer pointed to by @var{buffer}. This function is a GNU extension and should not be used in portable @@ -1696,11 +1695,11 @@ programs. @comment GNU @deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer}) This function initializes all aspects of the random number generator -described in @var{buffer} by the data in @var{param}. Here it is -especially true the function does more than just copying the contents of -@var{param} of @var{buffer}. Some more actions are required and -therefore it is important to use this function and not initialized the -random number generator directly. +described in @var{buffer} with the data in @var{param}. Here it is +especially true that the function does more than just copying the +contents of @var{param} and @var{buffer}. More work is required and +therefore it is important to use this function rather than initializing +the random number generator directly. If the return value is non-negative the function call succeeded. @@ -1712,23 +1711,22 @@ programs. @section Is Fast Code or Small Code preferred? @cindex Optimization -If an application uses many floating point function it is often the case -that the costs for the function calls itselfs are not neglectable. -Modern processor implementation often can execute the operation itself -very fast but the call means a disturbance of the control flow. +If an application uses many floating point functions it is often the case +that the cost of the function calls themselves is not negligible. +Modern processors can often execute the operations themselves +very fast, but the function call disrupts the instruction pipeline. For this reason the GNU C Library provides optimizations for many of the -frequently used math functions. When the GNU CC is used and the user -activates the optimizer several new inline functions and macros get +frequently-used math functions. When GNU CC is used and the user +activates the optimizer, several new inline functions and macros are defined. These new functions and macros have the same names as the -library function and so get used instead of the later. In case of +library functions and so are used instead of the latter. In the case of inline functions the compiler will decide whether it is reasonable to -use the inline function and this decision is usually correct. +use them, and this decision is usually correct. -For the generated code this means that no calls to the library functions -are necessary. This increases the speed significantly. But the -drawback is that the code size increases and this increase is not always -neglectable. +This means that no calls to the library functions may be necessary, and +can increase the speed of generated code significantly. The drawback is +that code size will increase, and the increase is not always negligible. The speed increase has one drawback: the inline functions might not set @code{errno} and might not have the same precission as the library @@ -1736,12 +1734,12 @@ functions. In cases where the inline functions and macros are not wanted the symbol @code{__NO_MATH_INLINES} should be defined before any system header is -included. This will make sure only library functions are used. Of -course it can be determined for each single file in the project whether -giving this option is preferred or not. - -Not all hardware implements the entire @w{IEEE 754} standard, or if it -does, there may be a substantial performance penalty for using some of -its features. For example, enabling traps on some processors forces -the FPU to run unpipelined, which more than doubles calculation time. +included. This will ensure that only library functions are used. Of +course, it can be determined for each file in the project whether +giving this option is preferable or not. + +Not all hardware implements the entire @w{IEEE 754} standard, and even +if it does there may be a substantial performance penalty for using some +of its features. For example, enabling traps on some processors forces +the FPU to run un-pipelined, which can more than double calculation time. @c ***Add explanation of -lieee, -mieee. diff --git a/manual/nss.texi b/manual/nss.texi index e3ff131..3037645 100644 --- a/manual/nss.texi +++ b/manual/nss.texi @@ -267,7 +267,7 @@ missing. For the @code{hosts} and @code{networks} databases the default value is @code{dns [!UNAVAIL=return] files}. I.e., the system is prepared for the DNS service not to be available but if it is available the answer it -returns is ultimative. +returns is definitive. The @code{passwd}, @code{group}, and @code{shadow} databases are traditionally handled in a special way. The appropriate files in the @@ -297,7 +297,7 @@ But one should avoid slow services like this if possible. @node NSS Module Internals, Extending NSS, NSS Configuration File, Name Service Switch @section NSS Module Internals -Now it is time to described how the modules look like. The functions +Now it is time to describe what the modules look like. The functions contained in a module are identified by their names. I.e., there is no jump table or the like. How this is done is of no interest here; those interested in this topic should read about Dynamic Linking. @@ -322,8 +322,8 @@ The name of each function consist of various parts: @end quotation @var{service} of course corresponds to the name of the module this -function is found in.@footnote{Now you might ask why to duplicate this -information. The answer is that we want to keep the possibility to link +function is found in.@footnote{Now you might ask why this information is +duplicated. The answer is that we want to make it possible to link directly with these shared objects.} The @var{function} part is derived from the interface function in the C library itself. If the user calls the function @code{gethostbyname} and the service used is @code{files} @@ -364,14 +364,12 @@ Sun's NSS modules are usable as modules which get indirectly loaded only. The NSS modules in the GNU C Library are prepared to be used as normal -libraries itself. -@comment Fix me if necessary. -This is @emph{not} true in the moment, though. But the different -organization of the name space in the modules does not make it +libraries themselves. This is @emph{not} true at the moment, though. +However, the organization of the name space in the modules does not make it impossible like it is for Solaris. Now you can see why the modules are still libraries.@footnote{There is a second explanation: we were too lazy to change the Makefiles to allow the generation of shared objects -not starting with @file{lib} but do not tell this anybody.} +not starting with @file{lib} but don't tell this to anybody.} @node NSS Modules Interface, , NSS Module Names, NSS Module Internals @@ -441,7 +439,7 @@ more. @multitable @columnfractions .3 .2 .50 @item @code{NSS_STATUS_TRYAGAIN} @tab - @code{EAGAIN} @tab One functions used ran temporarily out of + @code{EAGAIN} @tab One of the functions used ran temporarily out of resources or a service is currently not available. @item @tab @@ -481,7 +479,7 @@ signature of the module function: @item the return value is @code{int}; @item -the name is as explain in @pxref{NSS Module Names}; +the name is as explained in @pxref{NSS Module Names}; @item the first arguments are identical to the arguments of the non-reentrant function; @@ -561,11 +559,11 @@ more about this command line. To use the new module the library must be able to find it. This can be achieved by using options for the dynamic linker so that it will search -directory where the binary is placed. For an ELF system this could be +the directory where the binary is placed. For an ELF system this could be done by adding the wanted directory to the value of @code{LD_LIBRARY_PATH}. -But this is not always possible since some program (those which run +But this is not always possible since some programs (those which run under IDs which do not belong to the user) ignore this variable. Therefore the stable version of the module should be placed into a directory which is searched by the dynamic linker. Normally this should @@ -579,7 +577,7 @@ cause any harm. System administrators should be careful. @subsection Internals of the NSS Module Functions Until now we only provided the syntactic interface for the functions in -the NSS module. In fact there is not more much we can tell since the +the NSS module. In fact there is not much more we can say since the implementation obviously is different for each function. But a few general rules must be followed by all functions. @@ -635,7 +633,7 @@ As explained above this function could also have an additional last argument. This depends on the database used; it happens only for @code{host} and @code{networks}. -The function shall return @code{NSS_STATUS_SUCCESS} as long as their are +The function shall return @code{NSS_STATUS_SUCCESS} as long as there are more entries. When the last entry was read it should return @code{NSS_STATUS_NOTFOUND}. When the buffer given as an argument is too small for the data to be returned @code{NSS_STATUS_TRYAGAIN} should be diff --git a/manual/pipe.texi b/manual/pipe.texi index 9050ec8..67e446f 100644 --- a/manual/pipe.texi +++ b/manual/pipe.texi @@ -95,7 +95,7 @@ read by the child process. @cindex filtering i/o through subprocess A common use of pipes is to send data to or receive data from a program -being run as subprocess. One way of doing this is by using a combination of +being run as a subprocess. One way of doing this is by using a combination of @code{pipe} (to create the pipe), @code{fork} (to create the subprocess), @code{dup2} (to force the subprocess to use the pipe as its standard input or output channel), and @code{exec} (to execute the new program). Or, @@ -123,7 +123,7 @@ write to the stream to send data to the standard input channel of the subprocess. The subprocess inherits its standard output channel from the parent process. -In the event of an error, @code{popen} returns a null pointer. This +In the event of an error @code{popen} returns a null pointer. This might happen if the pipe or stream cannot be created, if the subprocess cannot be forked, or if the program cannot be executed. @end deftypefun @@ -198,7 +198,7 @@ is not greater than @code{PIPE_BUF}. This means that the data transfer seems to be an instantaneous unit, in that nothing else in the system can observe a state in which it is partially complete. Atomic I/O may not begin right away (it may need to wait for buffer space or for data), -but once it does begin, it finishes immediately. +but once it does begin it finishes immediately. Reading or writing a larger amount of data may not be atomic; for example, output data from other processes sharing the descriptor may be diff --git a/manual/signal.texi b/manual/signal.texi index 15458c2..08ee785 100644 --- a/manual/signal.texi +++ b/manual/signal.texi @@ -1659,7 +1659,7 @@ the past. Here is an example of a handler for @code{SIGCHLD} that compensates for the fact that the number of signals received may not equal the number of -child processes generate them. It assumes that the program keeps track +child processes that generate them. It assumes that the program keeps track of all the child processes with a chain of structures as follows: @smallexample @@ -1809,7 +1809,7 @@ sig_atomic_t last_process_status_change; Handler functions usually don't do very much. The best practice is to write a handler that does nothing but set an external variable that the program checks regularly, and leave all serious work to the program. -This is best because the handler can be called at asynchronously, at +This is best because the handler can be called asynchronously, at unpredictable times---perhaps in the middle of a primitive function, or even between the beginning and the end of a C operator that requires multiple instructions. The data structures being manipulated might @@ -1856,8 +1856,8 @@ blocks signals around each use, then you are safe. There are a large number of library functions that return values in a fixed object, always reusing the same object in this fashion, and all of -them cause the same problem. The description of a function in this -manual always mentions this behavior. +them cause the same problem. Function descriptions in this manual +always mention this behavior. @item If a function uses and modifies an object that you supply, then it is @@ -1940,7 +1940,7 @@ Whether the data in your application concerns atoms, or mere text, you have to be careful about the fact that access to a single datum is not necessarily @dfn{atomic}. This means that it can take more than one instruction to read or write a single object. In such cases, a signal -handler might in the middle of reading or writing the object. +handler might be invoked in the middle of reading or writing the object. There are three ways you can cope with this problem. You can use data types that are always accessed atomically; you can carefully arrange @@ -2031,9 +2031,9 @@ atomically. In practice, you can assume that @code{int} and other integer types no longer than @code{int} are atomic. You can also assume that pointer -types are atomic; that is very convenient. Both of these are true on -all of the machines that the GNU C library supports, and on all POSIX -systems we know of. +types are atomic; that is very convenient. Both of these assumptions +are true on all of the machines that the GNU C library supports and on +all POSIX systems we know of. @c ??? This might fail on a 386 that uses 64-bit pointers. @node Atomic Usage @@ -2846,7 +2846,7 @@ not only within @code{update_mumble}, but also within the caller. This is also why we do not check @code{signal_pending} if @code{defer_signal} is still nonzero. -The incrementing and decrementing of @code{defer_signal} require more +The incrementing and decrementing of @code{defer_signal} each require more than one instruction; it is possible for a signal to happen in the middle. But that does not cause any problem. If the signal happens early enough to see the value from before the increment or decrement, @@ -2932,12 +2932,12 @@ The function was interrupted by delivery of a signal. If the signal causes program termination, @code{pause} doesn't return (obviously). -This function is a cancelation point in multi-threaded programs. This +This function is a cancellation point in multithreaded programs. This is a problem if the thread allocates some resources (like memory, file descriptors, semaphores or whatever) at the time @code{pause} is -called. If the thread gets canceled these resources stay allocated +called. If the thread gets cancelled these resources stay allocated until the program ends. To avoid this calls to @code{pause} should be -protected using cancelation handlers. +protected using cancellation handlers. @c ref pthread_cleanup_push / pthread_cleanup_pop The @code{pause} function is declared in @file{unistd.h}. diff --git a/manual/socket.texi b/manual/socket.texi index 448962f..53bdc5b 100644 --- a/manual/socket.texi +++ b/manual/socket.texi @@ -8,18 +8,17 @@ communication using sockets. @cindex socket @cindex interprocess communication, with sockets A @dfn{socket} is a generalized interprocess communication channel. -Like a pipe, a socket is represented as a file descriptor. But, -unlike pipes, sockets support communication between unrelated -processes, and even between processes running on different machines -that communicate over a network. Sockets are the primary means of -communicating with other machines; @code{telnet}, @code{rlogin}, -@code{ftp}, @code{talk}, and the other familiar network programs use -sockets. +Like a pipe, a socket is represented as a file descriptor. Unlike pipes +sockets support communication between unrelated processes, and even +between processes running on different machines that communicate over a +network. Sockets are the primary means of communicating with other +machines; @code{telnet}, @code{rlogin}, @code{ftp}, @code{talk} and the +other familiar network programs use sockets. Not all operating systems support sockets. In the GNU library, the header file @file{sys/socket.h} exists regardless of the operating system, and the socket functions always exist, but if the system does -not really support sockets, these functions always fail. +not really support sockets these functions always fail. @strong{Incomplete:} We do not currently document the facilities for broadcast messages or for configuring Internet interfaces. The @@ -28,7 +27,7 @@ aren't documented either so far. @menu * Socket Concepts:: Basic concepts you need to know about. -* Communication Styles::Stream communication, datagrams, and other styles. +* Communication Styles::Stream communication, datagrams and other styles. * Socket Addresses:: How socket names (``addresses'') work. * Interface Naming:: Identifying specific network interfaces. * Local Namespace:: Details about the local namespace. @@ -61,7 +60,7 @@ communication style specifies the answers to questions such as these: @cindex byte stream @cindex stream (sockets) @strong{What are the units of data transmission?} Some communication -styles regard the data as a sequence of bytes, with no larger +styles regard the data as a sequence of bytes with no larger structure; others group the bytes into records (which are known in this context as @dfn{packets}). @@ -81,7 +80,7 @@ to retransmit data as needed. @item @strong{Is communication entirely with one partner?} Some communication styles are like a telephone call---you make a -@dfn{connection} with one remote socket, and then exchange data +@dfn{connection} with one remote socket and then exchange data freely. Other styles are like mailing letters---you specify a destination address for each message you send. @end itemize @@ -112,7 +111,7 @@ start with @samp{PF_}. The rules of a protocol apply to the data passing between two programs, perhaps on different computers; most of these rules are handled by the -operating system, and you need not know about them. What you do need to +operating system and you need not know about them. What you do need to know about protocols is this: @itemize @bullet @@ -127,30 +126,30 @@ example, the TCP protocol fits only the byte stream style of communication and the Internet namespace. @item -For each combination of style and namespace, there is a @dfn{default -protocol} which you can request by specifying 0 as the protocol +For each combination of style and namespace there is a @dfn{default +protocol}, which you can request by specifying 0 as the protocol number. And that's what you should normally do---use the default. @end itemize Throughout the following description at various places variables/parameters to denote sizes are required. And here the trouble starts. In the first implementations the type of these variables was -simply @code{int}. This type was on almost all machines of this time 32 -bits wide and so a de-factor standard required 32 bit variables. This -is important since references to variables of this type are passed to -the kernel. - -But then the POSIX people came and unified the interface with the words -"all size values are of type @code{size_t}". But on 64 bit machines -@code{size_t} is 64 bits wide, and so variable references are not anymore +simply @code{int}. On most machines at that time an @code{int} was 32 +bits wide, which created a @emph{de facto} standard requiring 32-bit +variables. This is important since references to variables of this type +are passed to the kernel. + +Then the POSIX people came and unified the interface with the words "all +size values are of type @code{size_t}". On 64-bit machines +@code{size_t} is 64 bits wide, so pointers to variables were no longer possible. The Unix98 specification provides a solution by introducing a type @code{socklen_t}. This type is used in all of the cases that POSIX changed to use @code{size_t}. The only requirement of this type is that it be an unsigned type of at least 32 bits. Therefore, implementations -which require that references to 32 bit variables be passed can be as -happy as implementations which use 64 bit values. +which require that references to 32-bit variables be passed can be as +happy as implementations which use 64-bit values. @node Communication Styles @@ -165,8 +164,8 @@ defined in @file{sys/socket.h}. @comment sys/socket.h @comment BSD @deftypevr Macro int SOCK_STREAM -The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}); -it operates over a connection with a particular remote socket, and +The @code{SOCK_STREAM} style is like a pipe (@pxref{Pipes and FIFOs}). +It operates over a connection with a particular remote socket and transmits data reliably as a stream of bytes. Use of this style is covered in detail in @ref{Connections}. @@ -176,7 +175,7 @@ Use of this style is covered in detail in @ref{Connections}. @comment BSD @deftypevr Macro int SOCK_DGRAM The @code{SOCK_DGRAM} style is used for sending -individually-addressed packets, unreliably. +individually-addressed packets unreliably. It is the diametrical opposite of @code{SOCK_STREAM}. Each time you write data to a socket of this kind, that data becomes @@ -190,7 +189,7 @@ fourth and fifth packets; the seventh packet may arrive before the sixth, and may arrive a second time after the sixth. The typical use for @code{SOCK_DGRAM} is in situations where it is -acceptable to simply resend a packet if no response is seen in a +acceptable to simply re-send a packet if no response is seen in a reasonable amount of time. @xref{Datagrams}, for detailed information about how to use datagram @@ -203,7 +202,7 @@ sockets. @comment sys/socket.h @comment BSD @deftypevr Macro int SOCK_SEQPACKET -This style is like @code{SOCK_STREAM} except that the data is +This style is like @code{SOCK_STREAM} except that the data are structured into packets. A program that receives data over a @code{SOCK_SEQPACKET} socket @@ -262,7 +261,7 @@ you send data from a socket, or use it to initiate a connection, the system assigns an address automatically if you have not specified one. Occasionally a client needs to specify an address because the server -discriminates based on addresses; for example, the rsh and rlogin +discriminates based on address; for example, the rsh and rlogin protocols look at the client's socket address and only bypass password checking if it is less than @code{IPPORT_RESERVED} (@pxref{Ports}). @@ -293,12 +292,12 @@ address. You can't use this data type effectively to interpret an address or construct one; for that, you must use the proper data type for the socket's namespace. -Thus, the usual practice is to construct an address in the proper +Thus, the usual practice is to construct an address of the proper namespace-specific type, then cast a pointer to @code{struct sockaddr *} when you call @code{bind} or @code{getsockname}. The one piece of information that you can get from the @code{struct -sockaddr} data type is the @dfn{address format} designator which tells +sockaddr} data type is the @dfn{address format designator}. This tells you which data type to use to understand the address fully. @pindex sys/socket.h @@ -376,8 +375,8 @@ for completeness, but there is no reason to use it in a program. @end table @file{sys/socket.h} defines symbols starting with @samp{AF_} for many -different kinds of networks, all or most of which are not actually -implemented. We will document those that really work, as we receive +different kinds of networks, most or all of which are not actually +implemented. We will document those that really work as we receive information about how to use them. @node Setting Address @@ -395,7 +394,7 @@ The @code{bind} function assigns an address to the socket @var{socket}. The @var{addr} and @var{length} arguments specify the address; the detailed format of the address depends on the namespace. The first part of the address is always the format designator, which -specifies a namespace, and says that the address is in the format for +specifies a namespace, and says that the address is in the format of that namespace. The return value is @code{0} on success and @code{-1} on failure. The @@ -566,15 +565,15 @@ as file names. @node Local Namespace Concepts @subsection Local Namespace Concepts -In the local namespace, socket addresses are file names. You can specify +In the local namespace socket addresses are file names. You can specify any file name you want as the address of the socket, but you must have write permission on the directory containing it. In order to connect to -a socket, you must have read permission for it. It's common to put +a socket you must have read permission for it. It's common to put these files in the @file{/tmp} directory. -One peculiarity of the local namespace is that the name is only used when -opening the connection; once that is over with, the address is not -meaningful and may not exist. +One peculiarity of the local namespace is that the name is only used +when opening the connection; once open the address is not meaningful and +may not exist. Another peculiarity is that you cannot connect to such a socket from another machine--not even if the other machine shares the file system @@ -582,7 +581,7 @@ which contains the name of the socket. You can see the socket in a directory listing, but connecting to it never succeeds. Some programs take advantage of this, such as by asking the client to send its own process ID, and using the process IDs to distinguish between clients. -However, we recommend you not to use this method in protocols you design, +However, we recommend you not use this method in protocols you design, as we might someday permit connections from other machines that mount the same file systems. Instead, send each new client an identifying number if you want it to have one. @@ -642,7 +641,7 @@ namespace. @xref{Socket Addresses}. This is the file name to use. @strong{Incomplete:} Why is 108 a magic number? RMS suggests making -this a zero-length array and tweaking the example following to use +this a zero-length array and tweaking the following example to use @code{alloca} to allocate an appropriate amount of storage based on the length of the filename. @end table @@ -676,15 +675,15 @@ namespace. This section describes the details of the protocols and socket naming conventions used in the Internet namespace. -Originaly the Internet namespace used only IP version 4 (IPv4). With +Originally the Internet namespace used only IP version 4 (IPv4). With the growing number of hosts on the Internet, a new protocol with a -larger address space was neccessary: IP version 6 (IPv6). IPv6 -introduces besides 128bit addresses (IPv4 has 32bit addresses) also -other features and will eventually replace IPv4. +larger address space was necessary: IP version 6 (IPv6). IPv6 +introduces 128-bit addresses (IPv4 has 32-bit addresses) and other +features, and will eventually replace IPv4. To create a socket in the IPv4 Internet namespace, use the symbolic name @code{PF_INET} of this namespace as the @var{namespace} argument to -@code{socket} or @code{socketpair}. For IPv6 addresses, you need the +@code{socket} or @code{socketpair}. For IPv6 addresses you need the macro @code{PF_INET6}. These macros are defined in @file{sys/socket.h}. @pindex sys/socket.h @@ -695,7 +694,9 @@ This designates the IPv4 Internet namespace and associated family of protocols. @end deftypevr -@deftypevr Macro int AF_INET6 +@comment sys/socket.h +@comment X/Open +@deftypevr Macro int PF_INET6 This designates the IPv6 Internet namespace and associated family of protocols. @end deftypevr @@ -706,7 +707,7 @@ A socket address for the Internet namespace includes the following components: @item The address of the machine you want to connect to. Internet addresses can be specified in several ways; these are discussed in @ref{Internet -Address Formats}, @ref{Host Addresses}, and @ref{Host Names}. +Address Formats}, @ref{Host Addresses} and @ref{Host Names}. @item A port number for that machine. @xref{Ports}. @@ -719,7 +720,7 @@ for information about this. @menu * Internet Address Formats:: How socket addresses are specified in the Internet namespace. -* Host Addresses:: All about host addresses of internet host. +* Host Addresses:: All about host addresses of Internet host. * Protocols Database:: Referring to protocols by name. * Ports:: Internet port numbers. * Services Database:: Ports may have symbolic names. @@ -751,7 +752,7 @@ Internet namespace. It has the following members: @table @code @item sa_family_t sin_family This identifies the address family or format of the socket address. -You should store the value of @code{AF_INET} in this member. +You should store the value @code{AF_INET} in this member. @xref{Socket Addresses}. @item struct in_addr sin_addr @@ -806,9 +807,9 @@ Each computer also has one or more @dfn{host names}, which are strings of words separated by periods, as in @samp{mescaline.gnu.org}. Programs that let the user specify a host typically accept both numeric -addresses and host names. But the program needs a numeric address to -open a connection; to use a host name, you must convert it to the -numeric address it stands for. +addresses and host names. To open a connection a program needs a +numeric address, and so must convert a host name to the numeric address +it stands for. @menu * Abstract Host Addresses:: What a host number consists of. @@ -832,17 +833,17 @@ numbers which identify that computer among all those on the Internet. An IPv4 Internet host address is a number containing four bytes of data. Historically these are divided into two parts, a @dfn{network number} and a @dfn{local network address number} within that network. In the -mid-1990s classless address were introduced which changed the +mid-1990s classless addresses were introduced which changed this behaviour. Since some functions implicitly expect the old definitions, -we first describe the class based network and will then describe -classless addresses. IPv6 uses only classless adresses and therefore +we first describe the class-based network and will then describe +classless addresses. IPv6 uses only classless addresses and therefore the following paragraphs don't apply. -The class based IPv4 network number consists of the first one, two or +The class-based IPv4 network number consists of the first one, two or three bytes; the rest of the bytes are the local address. IPv4 network numbers are registered with the Network Information Center -(NIC), and are divided into three classes---A, B, and C. The local +(NIC), and are divided into three classes---A, B and C. The local network address numbers of individual machines are registered with the administrator of the particular network. @@ -852,12 +853,12 @@ very large number of hosts. Medium-sized Class B networks have two-byte network numbers, with the first byte in the range 128 to 191. Class C networks are the smallest; they have three-byte network numbers, with the first byte in the range 192-255. Thus, the first 1, 2, or 3 bytes -of an Internet address specifies a network. The remaining bytes of the +of an Internet address specify a network. The remaining bytes of the Internet address specify the address within that network. The Class A network 0 is reserved for broadcast to all networks. In addition, the host number 0 within each network is reserved for broadcast -to all hosts in that network. These uses are obsolete now but out of +to all hosts in that network. These uses are obsolete now but for compatibility reasons you shouldn't use network 0 and host number 0. The Class A network 127 is reserved for loopback; you can always use @@ -902,15 +903,15 @@ radix is assumed. @subsubheading Classless Addresses -IPv4 addresses (and IPv6 addresses also) are now considered as -classless. The distinction between classes A, B, and C can be ignored. -Instead a IPv4 host adddress consists of a 32-bit address and a 32-bit -mask. The mask contains bits of 1 for the network part and bits of 0 -for the host part. The 1-bits are contigous from the leftmost bit, the -0-bits are contigous from the rightmost bit so that the netmask can also -be written as a prefix length of bits of 1. Classes A, B and C are just -special cases of this general rule. For example, class A addresses have -a netmask of @samp{255.0.0.0} or a prefix length of 8. +IPv4 addresses (and IPv6 addresses also) are now considered classless; +the distinction between classes A, B and C can be ignored. Instead an +IPv4 host address consists of a 32-bit address and a 32-bit mask. The +mask contains set bits for the network part and cleared bits for the +host part. The network part is contiguous from the left, with the +remaining bits representing the host. As a consequence, the netmask can +simply be specified as the number of set bits. Classes A, B and C are +just special cases of this general rule. For example, class A addresses +have a netmask of @samp{255.0.0.0} or a prefix length of 8. Classless IPv4 network addresses are written in numbers-and-dots notation with the prefix length appended and a slash as separator. For @@ -921,8 +922,8 @@ example the class A network 10 is written as @samp{10.0.0.0/8}. IPv6 addresses contain 128 bits (IPv4 has 32 bits) of data. A host address is usually written as eight 16-bit hexadecimal numbers that are separated by colons. Two colons are used to abbreviate strings of -consecutive zeros. For example the IPv6 loopback address which is -@samp{0:0:0:0:0:0:0:1} can be just written as @samp{::1}. +consecutive zeros. For example, the IPv6 loopback address +@samp{0:0:0:0:0:0:0:1} can just be written as @samp{::1}. @node Host Address Data Type @subsubsection Host Address Data Type @@ -935,8 +936,8 @@ the integer from the structure or put the integer into a structure. You will find older code that uses @code{unsigned long int} for IPv4 Internet host addresses instead of @code{uint32_t} or @code{struct -in_addr}. Historically @code{unsigned long int} was a 32 bit number but -with 64 bit machines this has changed. Using @code{unsigned long int} +in_addr}. Historically @code{unsigned long int} was a 32-bit number but +with 64-bit machines this has changed. Using @code{unsigned long int} might break the code if it is used on machines where this type doesn't have 32 bits. @code{uint32_t} is specified by Unix98 and guaranteed to have 32 bits. @@ -971,7 +972,7 @@ talking to itself. @comment netinet/in.h @comment BSD @deftypevr Macro {uint32_t} INADDR_ANY -You can use this constant to stand for ``any incoming address,'' when +You can use this constant to stand for ``any incoming address'' when binding to an address. @xref{Setting Address}. This is the usual address to give in the @code{sin_addr} member of @w{@code{struct sockaddr_in}} when you want to accept Internet connections. @@ -1002,7 +1003,7 @@ data, which can be accessed (via a union) in a variety of ways. @deftypevr Constant {struct in6_addr} in6addr_loopback This constant is the IPv6 address @samp{::1}, the loopback address. See above for a description of what this means. The macro -@code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialise your +@code{IN6ADDR_LOOPBACK_INIT} is provided to allow you to initialize your own variables to this value. @end deftypevr @@ -1011,7 +1012,7 @@ own variables to this value. @deftypevr Constant {struct in6_addr} in6addr_any This constant is the IPv6 address @samp{::}, the unspecified address. See above for a description of what this means. The macro -@code{IN6ADDR_ANY_INIT} is provided to allow you to initialise your +@code{IN6ADDR_ANY_INIT} is provided to allow you to initialize your own variables to this value. @end deftypevr @@ -1022,7 +1023,7 @@ own variables to this value. @noindent These additional functions for manipulating Internet addresses are declared in the header file @file{arpa/inet.h}. They represent Internet -addresses in network byte order; they represent network numbers and +addresses in network byte order, and network numbers and local-address-within-network numbers in host byte order. @xref{Byte Order}, for an explanation of network and host byte order. @@ -1041,7 +1042,7 @@ it in the @code{struct in_addr} that @var{addr} points to. This function converts the IPv4 Internet host address @var{name} from the standard numbers-and-dots notation into binary data. If the input is not valid, @code{inet_addr} returns @code{INADDR_NONE}. This is an -obsolete interface to @code{inet_aton}, described immediately above; it +obsolete interface to @code{inet_aton}, described immediately above. It is obsolete because @code{INADDR_NONE} is a valid address (255.255.255.255), and @code{inet_aton} provides a cleaner way to indicate error return. @@ -1170,7 +1171,7 @@ vector of strings. This is the host address type; in practice, its value is always either @code{AF_INET} or @code{AF_INET6}, with the latter being used for IPv6 hosts. In principle other kinds of addresses could be represented in -the data base as well as Internet addresses; if this were done, you +the database as well as Internet addresses; if this were done, you might find a value in this field other than @code{AF_INET} or @code{AF_INET6}. @xref{Socket Addresses}. @@ -1214,7 +1215,7 @@ named @var{name}. If the lookup fails, it returns a null pointer. @deftypefun {struct hostent *} gethostbyname2 (const char *@var{name}, int @var{af}) The @code{gethostbyname2} function is like @code{gethostbyname}, but allows the caller to specify the desired address family (e.g.@: -@code{AF_INET} or @code{AF_INET6}) for the result. +@code{AF_INET} or @code{AF_INET6}) of the result. @end deftypefun @comment netdb.h @@ -1245,7 +1246,7 @@ Here are the error codes that you may find in @code{h_errno}: @comment BSD @item HOST_NOT_FOUND @vindex HOST_NOT_FOUND -No such host is known in the data base. +No such host is known in the database. @comment netdb.h @comment BSD @@ -1349,8 +1350,8 @@ too small. @end deftypefun You can also scan the entire hosts database one entry at a time using -@code{sethostent}, @code{gethostent}, and @code{endhostent}. Be careful -in using these functions, because they are not reentrant. +@code{sethostent}, @code{gethostent} and @code{endhostent}. Be careful +when using these functions because they are not reentrant. @comment netdb.h @comment BSD @@ -1494,8 +1495,8 @@ find such a service, it returns a null pointer. @noindent You can also scan the services database using @code{setservent}, -@code{getservent}, and @code{endservent}. Be careful in using these -functions, because they are not reentrant. +@code{getservent} and @code{endservent}. Be careful when using these +functions because they are not reentrant. @comment netdb.h @comment BSD @@ -1538,11 +1539,11 @@ order), and others put it last (``little-endian'' order). So that machines with different byte order conventions can communicate, the Internet protocols specify a canonical byte order convention for data transmitted over the network. This is known -as the @dfn{network byte order}. +as @dfn{network byte order}. When establishing an Internet socket connection, you must make sure that the data in the @code{sin_port} and @code{sin_addr} members of the -@code{sockaddr_in} structure are represented in the network byte order. +@code{sockaddr_in} structure are represented in network byte order. If you are encoding integer data in the messages sent through the socket, you should convert this to network byte order too. If you don't do this, your program may fail when running on or talking to other kinds @@ -1550,7 +1551,7 @@ of machines. If you use @code{getservbyname} and @code{gethostbyname} or @code{inet_addr} to get the port number and host address, the values are -already in the network byte order, and you can copy them directly into +already in network byte order, and you can copy them directly into the @code{sockaddr_in} structure. Otherwise, you have to convert the values explicitly. Use @code{htons} @@ -1581,7 +1582,7 @@ network byte order to host byte order. This function converts the @code{uint32_t} integer @var{hostlong} from host byte order to network byte order. -This is used for IPv4 internet addresses. +This is used for IPv4 Internet addresses. @end deftypefun @comment netinet/in.h @@ -1590,7 +1591,7 @@ This is used for IPv4 internet addresses. This function converts the @code{uint32_t} integer @var{netlong} from network byte order to host byte order. -This is used for IPv4 internet addresses. +This is used for IPv4 Internet addresses. @end deftypefun @node Protocols Database @@ -1598,7 +1599,7 @@ This is used for IPv4 internet addresses. @cindex protocols database The communications protocol used with a socket controls low-level -details of how data is exchanged. For example, the protocol implements +details of how data are exchanged. For example, the protocol implements things like checksums to detect errors in transmissions, and routing instructions for messages. Normal user programs have little reason to mess with these details directly. @@ -1665,8 +1666,8 @@ protocol, it returns a null pointer. @end deftypefun You can also scan the whole protocols database one protocol at a time by -using @code{setprotoent}, @code{getprotoent}, and @code{endprotoent}. -Be careful in using these functions, because they are not reentrant. +using @code{setprotoent}, @code{getprotoent} and @code{endprotoent}. +Be careful when using these functions because they are not reentrant. @comment netdb.h @comment BSD @@ -1729,7 +1730,7 @@ CCITT. @file{socket.h} defines these symbols and others naming protocols not actually implemented. @code{PF_IMPLINK} is used for communicating between hosts and Internet -Message Processors. For information on this, and on @code{PF_ROUTE}, an +Message Processors. For information on this and @code{PF_ROUTE}, an occasionally-used local area routing protocol, see the GNU Hurd Manual (to appear in the future). @@ -1783,7 +1784,7 @@ The process already has too many file descriptors open. The system already has too many file descriptors open. @item EACCESS -The process does not have privilege to create a socket of the specified +The process does not have the privilege to create a socket of the specified @var{style} or @var{protocol}. @item ENOBUFS @@ -1791,7 +1792,7 @@ The system ran out of internal buffer space. @end table The file descriptor returned by the @code{socket} function supports both -read and write operations. But, like pipes, sockets do not support file +read and write operations. However, like pipes, sockets do not support file positioning operations. @end deftypefun @@ -1806,7 +1807,7 @@ see @ref{Local Socket Example}, or @ref{Inet Example}. @cindex shutting down a socket @cindex socket shutdown -When you are finished using a socket, you can simply close its +When you have finished using a socket, you can simply close its file descriptor with @code{close}; see @ref{Opening and Closing Files}. If there is still data waiting to be transmitted over the connection, normally @code{close} tries to complete this transmission. You @@ -1814,7 +1815,7 @@ can control this behavior using the @code{SO_LINGER} socket option to specify a timeout period; see @ref{Socket Options}. @pindex sys/socket.h -You can also shut down only reception or only transmission on a +You can also shut down only reception or transmission on a connection by calling @code{shutdown}, which is declared in @file{sys/socket.h}. @@ -1877,7 +1878,7 @@ This function creates a socket pair, returning the file descriptors in is a full-duplex communications channel, so that both reading and writing may be performed at either end. -The @var{namespace}, @var{style}, and @var{protocol} arguments are +The @var{namespace}, @var{style} and @var{protocol} arguments are interpreted as for the @code{socket} function. @var{style} should be one of the communication styles listed in @ref{Communication Styles}. The @var{namespace} argument specifies the namespace, which must be @@ -1927,12 +1928,12 @@ over and over. Making a connection is asymmetric; one side (the initiate a connection with a server. @item -@ref{Listening}, and @ref{Accepting Connections}, describe what the +@ref{Listening} and @ref{Accepting Connections} describe what the server program must do to wait for and act upon connection requests from clients. @item -@ref{Transferring Data}, describes how data is transferred through the +@ref{Transferring Data}, describes how data are transferred through the connected socket. @end itemize @end iftex @@ -1959,7 +1960,7 @@ connected socket. In making a connection, the client makes a connection while the server waits for and accepts the connection. Here we discuss what the client -program must do, using the @code{connect} function, which is declared in +program must do with the @code{connect} function, which is declared in @file{sys/socket.h}. @comment sys/socket.h @@ -2024,10 +2025,10 @@ The socket @var{socket} is non-blocking and already has a pending connection in progress (see @code{EINPROGRESS} above). @end table -This function is defined as a cancelation point in multi-threaded -programs. So one has to be prepared for this and make sure that -possibly allocated resources (like memory, files descriptors, -semaphores or whatever) are freed even if the thread is canceled. +This function is defined as a cancellation point in multi-threaded +programs, so one has to be prepared for this and make sure that +allocated resources (like memory, files descriptors, semaphores or +whatever) are freed even if the thread is canceled. @c @xref{pthread_cleanup_push}, for a method how to do this. @end deftypefun @@ -2052,7 +2053,7 @@ You can write a network server that does not even start running until a connection to it is requested. @xref{Inetd Servers}. In the Internet namespace, there are no special protection mechanisms -for controlling access to connect to a port; any process on any machine +for controlling access to a port; any process on any machine can make a connection to your server. If you want to restrict access to your server, make it examine the addresses associated with connection requests or implement some other handshaking or identification @@ -2099,7 +2100,7 @@ to do this. A socket that has been established as a server can accept connection requests from multiple clients. The server's original socket -@emph{does not become part} of the connection; instead, @code{accept} +@emph{does not become part of the connection}; instead, @code{accept} makes a new socket which participates in the connection. @code{accept} returns the descriptor for this socket. The server's original socket remains available for listening for further connection @@ -2108,7 +2109,7 @@ requests. The number of pending connection requests on a server socket is finite. If connection requests arrive from clients faster than the server can act upon them, the queue can fill up and additional requests are refused -with a @code{ECONNREFUSED} error. You can specify the maximum length of +with an @code{ECONNREFUSED} error. You can specify the maximum length of this queue as an argument to the @code{listen} function, although the system may also impose its own internal limit on the length of this queue. @@ -2158,10 +2159,10 @@ The descriptor @var{socket} does not support this operation. connections immediately available. @end table -This function is defined as a cancelation point in multi-threaded -programs. So one has to be prepared for this and make sure that -possibly allocated resources (like memory, files descriptors, -semaphores or whatever) are freed even if the thread is canceled. +This function is defined as a cancellation point in multi-threaded +programs, so one has to be prepared for this and make sure that +allocated resources (like memory, files descriptors, semaphores or +whatever) are freed even if the thread is canceled. @c @xref{pthread_cleanup_push}, for a method how to do this. @end deftypefun @@ -2217,7 +2218,7 @@ In order to specify these modes, you must use the @code{recv} and @code{send} functions instead of the more generic @code{read} and @code{write} functions. The @code{recv} and @code{send} functions take an additional argument which you can use to specify various flags to -control the special I/O modes. For example, you can specify the +control special I/O modes. For example, you can specify the @code{MSG_OOB} flag to read or write out-of-band data, the @code{MSG_PEEK} flag to peek at input, or the @code{MSG_DONTROUTE} flag to control inclusion of routing information on output. @@ -2290,10 +2291,10 @@ signal is ignored or blocked, or if its handler returns, then @code{send} fails with @code{EPIPE}. @end table -This function is defined as a cancelation point in multi-threaded -programs. So one has to be prepared for this and make sure that -possibly allocated resources (like memory, files descriptors, -semaphores or whatever) are freed even if the thread is canceled. +This function is defined as a cancellation point in multi-threaded +programs, so one has to be prepared for this and make sure that +allocated resources (like memory, files descriptors, semaphores or +whatever) are freed even if the thread is canceled. @c @xref{pthread_cleanup_push}, for a method how to do this. @end deftypefun @@ -2313,7 +2314,7 @@ The @code{recv} function is like @code{read}, but with the additional flags @var{flags}. The possible values of @var{flags} are described in @ref{Socket Data Options}. -If nonblocking mode is set for @var{socket}, and no data is available to +If nonblocking mode is set for @var{socket}, and no data are available to be read, @code{recv} fails immediately rather than waiting. @xref{File Status Flags}, for information about nonblocking mode. @@ -2340,10 +2341,10 @@ The operation was interrupted by a signal before any data was read. You never connected this socket. @end table -This function is defined as a cancelation point in multi-threaded -programs. So one has to be prepared for this and make sure that -possibly allocated resources (like memory, files descriptors, -semaphores or whatever) are freed even if the thread is canceled. +This function is defined as a cancellation point in multi-threaded +programs, so one has to be prepared for this and make sure that +allocated resources (like memory, files descriptors, semaphores or +whatever) are freed even if the thread is canceled. @c @xref{pthread_cleanup_push}, for a method how to do this. @end deftypefun @@ -2424,18 +2425,18 @@ This program uses @code{make_socket} to set up the socket address; see Streams with connections permit @dfn{out-of-band} data that is delivered with higher priority than ordinary data. Typically the reason for sending out-of-band data is to send notice of an -exceptional condition. The way to send out-of-band data is using +exceptional condition. To send out-of-band data use @code{send}, specifying the flag @code{MSG_OOB} (@pxref{Sending Data}). -Out-of-band data is received with higher priority because the +Out-of-band data are received with higher priority because the receiving process need not read it in sequence; to read the next available out-of-band data, use @code{recv} with the @code{MSG_OOB} flag (@pxref{Receiving Data}). Ordinary read operations do not read -out-of-band data; they read only the ordinary data. +out-of-band data; they read only ordinary data. @cindex urgent socket condition -When a socket finds that out-of-band data is on its way, it sends a +When a socket finds that out-of-band data are on their way, it sends a @code{SIGURG} signal to the owner process or process group of the socket. You can specify the owner using the @code{F_SETOWN} command to the @code{fcntl} function; see @ref{Interrupt Input}. You must @@ -2449,7 +2450,7 @@ can wait for an exceptional condition on the socket. @xref{Waiting for I/O}, for more information about @code{select}. Notification of out-of-band data (whether with @code{SIGURG} or with -@code{select}) indicates that out-of-band data is on the way; the data +@code{select}) indicates that out-of-band data are on the way; the data may not actually arrive until later. If you try to read the out-of-band data before it arrives, @code{recv} fails with an @code{EWOULDBLOCK} error. @@ -2522,7 +2523,7 @@ struct buffer @r{It may be necessary to read some ordinary data} @r{in order to make room for the out-of-band data.} - @r{If so, the ordinary data is saved as a chain of buffers} + @r{If so, the ordinary data are saved as a chain of buffers} @r{found in the `next' field of the value.} */ struct buffer * @@ -2599,7 +2600,7 @@ these styles, you group data into packets and each packet is an independent communication. You specify the destination for each packet individually. -Datagram packets are like letters: you send each one independently, +Datagram packets are like letters: you send each one independently with its own destination address, and they may arrive in the wrong order or not at all. @@ -2626,7 +2627,7 @@ The normal way of sending data on a datagram socket is by using the You can call @code{connect} on a datagram socket, but this only specifies a default destination for further data transmission on the -socket. When a socket has a default destination, then you can use +socket. When a socket has a default destination you can use @code{send} (@pxref{Sending Data}) or even @code{write} (@pxref{I/O Primitives}) to send a packet there. You can cancel the default destination by calling @code{connect} using an address format of @@ -2647,16 +2648,16 @@ The @var{flags} are interpreted the same way as for @code{send}; see The return value and error conditions are also the same as for @code{send}, but you cannot rely on the system to detect errors and report them; the most common error is that the packet is lost or there -is no one at the specified address to receive it, and the operating +is no-one at the specified address to receive it, and the operating system on your machine usually does not know this. It is also possible for one call to @code{sendto} to report an error -due to a problem related to a previous call. +owing to a problem related to a previous call. -This function is defined as a cancelation point in multi-threaded -programs. So one has to be prepared for this and make sure that -possibly allocated resources (like memory, files descriptors, -semaphores or whatever) are freed even if the thread is canceled. +This function is defined as a cancellation point in multi-threaded +programs, so one has to be prepared for this and make sure that +allocated resources (like memory, files descriptors, semaphores or +whatever) are freed even if the thread is canceled. @c @xref{pthread_cleanup_push}, for a method how to do this. @end deftypefun @@ -2676,13 +2677,13 @@ The @code{recvfrom} function reads one packet from the socket specifies the maximum number of bytes to be read. If the packet is longer than @var{size} bytes, then you get the first -@var{size} bytes of the packet, and the rest of the packet is lost. +@var{size} bytes of the packet and the rest of the packet is lost. There's no way to read the rest of the packet. Thus, when you use a packet protocol, you must always know how long a packet to expect. The @var{addr} and @var{length-ptr} arguments are used to return the address where the packet came from. @xref{Socket Addresses}. For a -socket in the local domain, the address information won't be meaningful, +socket in the local domain the address information won't be meaningful, since you can't read the address of such a socket (@pxref{Local Namespace}). You can specify a null pointer as the @var{addr} argument if you are not interested in this information. @@ -2691,15 +2692,15 @@ The @var{flags} are interpreted the same way as for @code{recv} (@pxref{Socket Data Options}). The return value and error conditions are also the same as for @code{recv}. -This function is defined as a cancelation point in multi-threaded -programs. So one has to be prepared for this and make sure that -possibly allocated resources (like memory, files descriptors, -semaphores or whatever) are freed even if the thread is canceled. +This function is defined as a cancellation point in multi-threaded +programs, so one has to be prepared for this and make sure that +allocated resources (like memory, files descriptors, semaphores or +whatever) are freed even if the thread is canceled. @c @xref{pthread_cleanup_push}, for a method how to do this. @end deftypefun You can use plain @code{recv} (@pxref{Receiving Data}) instead of -@code{recvfrom} if you know don't need to find out who sent the packet +@code{recvfrom} if you don't need to find out who sent the packet (either because you know where it should come from or because you treat all possible senders alike). Even @code{read} can be used if you don't want to specify @var{flags} (@pxref{I/O Primitives}). @@ -2719,10 +2720,10 @@ you don't want to specify @var{flags} (@pxref{I/O Primitives}). @comment BSD @deftypefun int sendmsg (int @var{socket}, const struct msghdr *@var{message}, int @var{flags}) -This function is defined as a cancelation point in multi-threaded -programs. So one has to be prepared for this and make sure that -possibly allocated resources (like memory, files descriptors, -semaphores or whatever) are freed even if the thread is cancel. +This function is defined as a cancellation point in multi-threaded +programs, so one has to be prepared for this and make sure that +allocated resources (like memory, files descriptors, semaphores or +whatever) are freed even if the thread is cancel. @c @xref{pthread_cleanup_push}, for a method how to do this. @end deftypefun @@ -2730,10 +2731,10 @@ semaphores or whatever) are freed even if the thread is cancel. @comment BSD @deftypefun int recvmsg (int @var{socket}, struct msghdr *@var{message}, int @var{flags}) -This function is defined as a cancelation point in multi-threaded -programs. So one has to be prepared for this and make sure that -possibly allocated resources (like memory, files descriptors, -semaphores or whatever) are freed even if the thread is canceled. +This function is defined as a cancellation point in multi-threaded +programs, so one has to be prepared for this and make sure that +allocated resources (like memory, files descriptors, semaphores or +whatever) are freed even if the thread is canceled. @c @xref{pthread_cleanup_push}, for a method how to do this. @end deftypefun @end ignore @@ -2748,7 +2749,7 @@ Socket Example}, to create and name their sockets. First, here is the server program. It sits in a loop waiting for messages to arrive, bouncing each message back to the sender. -Obviously, this isn't a particularly useful program, but it does show +Obviously this isn't a particularly useful program, but it does show the general ideas involved. @smallexample @@ -2774,10 +2775,10 @@ referencing the name of the client. Keep in mind that datagram socket communications are unreliable. In this example, the client program waits indefinitely if the message never reaches the server or if the server's response never comes -back. It's up to the user running the program to kill it and restart -it, if desired. A more automatic solution could be to use +back. It's up to the user running the program to kill and restart +it if desired. A more automatic solution could be to use @code{select} (@pxref{Waiting for I/O}) to establish a timeout period -for the reply, and in case of timeout either resend the message or +for the reply, and in case of timeout either re-send the message or shut down the socket and exit. @node Inetd @@ -2787,7 +2788,7 @@ We've explained above how to write a server program that does its own listening. Such a server must already be running in order for anyone to connect to it. -Another way to provide service for an Internet port is to let the daemon +Another way to provide a service on an Internet port is to let the daemon program @code{inetd} do the listening. @code{inetd} is a program that runs all the time and waits (using @code{select}) for messages on a specified set of ports. When it receives a message, it accepts the @@ -2808,19 +2809,19 @@ someone requests a connection to the appropriate port, a new server process starts. The connection already exists at this time; the socket is available as the standard input descriptor and as the standard output descriptor (descriptors 0 and 1) in the server -process. So the server program can begin reading and writing data +process. Thus the server program can begin reading and writing data right away. Often the program needs only the ordinary I/O facilities; in fact, a general-purpose filter program that knows nothing about sockets can work as a byte stream server run by @code{inetd}. You can also use @code{inetd} for servers that use connectionless communication styles. For these servers, @code{inetd} does not try to accept -a connection, since no connection is possible. It just starts the +a connection since no connection is possible. It just starts the server program, which can read the incoming datagram packet from descriptor 0. The server program can handle one request and then exit, or you can choose to write it to keep reading more requests until no more arrive, and then exit. You must specify which of these -two techniques the server uses, when you configure @code{inetd}. +two techniques the server uses when you configure @code{inetd}. @node Configuring Inetd @subsection Configuring @code{inetd} @@ -2859,7 +2860,7 @@ byte stream connections and @samp{udp} for unreliable datagrams. The @var{wait} field should be either @samp{wait} or @samp{nowait}. Use @samp{wait} if @var{style} is a connectionless style and the -server, once started, handles multiple requests, as many as come in. +server, once started, handles multiple requests as they come in. Use @samp{nowait} if @code{inetd} should start a new process for each message or request that comes in. If @var{style} uses connections, then @var{wait} @strong{must} be @samp{nowait}. @@ -2882,7 +2883,7 @@ program name itself (sans directories). If you edit @file{/etc/inetd.conf}, you can tell @code{inetd} to reread the file and obey its new contents by sending the @code{inetd} process the @code{SIGHUP} signal. You'll have to use @code{ps} to determine the -process ID of the @code{inetd} process, as it is not fixed. +process ID of the @code{inetd} process as it is not fixed. @c !!! could document /etc/inetd.sec @@ -2948,7 +2949,7 @@ The @var{optname} doesn't make sense for the given @var{level}. @deftypefun int setsockopt (int @var{socket}, int @var{level}, int @var{optname}, void *@var{optval}, socklen_t @var{optlen}) This function is used to set the socket option @var{optname} at level @var{level} for socket @var{socket}. The value of the option is passed -in the buffer @var{optval}, which has size @var{optlen}. +in the buffer @var{optval} of size @var{optlen}. @c Argh. -zw @iftex @@ -2989,7 +2990,7 @@ This option toggles recording of debugging information in the underlying protocol modules. The value has type @code{int}; a nonzero value means ``yes''. @c !!! should say how this is used -@c Ok, anyone who knows, please explain. +@c OK, anyone who knows, please explain. @comment sys/socket.h @comment BSD @@ -3037,7 +3038,7 @@ This structure type has the following members: @table @code @item int l_onoff This field is interpreted as a boolean. If nonzero, @code{close} -blocks until the data is transmitted or the timeout period has expired. +blocks until the data are transmitted or the timeout period has expired. @item int l_linger This specifies the timeout period, in seconds. @@ -3107,7 +3108,7 @@ to the system developer. This is usually kept either in the file @file{/etc/networks} or in an equivalent from a name server. This data base is useful for routing programs such as @code{route}, but it is not useful for programs that simply communicate over the network. We -provide functions to access this data base, which are declared in +provide functions to access this database, which are declared in @file{netdb.h}. @comment netdb.h @@ -3159,8 +3160,8 @@ network. @end deftypefun You can also scan the networks database using @code{setnetent}, -@code{getnetent}, and @code{endnetent}. Be careful in using these -functions, because they are not reentrant. +@code{getnetent} and @code{endnetent}. Be careful when using these +functions because they are not reentrant. @comment netdb.h @comment BSD diff --git a/manual/stdio.texi b/manual/stdio.texi index 0f82864..ddae15f 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -1847,14 +1847,14 @@ The information is stored in the array @var{argtypes}; each element of this array describes one argument. This information is encoded using the various @samp{PA_} macros, listed below. -The @var{n} argument specifies the number of elements in the array -@var{argtypes}. This is the most elements that +The argument @var{n} specifies the number of elements in the array +@var{argtypes}. This is the maximum number of elements that @code{parse_printf_format} will try to write. @code{parse_printf_format} returns the total number of arguments required by @var{template}. If this number is greater than @var{n}, then the information returned describes only the first @var{n} arguments. If you -want information about more than that many arguments, allocate a bigger +want information about additional arguments, allocate a bigger array and call @code{parse_printf_format} again. @end deftypefun @@ -2107,9 +2107,9 @@ about this. @c but if you are never going to call @code{parse_printf_format}, you do @c not need to define an arginfo function. -@strong{Attention:} In the GNU C library version before 2.0 the +@strong{Attention:} In the GNU C library versions before 2.0 the @var{arginfo-function} function did not need to be installed unless -the user uses the @code{parse_printf_format} function. This changed. +the user used the @code{parse_printf_format} function. This has changed. Now a call to any of the @code{printf} functions will call this function when this format specifier appears in the format string. @@ -2220,7 +2220,7 @@ width. The value is @code{'0'} if the @samp{0} flag was specified, and Now let's look at how to define the handler and arginfo functions which are passed as arguments to @code{register_printf_function}. -@strong{Compatibility Note:} The interface changed in the GNU libc +@strong{Compatibility Note:} The interface changed in GNU libc version 2.0. Previously the third argument was of type @code{va_list *}. @@ -2254,7 +2254,7 @@ a description of this data structure. @c arguments that your handler processes. @xref{Variadic Functions}.) The @var{args} is a vector of pointers to the arguments data. -The number of arguments were determined by calling the argument +The number of arguments was determined by calling the argument information function provided by the user. Your handler function should return a value just like @code{printf} @@ -2328,7 +2328,7 @@ which implement a special way to print floating-point numbers. Print a given floating point number as for the format @code{%f} except that there is a postfix character indicating the divisor for the number to make this less than 1000. There are two possible divisors: -powers of 1024 or powers to 1000. Which one is used depends on the +powers of 1024 or powers of 1000. Which one is used depends on the format character specified while registered this handler. If the character is of lower case, 1024 is used. For upper case characters, 1000 is used. @@ -2378,7 +2378,7 @@ format character as if it were @code{%.3fk} and will yield @code{1.000k}. @end deftypefun Due to the requirements of @code{register_printf_function} we must also -provide the function which return information about the arguments. +provide the function which returns information about the arguments. @comment printf.h @comment GNU @@ -2403,14 +2403,14 @@ register_printf_function ('b', printf_size, printf_size_info); @end smallexample @noindent -we could also print using power of 1024. Please note that all what is -different in these both lines in the format specifier. The -@code{printf_size} function knows about the difference of low and upper +we could also print using a power of 1024. Please note that all that is +different in these two lines is the format specifier. The +@code{printf_size} function knows about the difference between lower and upper case format specifiers. The use of @code{'B'} and @code{'b'} is no coincidence. Rather it is the preferred way to use this functionality since it is available on -some other systems also available using the format specifiers. +some other systems which also use format specifiers. @node Formatted Input @section Formatted Input @@ -2784,7 +2784,7 @@ in. @xref{Dynamic String Input}. @end itemize The @samp{%c} conversion is the simplest: it matches a fixed number of -characters, always. The maximum field with says how many characters to +characters, always. The maximum field width says how many characters to read; if you don't specify the maximum, the default is 1. This conversion doesn't append a null character to the end of the text it reads. It also does not skip over initial whitespace characters. It @@ -2903,7 +2903,7 @@ conversion specification to read a ``variable assignment'' of the form This section describes the miscellaneous input conversions. The @samp{%p} conversion is used to read a pointer value. It recognizes -the same syntax as is used by the @samp{%p} output conversion for +the same syntax used by the @samp{%p} output conversion for @code{printf} (@pxref{Other Output Conversions}); that is, a hexadecimal number just as the @samp{%x} conversion accepts. The corresponding argument should be of type @code{void **}; that is, the address of a @@ -2946,9 +2946,9 @@ The optional arguments are pointers to the places which receive the resulting values. The return value is normally the number of successful assignments. If -an end-of-file condition is detected before any matches are performed -(including matches against whitespace and literal characters in the -template), then @code{EOF} is returned. +an end-of-file condition is detected before any matches are performed, +including matches against whitespace and literal characters in the +template, then @code{EOF} is returned. @end deftypefun @comment stdio.h @@ -2987,7 +2987,7 @@ extensions. @comment stdio.h @comment GNU @deftypefun int vscanf (const char *@var{template}, va_list @var{ap}) -This function is similar to @code{scanf} except that, instead of taking +This function is similar to @code{scanf}, but instead of taking a variable number of arguments directly, it takes an argument list pointer @var{ap} of type @code{va_list} (@pxref{Variadic Functions}). @end deftypefun @@ -3010,8 +3010,8 @@ In GNU C, there is a special construct you can use to let the compiler know that a function uses a @code{scanf}-style format string. Then it can check the number and types of arguments in each call to the function, and warn you when they do not match the format string. -@xref{Function Attributes, , Declaring Attributes of Functions, -gcc.info, Using GNU CC}, for details. +For details, @xref{Function Attributes, , Declaring Attributes of Functions, +gcc.info, Using GNU CC}. @node EOF and Errors @section End-Of-File and Errors @@ -3169,18 +3169,15 @@ possibly for other reasons as well. If a failure occurs, a value of @comment stdio.h @comment Unix98 @deftypefun off_t ftello (FILE *@var{stream}) -The @code{ftello} function is similar to @code{ftell} only it corrects a -problem which the POSIX type system. In this type system all file -positions are described using values of type @code{off_t} which is not -necessarily of the same size as @code{long int}. Therefore using -@code{ftell} can lead to problems if the implementation is written on -top of a POSIX compliant lowlevel I/O implementation. - -Therefore it is a good idea to prefer @code{ftello} whenever it is -available since its functionality is (if different at all) closer the -underlying definition. - -If this function fails it return @code{(off_t) -1}. This can happen due +The @code{ftello} function is similar to @code{ftell}, except that it +returns a value of type @code{off_t}. Systems which support this type +use it to describe all file positions, unlike the POSIX specification +which uses a long int. The two are not necessarily the same size. +Therefore, using ftell can lead to problems if the implementation is +written on top of a POSIX compliant low-level I/O implementation, and using +@code{ftello} is preferable whenever it is available. + +If this function fails it returns @code{(off_t) -1}. This can happen due to missing support for file positioning or internal errors. Otherwise the return value is the current file position. @@ -3360,9 +3357,9 @@ the same file position. @item In a call to @code{fseek} or @code{fseeko} on a text stream, either the -@var{offset} must either be zero; or @var{whence} must be -@code{SEEK_SET} and the @var{offset} must be the result of an earlier -call to @code{ftell} on the same stream. +@var{offset} must be zero, or @var{whence} must be @code{SEEK_SET} and +and the @var{offset} must be the result of an earlier call to @code{ftell} +on the same stream. @item The value of the file position indicator of a text stream is undefined @@ -3484,7 +3481,7 @@ If you are writing programs that do interactive input and output using streams, you need to understand how buffering works when you design the user interface to your program. Otherwise, you might find that output (such as progress or prompt messages) doesn't appear when you intended -it to, or other unexpected behavior. +it to, or displays some other unexpected behavior. This section deals only with controlling when characters are transmitted between the stream and the file or device, and @emph{not} with how @@ -3756,8 +3753,8 @@ This function opens a stream that allows the access specified by the by the argument @var{buf}. This array must be at least @var{size} bytes long. If you specify a null pointer as the @var{buf} argument, @code{fmemopen} -dynamically allocates (as with @code{malloc}; @pxref{Unconstrained -Allocation}) an array @var{size} bytes long. This is really only useful +dynamically allocates an array @var{size} bytes long (as with @code{malloc}; +@pxref{Unconstrained Allocation}). This is really only useful if you are going to write things to the buffer and then read them back in again, because you have no way of actually getting a pointer to the buffer (for this, try @code{open_memstream}, below). The buffer is @@ -4162,7 +4159,7 @@ Display a message described by its parameters on the device(s) specified in the @var{classification} parameter. The @var{label} parameter identifies the source of the message. The string should consist of two colon separated parts where the first part has not more than 10 and the -second part not more the 14 characters. The @var{text} parameter +second part not more than 14 characters. The @var{text} parameter describes the condition of the error, the @var{action} parameter possible steps to recover from the error and the @var{tag} parameter is a reference to the online documentation where more information can be @@ -4228,7 +4225,7 @@ inserted if necessary, i.e., if the corresponding parameter is not ignored. This function is specified in the X/Open Portability Guide. It is also -available on all system derived from System V. +available on all systems derived from System V. The function returns the value @code{MM_OK} if no error occurred. If only the printing to standard error failed, it returns @code{MM_NOMSG}. @@ -4241,7 +4238,7 @@ is incorrect. There are two environment variables which influence the behaviour of @code{fmtmsg}. The first is @code{MSGVERB}. It is used to control the output actually happening on standard error (@emph{not} the console -output). Each of the five fields can explicitely be enabled. To do +output). Each of the five fields can explicitly be enabled. To do this the user has to put the @code{MSGVERB} variable with a format like the following in the environment before calling the @code{fmtmsg} function the first time: @@ -4291,17 +4288,17 @@ not print the numeric value but instead the string representation). @subsection Adding Severity Classes @cindex severity class -There is another possibility to introduce severity classes beside using +There is another possibility to introduce severity classes besides using the environment variable @code{SEV_LEVEL}. This simplifies the task of introducing new classes in a running program. One could use the @code{setenv} or @code{putenv} function to set the environment variable, but this is toilsome. @deftypefun int addseverity (int @var{severity}, const char *@var{string}) -This function allows to introduce new severity classes which can be +This function allows the introduction of new severity classes which can be addressed by the @var{severity} parameter of the @code{fmtmsg} function. The @var{severity} parameter of @code{addseverity} must match the value -for the parameter with the same name of @code{fmtmsg} and @var{string} +for the parameter with the same name of @code{fmtmsg}, and @var{string} is the string printed in the actual messages instead of the numeric value. @@ -4332,14 +4329,14 @@ functions described in this section. @include fmtmsgexpl.c.texi @end smallexample -The second call to @code{fmtmsg} illustrates a use of this function how -it usually happens on System V systems which heavily use this function. -It might be worth a thought to follow the scheme used in System V -systems so we give a short explanation here. The value of the +The second call to @code{fmtmsg} illustrates a use of this function as +it usually occurs on System V systems, which heavily use this function. +It seems worthwhile to give a short explanation here of how this system +works on System V. The value of the @var{label} field (@code{UX:cat}) says that the error occured in the Unix program @code{cat}. The explanation of the error follows and the value for the @var{action} parameter is @code{"refer to manual"}. One -could me more specific here, if needed. The @var{tag} field contains, +could be more specific here, if necessary. The @var{tag} field contains, as proposed above, the value of the string given for the @var{label} parameter, and additionally a unique ID (@code{001} in this case). For a GNU environment this string could contain a reference to the @@ -4362,7 +4359,7 @@ form. The string must contain two fields, separated by a colon (@pxref{Printing Formatted Messages}). The third @code{fmtmsg} call produced no output since the class with the numeric value @code{6} is not defined. Although a class with numeric value @code{5} is also not -defined by default, the call the @code{addseverity} introduces it and +defined by default, the call to @code{addseverity} introduces it and the second call to @code{fmtmsg} produces the above output. When we change the environment of the program to contain @@ -4375,11 +4372,11 @@ label:foo: NOTE: text TO FIX: action tag @end smallexample -Now the third call the @code{fmtmsg} produced some output and we see how +Now the third call to @code{fmtmsg} produced some output and we see how the string @code{NOTE} from the environment variable appears in the message. -Now we can reduce the output by specifying in which fields we are +Now we can reduce the output by specifying which fields we are interested in. If we additionally set the environment variable @code{MSGVERB} to the value @code{severity:label:action} we get the following output: @@ -4395,5 +4392,5 @@ TO FIX: action I.e., the output produced by the @var{text} and the @var{tag} parameters to @code{fmtmsg} vanished. Please also note that now there is no colon after the @code{NOTE} and @code{NOTE2} strings in the output. This is -not necessary since there is no more output on this line since the text +not necessary since there is no more output on this line because the text is missing. diff --git a/manual/sysinfo.texi b/manual/sysinfo.texi index 08283c0..5251b9a 100644 --- a/manual/sysinfo.texi +++ b/manual/sysinfo.texi @@ -82,7 +82,7 @@ This process cannot set the host name because it is not privileged. @deftypefun {long int} gethostid (void) This function returns the ``host ID'' of the machine the program is running on. By convention, this is usually the primary Internet address -of that machine, converted to a @w{@code{long int}}. However, some +of that machine, converted to a @w{@code{long int}}. However, on some systems it is a meaningless but unique number which is hard-coded for each machine. @end deftypefun @@ -95,7 +95,7 @@ to @var{id}. Only privileged processes are allowed to do this. Usually it happens just once, at system boot time. The return value is @code{0} on success and @code{-1} on failure. -The following @code{errno} error condition is defined for this function: +The following @code{errno} error conditions are defined for this function: @table @code @item EPERM @@ -186,10 +186,10 @@ possibility. @section Which filesystems are mounted and/or available? The Unix concept of @emph{Everything is a file} is based on the -possibility to @dfn{mount} filesystems or other things into the +ability to @dfn{mount} filesystems or other things into the filesystem. For some programs it is desirable and necessary to access -the information whether and, if yes, where a certain filesystem is -mounted or simply to get lists of all the available filesystems. The +information about whether a certain filesystem is mounted and, if it is, +where, or simply to get lists of all the available filesystems. The GNU libc provides some functions to retrieve this information portably. Traditionally Unix systems have a file named @file{/etc/fstab} which @@ -252,7 +252,7 @@ more than one option, separated from the others by a comma. Each option consists of a name and an optional value part, introduced by an @code{=} character. -If the value of this element must be processed it should best happen +If the value of this element must be processed it should ideally be done using the @code{getsubopt} function; see @ref{Suboptions}. @item const char *fs_type @@ -323,7 +323,7 @@ is the first call to any of the functions handling @file{fstab} since program start or the last call of @code{endfsent}, the file will be opened. -The function returns a pointer to an variable of type @code{struct +The function returns a pointer to a variable of type @code{struct fstab}. This variable is shared by all threads and therefore this function is not thread-safe. If an error occurred @code{getfsent} returns a @code{NULL} pointer. @@ -340,7 +340,7 @@ argument. If this is the first call to any of the functions handling @file{fstab} since program start or the last call of @code{endfsent}, the file will be opened. -The function returns a pointer to an variable of type @code{struct +The function returns a pointer to a variable of type @code{struct fstab}. This variable is shared by all threads and therefore this function is not thread-safe. If an error occurred @code{getfsent} returns a @code{NULL} pointer. @@ -357,7 +357,7 @@ argument. If this is the first call to any of the functions handling @file{fstab} since program start or the last call of @code{endfsent}, the file will be opened. -The function returns a pointer to an variable of type @code{struct +The function returns a pointer to a variable of type @code{struct fstab}. This variable is shared by all threads and therefore this function is not thread-safe. If an error occurred @code{getfsent} returns a @code{NULL} pointer. @@ -387,11 +387,11 @@ filesystem. It corresponds to the @code{fs_file} element in @item char *mnt_type @code{mnt_type} describes the filesystem type and is therefore equivalent to @code{fs_vfstype} in @code{struct fstab}. @file{mntent.h} -defines a few symbolic names for some of the value this string can have. -But since the kernel can support an arbitrary filesystems it does not +defines a few symbolic names for some of the values this string can have. +But since the kernel can support arbitrary filesystems it does not make much sense to give them symbolic names. If one knows the symbol name one also knows the filesystem name. Nevertheless here follows the -list of the symbol provided in @file{mntent.h}. +list of the symbols provided in @file{mntent.h}. @vtable @code @item MNTTYPE_IGNORE @@ -414,7 +414,7 @@ the filesystem. As for the equivalent element @code{fs_mntops} of The @file{mntent.h} file defines a number of macros with string values which correspond to some of the options understood by the kernel. There -might be many more options which are possible so it makes not much sense +might be many more options which are possible so it doesn't make much sense to rely on these macros but to be consistent here is the list: @vtable @code @@ -539,7 +539,7 @@ end of file reached, @comment mntent.h @comment BSD @deftypefun int addmntent (FILE *@var{stream}, const struct mntent *@var{mnt}) -The @code{addmntent} function allows to add a new entry to the file +The @code{addmntent} function allows adding a new entry to the file previously opened with @code{setmntent}. The new entries are always appended. I.e., even if the position of the file descriptor is not at the end of the file this function does not overwrite an existing entry diff --git a/manual/users.texi b/manual/users.texi index 7317f5e..e6318ac 100644 --- a/manual/users.texi +++ b/manual/users.texi @@ -1071,7 +1071,7 @@ the user accounting database. All the @code{get*} functions mentioned before store the information they return in a static buffer. This can be a problem in multi-threaded -programs since the data return for the request is overwritten be the +programs since the data returned for the request is overwritten by the return value data in another thread. Therefore the GNU C Library provides as extensions three more functions which return the data in a user-provided buffer. @@ -1853,16 +1853,16 @@ group of users with a certain machine. On the other hand grouping of host names is not supported so far. In Sun Microsystems SunOS appeared a new kind of database, the netgroup -database. It allows to group hosts, users, and domain freely, giving -them individual names. More concrete: a netgroup is a list of triples -consisting of a host name, a user name, and a domain name, where any of -the entries can be a wildcard entry, matching all inputs. A last +database. It allows grouping hosts, users, and domains freely, giving +them individual names. To be more concrete, a netgroup is a list of triples +consisting of a host name, a user name, and a domain name where any of +the entries can be a wildcard entry matching all inputs. A last possibility is that names of other netgroups can also be given in the list specifying a netgroup. So one can construct arbitrary hierarchies without loops. Sun's implementation allows netgroups only for the @code{nis} or -@code{nisplus} service @pxref{Services in the NSS configuration}. The +@code{nisplus} service, @pxref{Services in the NSS configuration}. The implementation in the GNU C library has no such restriction. An entry in either of the input services must have the following form: @@ -1873,7 +1873,7 @@ in either of the input services must have the following form: Any of the fields in the triple can be empty which means anything matches. While describing the functions we will see that the opposite case is useful as well. I.e., there may be entries which will not -match any input. For entries like a name consisting of the single +match any input. For entries like this, a name consisting of the single character @code{-} shall be used. @node Lookup Netgroup @@ -1889,10 +1889,10 @@ These functions are declared in @file{netdb.h}. @comment BSD @deftypefun int setnetgrent (const char *@var{netgroup}) A call to this function initializes the internal state of the library to -allow following calls of the @code{getnetgrent} iterate over all entries +allow following calls of the @code{getnetgrent} to iterate over all entries in the netgroup with name @var{netgroup}. -When the call is successful (i.e., when a netgroup with this name exist) +When the call is successful (i.e., when a netgroup with this name exists) the return value is @code{1}. When the return value is @code{0} no netgroup of this name is known or some other error occurred. @end deftypefun @@ -1914,11 +1914,11 @@ the @code{innetgr} function and parts of the implementation of the @comment BSD @deftypefun int getnetgrent (char **@var{hostp}, char **@var{userp}, char **@var{domainp}) This function returns the next unprocessed entry of the currently -selected netgroup. The string pointers, which addresses are passed in +selected netgroup. The string pointers, in which addresses are passed in the arguments @var{hostp}, @var{userp}, and @var{domainp}, will contain after a successful call pointers to appropriate strings. If the string in the next entry is empty the pointer has the value @code{NULL}. -The returned string pointers are only valid unless no of the netgroup +The returned string pointers are only valid if none of the netgroup related functions are called. The return value is @code{1} if the next entry was successfully read. A @@ -1946,7 +1946,7 @@ SunOS libc does not provide this function. @comment netdb.h @comment BSD @deftypefun void endnetgrent (void) -This function free all buffers which were allocated to process the last +This function frees all buffers which were allocated to process the last selected netgroup. As a result all string pointers returned by calls to @code{getnetgrent} are invalid afterwards. @end deftypefun @@ -1975,7 +1975,7 @@ to the other @code{set}/@code{get}/@code{endnetgrent} functions. @end enumerate Any of the pointers @var{hostp}, @var{userp}, and @var{domainp} can be -@code{NULL} which means any value is excepted in this position. This is +@code{NULL} which means any value is accepted in this position. This is also true for the name @code{-} which should not match any other string otherwise. |