Misc changes suggested by mib.

3 files changed, 151 insertions, 88 deletions

diff --git a/manual/filesys.texi b/manual/filesys.texi
index c01779bc2f..5071ef76a4 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -115,9 +115,15 @@ software.
 @comment unistd.h
 @comment BSD
 @deftypefun {char *} getwd (char *@var{buffer})
-This is similar to @code{getcwd}.  The GNU library provides @code{getwd}
-for backwards compatibility with BSD.  The @var{buffer} should be a
-pointer to an array at least @code{PATH_MAX} bytes long.
+This is similar to @code{getcwd}, but has no way to specify the size of
+the buffer.  The GNU library provides @code{getwd} only
+for backwards compatibility with BSD.
+
+The @var{buffer} argument should be a pointer to an array at least
+@code{PATH_MAX} bytes long (@pxref{Limits for Files}).  In the GNU
+system there is no limit to the size of a file name, so this is not
+necessarily enough space to contain the directory name.  That is why
+this function is deprecated.
 @end deftypefun
 
 @comment unistd.h
@@ -177,17 +183,60 @@ This is a structure type used to return information about directory
 entries.  It contains the following fields:
 
 @table @code
-@item char *d_name
+@item char d_name[]
 This is the null-terminated file name component.  This is the only
 field you can count on in all POSIX systems.
 
 @item ino_t d_fileno
 This is the file serial number.  For BSD compatibility, you can also
-refer to this member as @code{d_ino}.
+refer to this member as @code{d_ino}.  In the GNU system and most POSIX
+systems, for most files this the same as the @code{st_ino} member that
+@code{stat} will return for the file.  @xref{File Attributes}.
 
-@item size_t d_namlen
+@item unsigned char d_namlen
 This is the length of the file name, not including the terminating null
-character.
+character.  Its type is @code{unsigned char} because that is the integer
+type of the appropriate size
+
+@item unsigned char d_type
+This is the type of the file, possibly unknown.  The following constants
+are defined for its value:
+
+@table @code
+@item DT_UNKNOWN
+The type is unknown.  On some systems this is the only value returned.
+
+@item DT_REG
+A regular file.
+
+@item DT_DIR
+A directory.
+
+@item DT_FIFO
+A named pipe, or FIFO.  @xref{Named Pipes}.
+
+@item DT_SOCK
+A local-domain socket.  @xref{Local Domain}.
+
+@item DT_CHR
+A character device.
+
+@item DT_BLK
+A block device.
+@end table
+
+This member is a BSD extension.  Each value except DT_UNKNOWN
+corresponds to the file type bits in the @code{st_mode} member of
+@code{struct statbuf}.  These two macros convert between @code{d_type}
+values and @code{st_mode} values:
+
+@deftypefun int IFTODT (mode_t @var{mode})
+This returns the @code{d_type} value corresponding to @var{mode}.
+@end deftypefun
+
+@deftypefun mode_t DTTOIF (int @var{dirtype})
+This returns the @code{st_mode} value corresponding to @var{dirtype}.
+@end deftypefun
 @end table
 
 This structure may contain additional members in the future.
@@ -370,10 +419,10 @@ or names.
 One file can have names in several directories, so the the organization
 of the file system is not a strict hierarchy or tree.
 
-Since a particular file exists within a single file system, all its
-names must be in directories in that file system.  @code{link} reports
-an error if you try to make a hard link to the file from another file
-system.
+In most implementations, it is not possible to have hard links to the
+same file in multiple file systems.  @code{link} reports an error if you
+try to make a hard link to the file from another file system when this
+cannot be done.
 
 The prototype for the @code{link} function is declared in the header
 file @file{unistd.h}.
@@ -421,8 +470,8 @@ The directory or file system that would contain the new link is ``full''
 and cannot be extended.
 
 @item EPERM
-Some implementations only allow privileged users to make links to
-directories, and others prohibit this operation entirely.  This error
+In the GNU system and some others, you cannot make links to directories.
+many systems allow only privileged users to do so.  This error
 is used to report the problem.
 
 @item EROFS
@@ -457,13 +506,14 @@ happen when you try to open the link.  The @code{open} function realizes
 you have specified the name of a link, reads the file name contained in
 the link, and opens that file name instead.  The @code{stat} function
 likewise operates on the file that the symbolic link points to, instead
-of on the link itself.  So does @code{link}, the function that makes a
-hard link.
+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.
+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
+symbolic link, which one rarely wants.
 
 Prototypes for the functions listed in this section are in
 @file{unistd.h}.
@@ -560,7 +610,6 @@ A hardware error occurred while reading or writing data on the disk.
 @cindex unlinking a file
 
 You can delete a file with the functions @code{unlink} or @code{remove}.
-(These names are synonymous.)
 
 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
@@ -583,15 +632,15 @@ on error.  In addition to the usual file name syntax errors
 defined for this function:
 
 @table @code
-@item EACCESS
+@item EACCES
 Write permission is denied for the directory from which the file is to be
 removed.
 
 @item EBUSY
 This error indicates that the file is being used by the system in such a
-way that it can't be unlinked.  Examples of situations where you might
-see this error are if the file name specifies the root directory or a
-mount point for a file system.
+way that it can't be unlinked.  For example, you might see this error if
+the file name specifies the root directory or a mount point for a file
+system.
 
 @item ENOENT
 The file name to be deleted doesn't exist.
@@ -600,6 +649,7 @@ The file name to be deleted doesn't exist.
 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.
+The GNU system 
 
 @item EROFS
 The directory in which the file name is to be deleted is on a read-only
@@ -607,15 +657,6 @@ file system, and can't be modified.
 @end table
 @end deftypefun
 
-@comment stdio.h
-@comment ANSI
-@deftypefun int remove (const char *@var{filename})
-The @code{remove} function is another name for @code{unlink}.
-@code{remove} is the ANSI C name, whereas @code{unlink} is the POSIX.1
-name.  The name @code{remove} is declared in @file{stdio.h}.
-@pindex stdio.h
-@end deftypefun
-
 @comment unistd.h
 @comment POSIX.1
 @deftypefun int rmdir (const char *@var{filename})
@@ -630,19 +671,28 @@ are two additional @code{errno} error conditions defined for
 @code{rmdir}:
 
 @table @code
-@item EEXIST
-@itemx ENOTEMPTY
+@item ENOTEMPTY
+@itemx EEXIST
 The directory to be deleted is not empty.  
 @end table
 
-These two error codes are synonymous; some systems use one, and some
-use the other.
+These two error codes are synonymous; some systems use one, and some use
+the other.  The GNU system always uses @code{ENOTEMPTY}.
 
 The prototype for this function is declared in the header file
 @file{unistd.h}.
 @pindex unistd.h
 @end deftypefun
 
+@comment stdio.h
+@comment ANSI
+@deftypefun int remove (const char *@var{filename})
+This is the ANSI C function to remove a file.  It works like
+@code{unlink} for files and like @code{rmdir} for directories.
+@code{remove} is declared in @file{stdio.h}.
+@pindex stdio.h
+@end deftypefun
+
 @node Renaming Files
 @section Renaming Files
 
@@ -663,12 +713,9 @@ file system as the file (as indicated by 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 says that
-in this case @code{rename} does nothing and reports success---which is
-inconsistent.  We don't know what your operating system will do.  The
-GNU system, when completed, will probably do the right thing (delete
-@var{oldname}) unless you explicitly request strict POSIX compatibility
-``even when it hurts''.
+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.
 
 If the @var{oldname} is not a directory, then any existing file named
 @var{newname} is removed during the renaming operation.  However, if
@@ -685,7 +732,10 @@ 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.
+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.
 
 If @code{rename} fails, it returns @code{-1}.  In addition to the usual
 file name syntax errors (@pxref{File Name Errors}), the following
@@ -703,11 +753,10 @@ the system in a way that prevents the renaming from working.  This includes
 directories that are mount points for filesystems, and directories
 that are the current working directories of processes.
 
-@item EEXIST
-The directory @var{newname} isn't empty.
-
 @item ENOTEMPTY
-The directory @var{newname} isn't empty.
+@itemx EEXIST
+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}.
@@ -857,7 +906,9 @@ files on the same device.
 
 @item dev_t st_dev
 Identifies the device containing the file.  The @code{st_ino} and
-@code{st_dev}, taken together, uniquely identify the file.
+@code{st_dev}, taken together, uniquely identify the file.  The
+@code{st_dev} value is not necessarily consistent across reboots or
+system crashes, however.
 
 @item nlink_t st_nlink
 The number of hard links to the file.  This count keeps track of how many
@@ -920,9 +971,9 @@ might not be detected as sparse at all.  For practical applications,
 this is not a problem.
 
 @item unsigned int st_blksize
-The optimal block size for reading of writing this file.  You might use
-this size for allocating the buffer space for reading of writing the
-file.
+The optimal block size for reading of writing this file, in bytes.  You
+might use this size for allocating the buffer space for reading of
+writing the file.  (This is unrelated to @code{st_blocks}.)
 @end table
 @end deftp
 
@@ -1397,11 +1448,11 @@ many times in succession.
 @c !!! obsolete in all modern systems (but ask mib to be sure)
 
 On a directory, the sticky bit gives permission to delete a file in the
-directory if you can write the contents of 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 sticky bit makes it possible to control deletion for
-individual files.
+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).
+This is commonly used for the @file{/tmp} directory, where anyone may
+create files, but not delete files created by other users.
 @end table
 
 The actual bit values of the symbols are listed in the table above
@@ -1465,7 +1516,7 @@ For an ordinary file, this is typically read and write permission for
 all classes of users.  These permissions are then restricted as
 specified by the individual user's own file creation mask.
 
-@pindex chmod
+@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.
@@ -1527,9 +1578,7 @@ 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
-itself.  There is actually no way to set the mode of a link, which is
-always @code{-1}.
-@c I verified this experimentally.  It does not depend on umask. -- rms.
+itself.
 
 This function returns @code{0} if successful and @code{-1} if not.  In
 addition to the usual file name syntax errors (@pxref{File Name
@@ -1614,6 +1663,10 @@ want to try to keep track of the diverse features that different systems
 have.  Using @code{access} is simple and automatically does whatever is
 appropriate for the system you are using.
 
+@code{access} is @emph{only} only appropriate to use in setuid programs.
+A non-setuid program will always use the effective ID rather than the
+real ID.
+
 @pindex unistd.h
 The symbols in this section are declared in @file{unistd.h}.
 
diff --git a/manual/setjmp.texi b/manual/setjmp.texi
index 2732b6f1e7..6fee67186e 100644
--- a/manual/setjmp.texi
+++ b/manual/setjmp.texi
@@ -136,7 +136,7 @@ following contexts:
 @itemize @bullet
 @item
 As the test expression of a selection or iteration
-statement (such as @samp{if} or @samp{while}).
+statement (such as @samp{if}, @samp{switch}, or @samp{while}).
 
 @item
 As one operand of a equality or comparison operator that appears as the
diff --git a/manual/time.texi b/manual/time.texi
index 657aeb5688..9557cd5494 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -148,9 +148,11 @@ This is the CPU time used by the system on behalf of the calling process.
 This is the sum of the @code{tms_utime} values and the @code{tms_cutime}
 values of all terminated child processes of the calling process, whose
 status has been reported to the parent process by @code{wait} or
-@code{waitpid}; see @ref{Process Completion}.  In other words, it represents
-the total CPU time used in executing the instructions of all the terminated
-child processes of the calling process.
+@code{waitpid}; see @ref{Process Completion}.  In other words, it
+represents the total CPU time used in executing the instructions of all
+the terminated child processes of the calling process, excluding child
+processes which have not yet been reported by @code{wait} or
+@code{waitpid}.
 
 @item clock_t tms_cstime
 This is similar to @code{tms_cutime}, but represents the total CPU time
@@ -299,9 +301,9 @@ to a normal @code{time_t} value.
 This is the fractional second value, represented as the number of
 microseconds.
 
-Some times struct timeval values are user for time intervals.  Then the
+Some times struct timeval values are used for time intervals.  Then the
 @code{tv_sec} member is the number of seconds in the interval, and
-@code{tv_usec} is the number of addictional microseconds.
+@code{tv_usec} is the number of additional microseconds.
 @end table
 @end deftp
 
@@ -439,7 +441,7 @@ and @code{adjtime} functions are derived from BSD.
 @cindex broken-down time
 @cindex calendar time and broken-down time
 
-Calender time is represented as a number of seconds.  This is convenient
+Calendar time is represented as a number of seconds.  This is convenient
 for calculation, but has no resemblance to the way people normally
 represent dates and times.  By contrast, @dfn{broken-down time} is a binary
 representation separated into year, month, day, and so on.  Broken down
@@ -596,9 +598,9 @@ string.)
 @comment time.h
 @comment ANSI
 @deftypefun {char *} ctime (const time_t *@var{time})
-The @code{ctime} function is similar to @code{asctime}, except that
-the time value is specified in calendar time (rather than local time)
-format.  It is equivalent to
+The @code{ctime} function is similar to @code{asctime}, except that the
+time value is specified as a @code{time_t} calendar time value rather
+than in broken-down local time format.  It is equivalent to
 
 @smallexample
 asctime (localtime (@var{time}))
@@ -716,13 +718,19 @@ For an example of @code{strftime}, see @ref{Time Functions Example}.
 @node TZ Variable
 @subsection Specifying the Time Zone with @code{TZ}
 
-In the GNU system, a user can specify the time zone by means of the
+In POSIX systems, a user can specify the time zone by means of the
 @code{TZ} environment variable.  For information about how to set
-environment variables, see @ref{Environment Variables}.  The functions for
-accessing the time zone are declared in @file{time.h}.
+environment variables, see @ref{Environment Variables}.  The functions
+for accessing the time zone are declared in @file{time.h}.
 @pindex time.h
 @cindex time zone
 
+You should not normally need to set @code{TZ}.  If the system is
+configured properly, the default timezone will be correct.  You might
+set @code{TZ} if you are using a computer over the network from a
+different timezone, and would like times reported to you in the timezone
+that local for you, rather than what is local for the computer.
+
 The value of the @code{TZ} variable can be of one of three formats.  The
 first format is used when there is no Daylight Saving Time (or summer
 time) in the local time zone:
@@ -804,7 +812,7 @@ EST+5EDT,M4.1.0/M10.5.0
 The schedule of daylight savings time in any particular jurisdiction has
 changed over the years.  To be strictly correct, the conversion of dates
 and times in the past should be based on the schedule that was in effect
-then.  However, the system has no facilities to let you specify how the
+then.  However, this format has no facilities to let you specify how the
 schedule has changed from year to year.  The most you can do is specify
 one particular schedule---usually the present day schedule---and this is
 used to convert any date, no matter when.
@@ -819,6 +827,7 @@ Each operating system interprets this format differently; in the GNU C
 library, @var{characters} is the name of a file which describes the time
 zone.
 
+@strong{NOTE: I'm planning to update this for the tzfile scheme.}
 If the @code{TZ} environment variable does not have a value, the
 operation chooses a time zone by default.  Each operating system has its
 own rules for choosing the default time zone, so there is little we can
@@ -1303,8 +1312,9 @@ its stack past this size, it gets a @code{SIGSEGV} signal.
 @item RLIMIT_CORE
 @vindex RLIMIT_CORE
 The maximum size core file that this process can create.  If the process
-terminates and a core file is made, and this maximum size is not enough,
-the core file is truncated.
+terminates and would dump a core file larger than this maximum size,
+then no core file is created.  So setting this limit to zero prevents
+core files from ever being created.
 
 @comment sys/resource.h
 @comment BSD
@@ -1317,11 +1327,13 @@ surplus.
 
 @comment sys/resource.h
 @comment BSD
-@item RLIMIT_OPEN_FILES
+@item RLIMIT_NOFILE
+@itemx RLIMIT_OFILE
 @vindex RLIMIT_OPEN_FILES
-The maximum number of files that the process can open.
-If it tries to open more files than this, it gets error code
-@code{EMFILE}.  @xref{Error Codes}.
+The maximum number of files that the process can open.  If it tries to
+open more files than this, it gets error code @code{EMFILE}.
+@xref{Error Codes}.  Not all systems support this limit; GNU does, and
+4.4 BSD does.
 
 @comment sys/resource.h
 @comment BSD
@@ -1377,10 +1389,9 @@ The smallest valid priority value.
 @comment BSD
 @deftypefun int getpriority (int @var{class}, int @var{id})
 Read the priority of a class of processes; @var{class} and @var{id}
-specify which ones (see below).
-
-@c ??? What happens if class and id specify several processes
-@c ??? whose priorities differ?
+specify which ones (see below).  If the processes specified do not all
+have the same priority, this returns the smallest value that any of them
+has.
 
 The return value is the priority value on success, and @code{-1} on
 failure.  The following @code{errno} error condition are possible for
@@ -1404,7 +1415,7 @@ could be the priority value.  The only way to make certain is to set
 @comment sys/resource.h
 @comment BSD
 @deftypefun int setpriority (int @var{class}, int @var{id}, int @var{priority})
-Read the priority of a class of processes; @var{class} and @var{id}
+Set the priority of a class of processes; @var{class} and @var{id}
 specify which ones (see below).
 
 The return value is @code{0} on success and @code{-1} on failure.  The
@@ -1463,8 +1474,7 @@ current process group, or the current user, according to @var{class}.
 @comment dunno.h
 @deftypefun int nice (int @var{increment})
 Increment the priority of the current process by @var{increment}.
-The return value is not meaningful.
-@c ??? What is it in GNU libc?
+The return value is the same as for @code{setpriority}.
 
 Here is an equivalent definition for @code{nice}:
 
@@ -1473,7 +1483,7 @@ int
 nice (int increment)
 @{
   int old = getpriority (PRIO_PROCESS, 0);
-  setpriority (PRIO_PROCESS, 0, old + increment);
+  return setpriority (PRIO_PROCESS, 0, old + increment);
 @}
 @end smallexample
 @end deftypefun