2.5-18.1

1 files changed, 64 insertions, 13 deletions

diff --git a/manual/filesys.texi b/manual/filesys.texi
index 70889c2f85..2436f22e88 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -196,11 +196,17 @@ files in a directory, perhaps as part of a menu.
 
 @cindex directory stream
 The @code{opendir} function opens a @dfn{directory stream} whose
-elements are directory entries.  You use the @code{readdir} function on
-the directory stream to retrieve these entries, represented as
-@w{@code{struct dirent}} objects.  The name of the file for each entry is
-stored in the @code{d_name} member of this structure.  There are obvious
-parallels here to the stream facilities for ordinary files, described in
+elements are directory entries.  Alternatively @code{fdopendir} can be
+used which can have advantages if the program needs to have more
+control over the way the directory is opened for reading.  This
+allows, for instance, to pass the @code{O_NOATIME} flag to
+@code{open}.
+
+You use the @code{readdir} function on the directory stream to
+retrieve these entries, represented as @w{@code{struct dirent}}
+objects.  The name of the file for each entry is stored in the
+@code{d_name} member of this structure.  There are obvious parallels
+here to the stream facilities for ordinary files, described in
 @ref{I/O on Streams}.
 
 @menu
@@ -349,6 +355,9 @@ The process has too many files open.
 The entire system, or perhaps the file system which contains the
 directory, cannot support any additional open files at the moment.
 (This problem cannot happen on the GNU system.)
+
+@item ENOMEM
+Not enough memory available.
 @end table
 
 The @code{DIR} type is typically implemented using a file descriptor,
@@ -357,6 +366,48 @@ and the @code{opendir} function in terms of the @code{open} function.
 file descriptors are closed on @code{exec} (@pxref{Executing a File}).
 @end deftypefun
 
+The directory which is opened for reading by @code{opendir} is
+identified by the name.  In some situations this is not sufficient.
+Or the way @code{opendir} implicitly creates a file descriptor for the
+directory is not the way a program might want it.  In these cases an
+alternative interface can be used.
+
+@comment dirent.h
+@comment GNU
+@deftypefun {DIR *} fdopendir (int @var{fd})
+The @code{fdopendir} function works just like @code{opendir} but
+instead of taking a file name and opening a file descriptor for the
+directory the caller is required to provide a file descriptor.  This
+file descriptor is then used in subsequent uses of the returned
+directory stream object.
+
+The caller must make sure the file descriptor is associated with a
+directory and it allows reading.
+
+If the @code{fdopendir} call returns successfully the file descriptor
+is now under the control of the system.  It can be used in the same
+way the descriptor implicitly created by @code{opendir} can be used
+but the program must not close the descriptor.
+
+In case the function is unsuccessful it returns a null pointer and the
+file descriptor remains to be usable by the program.  The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EBADF
+The file descriptor is not valid.
+
+@item ENOTDIR
+The file descriptor is not associated with a directory.
+
+@item EINVAL
+The descriptor does not allow reading the directory content.
+
+@item ENOMEM
+Not enough memory available.
+@end table
+@end deftypefun
+
 In some situations it can be desirable to get hold of the file
 descriptor which is created by the @code{opendir} call.  For instance,
 to switch the current working directory to the directory just read the
@@ -531,7 +582,7 @@ added or removed since you last called @code{opendir} or
 
 @comment dirent.h
 @comment BSD
-@deftypefun off_t telldir (DIR *@var{dirstream})
+@deftypefun long int telldir (DIR *@var{dirstream})
 The @code{telldir} function returns the file position of the directory
 stream @var{dirstream}.  You can use this value with @code{seekdir} to
 restore the directory stream to that position.
@@ -539,7 +590,7 @@ restore the directory stream to that position.
 
 @comment dirent.h
 @comment BSD
-@deftypefun void seekdir (DIR *@var{dirstream}, off_t @var{pos})
+@deftypefun void seekdir (DIR *@var{dirstream}, long int @var{pos})
 The @code{seekdir} function sets the file position of the directory
 stream @var{dirstream} to @var{pos}.  The value @var{pos} must be the
 result of a previous call to @code{telldir} on this particular stream;
@@ -1199,10 +1250,10 @@ result is passed back as the return value of the function in a block of
 memory allocated with @code{malloc}.  If the result is not used anymore
 the memory should be freed with a call to @code{free}.
 
-In any of the path components except the last one is missing the
-function returns a NULL pointer.  This is also what is returned if the
-length of the path reaches or exceeds @code{PATH_MAX} characters.  In
-any case @code{errno} is set accordingly.
+If any of the path components is missing the function returns a NULL
+pointer.  This is also what is returned if the length of the path
+reaches or exceeds @code{PATH_MAX} characters.  In any case
+@code{errno} is set accordingly.
 
 @table @code
 @item ENAMETOOLONG
@@ -1740,7 +1791,7 @@ is transparently replaced by @code{ino64_t}.
 @deftp {Data Type} ino64_t
 This is an arithmetic data type used to represent file serial numbers
 for the use in LFS.  In the GNU system, this type is equivalent to
-@code{unsigned long longint}.
+@code{unsigned long long int}.
 
 When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
 available under the name @code{ino_t}.
@@ -2755,7 +2806,7 @@ function.
 
 @comment sys/time.h
 @comment BSD
-@deftypefun int futimes (int *@var{fd}, struct timeval @var{tvp}@t{[2]})
+@deftypefun int futimes (int @var{fd}, struct timeval @var{tvp}@t{[2]})
 This function is like @code{utimes}, except that it takes an open file
 descriptor as an argument instead of a file name.  @xref{Low-Level
 I/O}.  This function comes from FreeBSD, and is not available on all