about summary refs log tree commit diff
path: root/manual/filesys.texi
diff options
context:
space:
mode:
Diffstat (limited to 'manual/filesys.texi')
-rw-r--r--manual/filesys.texi70
1 files changed, 63 insertions, 7 deletions
diff --git a/manual/filesys.texi b/manual/filesys.texi
index c550d72f1b..84c9f6b8a3 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -140,6 +140,34 @@ syntax errors (@pxref{File Name Errors}), plus @code{ENOTDIR} if the
 file @var{filename} is not a directory.
 @end deftypefun
 
+@comment unistd.h
+@comment XPG
+@deftypefun int fchdir (int @var{filedes})
+This function is used to set the process's working directory to
+directory associated with the file descriptor @var{filedes}.
+
+The normal, successful return value from @code{fchdir} is @code{0}.  A
+value of @code{-1} is returned to indicate an error.  The following
+@code{errno} error conditions are defined for this function:
+
+@table @code
+@item EACCES
+Read permission is denied for the directory named by @code{dirname}.
+
+@item EBADF
+The @var{filedes} argument is not a valid file descriptor.
+
+@item ENOTDIR
+The file descriptor @var{filedes} is not associated with a directory.
+
+@item EINTR
+The function call was interrupt by a signal.
+
+@item EIO
+An I/O error occurred.
+@end table
+@end deftypefun
+
 
 @node Accessing Directories
 @section Accessing Directories
@@ -206,7 +234,7 @@ type of the appropriate size
 This is the type of the file, possibly unknown.  The following constants
 are defined for its value:
 
-@table @code
+@vtable @code
 @item DT_UNKNOWN
 The type is unknown.  On some systems this is the only value returned.
 
@@ -227,24 +255,34 @@ A character device.
 
 @item DT_BLK
 A block device.
-@end table
+@end vtable
 
-This member is a BSD extension.  On systems where it is used, it
+This member is a BSD extension.  The symbol @code{_DIRENT_HAVE_D_TYPE}
+is defined if this member is available.  On systems where it is used, it
 corresponds to the file type bits in the @code{st_mode} member of
-@code{struct statbuf}.  On other systems it will always be DT_UNKNOWN.
-These two macros convert between @code{d_type} values and @code{st_mode}
-values:
+@code{struct statbuf}.  If the value cannot be determine the member
+value is DT_UNKNOWN.  These two macros convert between @code{d_type}
+values and @code{st_mode} values:
 
+@comment dirent.h
+@comment BSD
 @deftypefun int IFTODT (mode_t @var{mode})
 This returns the @code{d_type} value corresponding to @var{mode}.
 @end deftypefun
 
+@comment dirent.h
+@comment BSD
 @deftypefun mode_t DTTOIF (int @var{dtype})
 This returns the @code{st_mode} value corresponding to @var{dtype}.
 @end deftypefun
 @end table
 
-This structure may contain additional members in the future.
+This structure may contain additional members in the future.  Their
+availability is always announced in the compilation environment by a
+macro names @code{_DIRENT_HAVE_D_xxx} where @code{xxx} is replaced by
+the name of the new member.  For instance, the member @code{d_reclen}
+available on some systems is announced through the macro
+@code{_DIRENT_HAVE_D_RECLEN}.
 
 When a file has multiple names, each name has its own directory entry.
 The only way you can tell that the directory entries belong to a
@@ -304,6 +342,24 @@ 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
 
+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
+@code{fchdir} function could be used.  Historically the @code{DIR} type
+was exposed and programs could access the fields.  This does not happen
+in the GNU C library.  Instead a separate function is provided to allow
+access.
+
+@comment dirent.h
+@comment GNU
+@deftypefun int dirfd (DIR *@var{dirstream})
+The function @code{dirfd} returns the file descriptor associated with
+the directory stream @var{dirstream}.  This descriptor can be used until
+the directory is closed with @code{closedir}.  If the directory stream
+implementation is not using file descriptors the return value is
+@code{-1}.
+@end deftypefun
+
 @node Reading/Closing Directory
 @subsection Reading and Closing a Directory Stream