@file{unistd.h}.
@pindex unistd.h
-@comment unistd.h
-@comment POSIX.1
@deftypefun {char *} getcwd (char *@var{buffer}, size_t @var{size})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
@c If buffer is NULL, this function calls malloc and realloc, and, in
@c case of error, free. Linux offers a getcwd syscall that we use on
not a library function but is a customary name used in most GNU
software.
-@comment unistd.h
-@comment BSD
@deftypefn {Deprecated Function} {char *} getwd (char *@var{buffer})
+@standards{BSD, unistd.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{} @acsfd{}}}
@c Besides the getcwd safety issues, it calls strerror_r on error, which
@c brings in all of the i18n issues.
this function is deprecated.
@end deftypefn
-@comment unistd.h
-@comment GNU
+@vindex PWD
@deftypefun {char *} get_current_dir_name (void)
+@standards{GNU, unistd.h}
@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
@c Besides getcwd, which this function calls as a fallback, it calls
@c getenv, with the potential thread-safety issues that brings about.
-@vindex PWD
-This @code{get_current_dir_name} function is basically equivalent to
-@w{@code{getcwd (NULL, 0)}}. The only difference is that the value of
-the @code{PWD} variable is returned if this value is correct. This is a
-subtle difference which is visible if the path described by the
-@code{PWD} value is using one or more symbol links in which case the
-value returned by @code{getcwd} can resolve the symbol links and
-therefore yield a different result.
+The @code{get_current_dir_name} function is basically equivalent to
+@w{@code{getcwd (NULL, 0)}}, except the value of the @env{PWD}
+environment variable is first examined, and if it does in fact
+correspond to the current directory, that value is returned. This is
+a subtle difference which is visible if the path described by the
+value in @env{PWD} is using one or more symbolic links, in which case
+the value returned by @code{getcwd} would resolve the symbolic links
+and therefore yield a different result.
This function is a GNU extension.
@end deftypefun
-@comment unistd.h
-@comment POSIX.1
@deftypefun int chdir (const char *@var{filename})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function is used to set the process's working directory to
@var{filename}.
file @var{filename} is not a directory.
@end deftypefun
-@comment unistd.h
-@comment XPG
@deftypefun int fchdir (int @var{filedes})
+@standards{XPG, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function is used to set the process's working directory to
directory associated with the file descriptor @var{filedes}.
might obtain it from a directory stream. All the symbols are declared
in the header file @file{dirent.h}.
-@comment dirent.h
-@comment POSIX.1
@deftp {Data Type} {struct dirent}
+@standards{POSIX.1, dirent.h}
This is a structure type used to return information about directory
entries. It contains the following fields:
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 stat}. If the value cannot be determine the member
+@code{struct stat}. If the value cannot be determined 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})
+@standards{BSD, dirent.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
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})
+@standards{BSD, dirent.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This returns the @code{st_mode} value corresponding to @var{dtype}.
@end deftypefun
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_@var{xxx}} where @var{xxx} is replaced
+macro named @code{_DIRENT_HAVE_D_@var{xxx}} where @var{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}.
This section describes how to open a directory stream. All the symbols
are declared in the header file @file{dirent.h}.
-@comment dirent.h
-@comment POSIX.1
@deftp {Data Type} DIR
+@standards{POSIX.1, dirent.h}
The @code{DIR} data type represents a directory stream.
@end deftp
you. Instead, you refer to these objects using the pointers returned by
the following functions.
-@comment dirent.h
-@comment POSIX.1
@deftypefun {DIR *} opendir (const char *@var{dirname})
+@standards{POSIX.1, dirent.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
@c Besides the safe syscall, we have to allocate the DIR object with
@c __alloc_dir, that calls malloc.
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})
+@standards{GNU, dirent.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
@c The DIR object is allocated with __alloc_dir, that calls malloc.
The @code{fdopendir} function works just like @code{opendir} but
in @theglibc{}. Instead a separate function is provided to allow
access.
-@comment dirent.h
-@comment GNU
@deftypefun int dirfd (DIR *@var{dirstream})
+@standards{GNU, dirent.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The function @code{dirfd} returns the file descriptor associated with
the directory stream @var{dirstream}. This descriptor can be used until
stream, and how to close the stream when you are done with it. All the
symbols are declared in the header file @file{dirent.h}.
-@comment dirent.h
-@comment POSIX.1
@deftypefun {struct dirent *} readdir (DIR *@var{dirstream})
-@safety{@prelim{}@mtunsafe{@mtasurace{:dirstream}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@standards{POSIX.1, dirent.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
@c This function holds dirstream's non-recursive lock, which brings
@c about the usual issues with locks and async signals and cancellation,
@c but the lock taking is not enough to make the returned value safe to
entering an infinite loop, you should stop reading from the directory
after the first error.
-In POSIX.1-2008, @code{readdir} is not thread-safe. In @theglibc{}
-implementation, it is safe to call @code{readdir} concurrently on
-different @var{dirstream}s, but multiple threads accessing the same
-@var{dirstream} result in undefined behavior. @code{readdir_r} is a
-fully thread-safe alternative, but suffers from poor portability (see
-below). It is recommended that you use @code{readdir}, with external
-locking if multiple threads access the same @var{dirstream}.
+@strong{Caution:} The pointer returned by @code{readdir} points to
+a buffer within the @code{DIR} object. The data in that buffer will
+be overwritten by the next call to @code{readdir}. You must take care,
+for instance, to copy the @code{d_name} string if you need it later.
+
+Because of this, it is not safe to share a @code{DIR} object among
+multiple threads, unless you use your own locking to ensure that
+no thread calls @code{readdir} while another thread is still using the
+data from the previous call. In @theglibc{}, it is safe to call
+@code{readdir} from multiple threads as long as each thread uses
+its own @code{DIR} object. POSIX.1-2008 does not require this to
+be safe, but we are not aware of any operating systems where it
+does not work.
+
+@code{readdir_r} allows you to provide your own buffer for the
+@code{struct dirent}, but it is less portable than @code{readdir}, and
+has problems with very long filenames (see below). We recommend
+you use @code{readdir}, but do not share @code{DIR} objects.
@end deftypefun
-@comment dirent.h
-@comment GNU
@deftypefun int readdir_r (DIR *@var{dirstream}, struct dirent *@var{entry}, struct dirent **@var{result})
+@standards{GNU, dirent.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
This function is a version of @code{readdir} which performs internal
locking. Like @code{readdir} it returns the next entry from the
directory. To prevent conflicts between simultaneously running
threads the result is stored inside the @var{entry} object.
-@strong{Portability Note:} It is recommended to use @code{readdir}
-instead of @code{readdir_r} for the following reasons:
+@strong{Portability Note:} @code{readdir_r} is deprecated. It is
+recommended to use @code{readdir} instead of @code{readdir_r} for the
+following reasons:
@itemize @bullet
@item
To support large filesystems on 32-bit machines there are LFS variants
of the last two functions.
-@comment dirent.h
-@comment LFS
@deftypefun {struct dirent64 *} readdir64 (DIR *@var{dirstream})
-@safety{@prelim{}@mtunsafe{@mtasurace{:dirstream}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
+@standards{LFS, dirent.h}
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
The @code{readdir64} function is just like the @code{readdir} function
except that it returns a pointer to a record of type @code{struct
dirent64}. Some of the members of this data type (notably @code{d_ino})
In all other aspects this function is equivalent to @code{readdir}.
@end deftypefun
-@comment dirent.h
-@comment LFS
@deftypefun int readdir64_r (DIR *@var{dirstream}, struct dirent64 *@var{entry}, struct dirent64 **@var{result})
+@standards{LFS, dirent.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
-The @code{readdir64_r} function is equivalent to the @code{readdir_r}
-function except that it takes parameters of base type @code{struct
-dirent64} instead of @code{struct dirent} in the second and third
-position. The same precautions mentioned in the documentation of
+The deprecated @code{readdir64_r} function is equivalent to the
+@code{readdir_r} function except that it takes parameters of base type
+@code{struct dirent64} instead of @code{struct dirent} in the second and
+third position. The same precautions mentioned in the documentation of
@code{readdir_r} also apply here.
@end deftypefun
-@comment dirent.h
-@comment POSIX.1
@deftypefun int closedir (DIR *@var{dirstream})
+@standards{POSIX.1, dirent.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{/hurd}}@acunsafe{@acsmem{} @acsfd{} @aculock{/hurd}}}
@c No synchronization in the posix implementation, only in the hurd
@c one. This is regarded as safe because it is undefined behavior if
already read from an open directory stream. All the symbols are
declared in the header file @file{dirent.h}.
-@comment dirent.h
-@comment POSIX.1
@deftypefun void rewinddir (DIR *@var{dirstream})
+@standards{POSIX.1, dirent.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
The @code{rewinddir} function is used to reinitialize the directory
stream @var{dirstream}, so that if you call @code{readdir} it
@code{rewinddir}.)
@end deftypefun
-@comment dirent.h
-@comment BSD
@deftypefun {long int} telldir (DIR *@var{dirstream})
+@standards{BSD, dirent.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}}
@c The implementation is safe on most platforms, but on BSD it uses
@c cookies, buckets and records, and the global array of pointers to
restore the directory stream to that position.
@end deftypefun
-@comment dirent.h
-@comment BSD
@deftypefun void seekdir (DIR *@var{dirstream}, long int @var{pos})
+@standards{BSD, dirent.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{/bsd} @asulock{/bsd}}@acunsafe{@acsmem{/bsd} @aculock{/bsd}}}
@c The implementation is safe on most platforms, but on BSD it uses
@c cookies, buckets and records, and the global array of pointers to
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 struct dirent **, const struct dirent **))
+@standards{BSD, dirent.h}
+@standards{SVID, dirent.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
@c The scandir function calls __opendirat, __readdir, and __closedir to
@c go over the named dir; malloc and realloc to allocate the namelist
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
-structure of type @code{struct dirent} which describe all selected
+structures 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
the global variable @code{errno} contains more information on the error.
@end deftypefun
-As described above the fourth argument to the @code{scandir} function
+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 @theglibc{} contains implementations of functions which
are very helpful for this purpose.
-@comment dirent.h
-@comment BSD/SVID
@deftypefun int alphasort (const struct dirent **@var{a}, const struct dirent **@var{b})
+@standards{BSD, dirent.h}
+@standards{SVID, dirent.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
@c Calls strcoll.
The @code{alphasort} function behaves like the @code{strcoll} function
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 struct dirent **@var{a}, const struct dirent **@var{b})
+@standards{GNU, dirent.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
@c Calls strverscmp, which will accesses the locale object multiple
@c times.
the information. The LFS provides the new type @w{@code{struct
dirent64}}. To use this we need a new function.
-@comment dirent.h
-@comment GNU
@deftypefun int scandir64 (const char *@var{dir}, struct dirent64 ***@var{namelist}, int (*@var{selector}) (const struct dirent64 *), int (*@var{cmp}) (const struct dirent64 **, const struct dirent64 **))
+@standards{GNU, dirent.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
@c See scandir.
The @code{scandir64} function works like the @code{scandir} function
@code{alphasort} and @code{versionsort} cannot be supplied for that
argument. Instead we provide the two replacement functions below.
-@comment dirent.h
-@comment GNU
@deftypefun int alphasort64 (const struct dirent64 **@var{a}, const struct dirent **@var{b})
+@standards{GNU, dirent.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
@c See alphasort.
The @code{alphasort64} function behaves like the @code{strcoll} function
than zero depending on the order of the two entries @var{a} and @var{b}.
@end deftypefun
-@comment dirent.h
-@comment GNU
@deftypefun int versionsort64 (const struct dirent64 **@var{a}, const struct dirent64 **@var{b})
+@standards{GNU, dirent.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}
@c See versionsort.
The @code{versionsort64} function is like @code{alphasort64}, excepted that it
functions take as one of their arguments a pointer to a callback
function of the appropriate type.
-@comment ftw.h
-@comment GNU
@deftp {Data Type} __ftw_func_t
+@standards{GNU, ftw.h}
@smallexample
int (*) (const char *, const struct stat *, int)
The item is a directory.
@item FTW_NS
The @code{stat} call failed and so the information pointed to by the
-second paramater is invalid.
+second parameter is invalid.
@item FTW_DNR
The item is a directory which cannot be read.
@item FTW_SL
For the LFS interface and for use in the function @code{ftw64}, the
header @file{ftw.h} defines another function type.
-@comment ftw.h
-@comment GNU
@deftp {Data Type} __ftw64_func_t
+@standards{GNU, ftw.h}
@smallexample
int (*) (const char *, const struct stat64 *, int)
@code{struct stat64} which is able to represent the larger values.
@end deftp
-@comment ftw.h
-@comment GNU
@deftp {Data Type} __nftw_func_t
+@standards{GNU, ftw.h}
@smallexample
int (*) (const char *, const struct stat *, int, struct FTW *)
@end smallexample
-@vindex FTW_DP
-@vindex FTW_SLN
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
+@vtable @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
@item FTW_SLN
The current item is a stale symbolic link. The file it points to does
not exist.
-@end table
+@end vtable
The last parameter of the callback function is a pointer to a structure
with some extra information as described below.
For the LFS interface there is also a variant of this data type
available which has to be used with the @code{nftw64} function.
-@comment ftw.h
-@comment GNU
@deftp {Data Type} __nftw64_func_t
+@standards{GNU, ftw.h}
@smallexample
int (*) (const char *, const struct stat64 *, int, struct FTW *)
@code{struct stat64} which is able to represent the larger values.
@end deftp
-@comment ftw.h
-@comment XPG4.2
@deftp {Data Type} {struct FTW}
+@standards{XPG4.2, ftw.h}
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.
@end deftp
-@comment ftw.h
-@comment SVID
@deftypefun int ftw (const char *@var{filename}, __ftw_func_t @var{func}, int @var{descriptors})
+@standards{SVID, ftw.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
@c see nftw for safety details
The @code{ftw} function calls the callback function given in the
directories and then the local file name. So the callback function can
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
+function. If this @code{stat} call is 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.
interface transparently replaces the old interface.
@end deftypefun
-@comment ftw.h
-@comment Unix98
@deftypefun int ftw64 (const char *@var{filename}, __ftw64_func_t @var{func}, int @var{descriptors})
+@standards{Unix98, ftw.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
This function is similar to @code{ftw} but it can work on filesystems
with large files. File information is reported using a variable of type
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})
+@standards{XPG4.2, ftw.h}
@safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}}
@c ftw_startup calls alloca, malloc, free, xstat/lxstat, tdestroy, and ftw_dir
@c if FTW_CHDIR, call open, and fchdir, or chdir and getcwd
The return value is computed in the same way as for @code{ftw}.
@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
+problems, the return value is @math{-1} and @code{errno} is set
accordingly. If the return value of a callback invocation was non-zero
then that value is returned.
interface transparently replaces the old interface.
@end deftypefun
-@comment ftw.h
-@comment Unix98
@deftypefun int nftw64 (const char *@var{filename}, __nftw64_func_t @var{func}, int @var{descriptors}, int @var{flag})
+@standards{Unix98, ftw.h}
@safety{@prelim{}@mtsafe{@mtasscwd{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{} @acscwd{}}}
This function is similar to @code{nftw} but it can work on filesystems
with large files. File information is reported using a variable of type
file @file{unistd.h}.
@pindex unistd.h
-@comment unistd.h
-@comment POSIX.1
@deftypefun int link (const char *@var{oldname}, const char *@var{newname})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{link} function makes a new link to the existing file named by
@var{oldname}, under the new name @var{newname}.
@end table
@end deftypefun
+@deftypefun int linkat (int oldfd, const char *@var{oldname}, int newfd, const char *@var{newname}, int flags)
+@standards{POSIX.1, unistd.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+
+The @code{linkat} function is analogous to the @code{link} function,
+except that it identifies its source and target using a combination of a
+file descriptor (referring to a directory) and a pathname. If a
+pathnames is not absolute, it is resolved relative to the corresponding
+file descriptor. The special file descriptor @code{AT_FDCWD} denotes
+the current directory.
+
+The @var{flags} argument is a combination of the following flags:
+
+@table @code
+@item AT_SYMLINK_FOLLOW
+If the source path identified by @var{oldfd} and @var{oldname} is a
+symbolic link, @code{linkat} follows the symbolic link and creates a
+link to its target. If the flag is not set, a link for the symbolic
+link itself is created; this is not supported by all file systems and
+@code{linkat} can fail in this case.
+
+@item AT_EMPTY_PATH
+If this flag is specified, @var{oldname} can be an empty string. In
+this case, a new link to the file denoted by the descriptor @var{oldfd}
+is created, which may have been opened with @code{O_PATH} or
+@code{O_TMPFILE}. This flag is a GNU extension.
+@end table
+@end deftypefun
+
@node Symbolic Links
@section Symbolic Links
@cindex soft link
function that makes a hard link, does too. It makes a hard link to the
symbolic link, which one rarely wants.
-Some systems have for some functions operating on files have a limit on
+Some systems have, for some functions operating on files, a limit on
how many symbolic links are followed when resolving a path name. The
limit if it exists is published in the @file{sys/param.h} header file.
-@comment sys/param.h
-@comment BSD
@deftypevr Macro int MAXSYMLINKS
+@standards{BSD, sys/param.h}
The macro @code{MAXSYMLINKS} specifies how many symlinks some function
will follow before returning @code{ELOOP}. Not all functions behave the
-same and this value is not the same a that returned for
+same and this value is not the same as that returned for
@code{_SC_SYMLOOP} by @code{sysconf}. In fact, the @code{sysconf}
result can indicate that there is no fixed limit although
@code{MAXSYMLINKS} exists and has a finite value.
@file{unistd.h}.
@pindex unistd.h
-@comment unistd.h
-@comment BSD
@deftypefun int symlink (const char *@var{oldname}, const char *@var{newname})
+@standards{BSD, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{symlink} function makes a symbolic link to @var{oldname} named
@var{newname}.
@item EIO
A hardware error occurred while reading or writing data on the disk.
-@ignore
@comment not sure about these
+@ignore
@item ELOOP
There are too many levels of indirection. This can be the result of
circular symbolic links to directories.
@end table
@end deftypefun
-@comment unistd.h
-@comment BSD
@deftypefun ssize_t readlink (const char *@var{filename}, char *@var{buffer}, size_t @var{size})
+@standards{BSD, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{readlink} function gets the value of the symbolic link
@var{filename}. The file name that the link points to is copied into
symbolic links to get the real
name of a file where no prefix names a symbolic link which is followed
and no filename in the path is @code{.} or @code{..}. This is for
-instance desirable if files have to be compare in which case different
+instance desirable if files have to be compared in which case different
names can refer to the same inode.
-@comment stdlib.h
-@comment GNU
@deftypefun {char *} canonicalize_file_name (const char *@var{name})
+@standards{GNU, stdlib.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
@c Calls realpath.
memory allocated with @code{malloc}. If the result is not used anymore
the memory should be freed with a call to @code{free}.
-If any of the path components is missing the function returns a NULL
+If any of the path components are 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.
@code{canonicalize_file_name} in that the user has to provide the buffer
where the result is placed in.
-@comment stdlib.h
-@comment XPG
@deftypefun {char *} realpath (const char *restrict @var{name}, char *restrict @var{resolved})
+@standards{XPG, stdlib.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{} @acsfd{}}}
@c Calls malloc, realloc, getcwd, lxstat64, readlink, alloca.
@end deftypefun
The advantage of using this function is that it is more widely
-available. The drawback is that it reports failures for long path on
+available. The drawback is that it reports failures for long paths on
systems which have no limits on the file name length.
@node Deleting Files
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
@deftypefun int unlink (const char *@var{filename})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{unlink} function deletes the file name @var{filename}. If
this is a file's sole name, the file itself is also deleted. (Actually,
@end table
@end deftypefun
-@comment unistd.h
-@comment POSIX.1
@deftypefun int rmdir (const char *@var{filename})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@cindex directories, deleting
@cindex deleting a directory
@pindex unistd.h
@end deftypefun
-@comment stdio.h
-@comment ISO
@deftypefun int remove (const char *@var{filename})
+@standards{ISO, stdio.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c Calls unlink and rmdir.
This is the @w{ISO C} function to remove a file. It works like
The @code{rename} function is used to change a file's name.
@cindex renaming a file
-@comment stdio.h
-@comment ISO
@deftypefun int rename (const char *@var{oldname}, const char *@var{newname})
+@standards{ISO, stdio.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c In the absence of a rename syscall, there's an emulation with link
@c and unlink, but it's racy, even more so if newname exists and is
a shell command @code{mkdir} which does the same thing.)
@c !!! umask
-@comment sys/stat.h
-@comment POSIX.1
@deftypefun int mkdir (const char *@var{filename}, mode_t @var{mode})
+@standards{POSIX.1, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{mkdir} function creates a new, empty directory with name
@var{filename}.
in this section.
@pindex sys/stat.h
-@comment sys/stat.h
-@comment POSIX.1
@deftp {Data Type} {struct stat}
+@standards{POSIX.1, sys/stat.h}
The @code{stat} structure type is used to return information about the
attributes of a file. It contains at least the following members:
this is not a problem.
@item unsigned int st_blksize
-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
+The optimal block size for reading or writing this file, in bytes. You
+might use this size for allocating the buffer space for reading or
writing the file. (This is unrelated to @code{st_blocks}.)
@end table
@end deftp
machines, types which can handle file sizes up to @twoexp{63}.
Therefore a new definition of @code{struct stat} is necessary.
-@comment sys/stat.h
-@comment LFS
@deftp {Data Type} {struct stat64}
+@standards{LFS, sys/stat.h}
The members of this type are the same and have the same names as those
in @code{struct stat}. The only difference is that the members
@code{st_ino}, @code{st_size}, and @code{st_blocks} have a different
in the header file @file{sys/types.h} as well as in @file{sys/stat.h}.
Here is a list of them.
-@comment sys/types.h
-@comment POSIX.1
@deftp {Data Type} mode_t
+@standards{POSIX.1, sys/types.h}
This is an integer data type used to represent file modes. In
@theglibc{}, this is an unsigned type no narrower than @code{unsigned
int}.
@end deftp
@cindex inode number
-@comment sys/types.h
-@comment POSIX.1
@deftp {Data Type} ino_t
+@standards{POSIX.1, sys/types.h}
This is an unsigned integer type used to represent file serial numbers.
(In Unix jargon, these are sometimes called @dfn{inode numbers}.)
In @theglibc{}, this type is no narrower than @code{unsigned int}.
is transparently replaced by @code{ino64_t}.
@end deftp
-@comment sys/types.h
-@comment Unix98
@deftp {Data Type} ino64_t
+@standards{Unix98, sys/types.h}
This is an unsigned integer type used to represent file serial numbers
for the use in LFS. In @theglibc{}, this type is no narrower than
@code{unsigned int}.
available under the name @code{ino_t}.
@end deftp
-@comment sys/types.h
-@comment POSIX.1
@deftp {Data Type} dev_t
+@standards{POSIX.1, sys/types.h}
This is an arithmetic data type used to represent file device numbers.
In @theglibc{}, this is an integer type no narrower than @code{int}.
@end deftp
-@comment sys/types.h
-@comment POSIX.1
@deftp {Data Type} nlink_t
+@standards{POSIX.1, sys/types.h}
This is an integer type used to represent file link counts.
@end deftp
-@comment sys/types.h
-@comment Unix98
@deftp {Data Type} blkcnt_t
+@standards{Unix98, sys/types.h}
This is a signed integer type used to represent block counts.
In @theglibc{}, this type is no narrower than @code{int}.
is transparently replaced by @code{blkcnt64_t}.
@end deftp
-@comment sys/types.h
-@comment Unix98
@deftp {Data Type} blkcnt64_t
+@standards{Unix98, sys/types.h}
This is a signed integer type used to represent block counts for the
use in LFS. In @theglibc{}, this type is no narrower than @code{int}.
a @code{struct stat} object. All three functions are declared in the
header file @file{sys/stat.h}.
-@comment sys/stat.h
-@comment POSIX.1
@deftypefun int stat (const char *@var{filename}, struct stat *@var{buf})
+@standards{POSIX.1, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{stat} function returns information about the attributes of the
file named by @w{@var{filename}} in the structure pointed to by @var{buf}.
replaces the normal implementation.
@end deftypefun
-@comment sys/stat.h
-@comment Unix98
@deftypefun int stat64 (const char *@var{filename}, struct stat64 *@var{buf})
+@standards{Unix98, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function is similar to @code{stat} but it is also able to work on
files larger than @twoexp{31} bytes on 32-bit systems. To be able to do
replaces the interface for small files on 32-bit machines.
@end deftypefun
-@comment sys/stat.h
-@comment POSIX.1
@deftypefun int fstat (int @var{filedes}, struct stat *@var{buf})
+@standards{POSIX.1, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{fstat} function is like @code{stat}, except that it takes an
open file descriptor as an argument instead of a file name.
replaces the normal implementation.
@end deftypefun
-@comment sys/stat.h
-@comment Unix98
@deftypefun int fstat64 (int @var{filedes}, struct stat64 *@var{buf})
+@standards{Unix98, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
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
@c available.
@c @safety{@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
-@comment sys/stat.h
-@comment BSD
@deftypefun int lstat (const char *@var{filename}, struct stat *@var{buf})
+@standards{BSD, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c Direct system call through lxstat, sometimes with an xstat conv call
@c afterwards.
replaces the normal implementation.
@end deftypefun
-@comment sys/stat.h
-@comment Unix98
@deftypefun int lstat64 (const char *@var{filename}, struct stat64 *@var{buf})
+@standards{Unix98, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c Direct system call through lxstat64, sometimes with an xstat conv
@c call afterwards.
@var{m} which is the @code{st_mode} field returned by @code{stat} on
that file:
-@comment sys/stat.h
-@comment POSIX
@deftypefn Macro int S_ISDIR (mode_t @var{m})
+@standards{POSIX, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
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})
+@standards{POSIX, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
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})
+@standards{POSIX, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
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})
+@standards{POSIX, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
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})
+@standards{POSIX, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
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})
+@standards{GNU, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
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})
+@standards{GNU, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This macro returns non-zero if the file is a socket. @xref{Sockets}.
@end deftypefn
((@var{mode} & S_IFMT) == S_IFCHR)
@end smallexample
-@comment sys/stat.h
-@comment BSD
@deftypevr Macro int S_IFMT
+@standards{BSD, sys/stat.h}
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:
-@table @code
-@comment sys/stat.h
-@comment BSD
+@vtable @code
@item S_IFDIR
-@vindex S_IFDIR
+@standards{BSD, sys/stat.h}
This is the file type constant of a directory file.
-@comment sys/stat.h
-@comment BSD
@item S_IFCHR
-@vindex S_IFCHR
+@standards{BSD, sys/stat.h}
This is the file type constant of a character-oriented device file.
-@comment sys/stat.h
-@comment BSD
@item S_IFBLK
-@vindex S_IFBLK
+@standards{BSD, sys/stat.h}
This is the file type constant of a block-oriented device file.
-@comment sys/stat.h
-@comment BSD
@item S_IFREG
-@vindex S_IFREG
+@standards{BSD, sys/stat.h}
This is the file type constant of a regular file.
-@comment sys/stat.h
-@comment BSD
@item S_IFLNK
-@vindex S_IFLNK
+@standards{BSD, sys/stat.h}
This is the file type constant of a symbolic link.
-@comment sys/stat.h
-@comment BSD
@item S_IFSOCK
-@vindex S_IFSOCK
+@standards{BSD, sys/stat.h}
This is the file type constant of a socket.
-@comment sys/stat.h
-@comment BSD
@item S_IFIFO
-@vindex S_IFIFO
+@standards{BSD, sys/stat.h}
This is the file type constant of a FIFO or pipe.
-@end table
+@end vtable
The POSIX.1b standard introduced a few more objects which possibly can
-be implemented as object in the filesystem. These are message queues,
+be implemented as objects in the filesystem. These are message queues,
semaphores, and shared memory objects. To allow differentiating these
-objects from other files the POSIX standard introduces three new test
-macros. But unlike the other macros it does not take the value of the
+objects from other files the POSIX standard introduced three new test
+macros. But unlike the other macros they do not take the value of the
@code{st_mode} field as the parameter. Instead they expect a pointer to
the whole @code{struct stat} structure.
-@comment sys/stat.h
-@comment POSIX
@deftypefn Macro int S_TYPEISMQ (struct stat *@var{s})
+@standards{POSIX, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-If the system implement POSIX message queues as distinct objects and the
+If the system implements POSIX message queues as distinct objects and the
file is a message queue object, this macro returns a non-zero value.
In all other cases the result is zero.
@end deftypefn
-@comment sys/stat.h
-@comment POSIX
@deftypefn Macro int S_TYPEISSEM (struct stat *@var{s})
+@standards{POSIX, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-If the system implement POSIX semaphores as distinct objects and the
+If the system implements POSIX semaphores as distinct objects and the
file is a semaphore object, this macro returns a non-zero value.
In all other cases the result is zero.
@end deftypefn
-@comment sys/stat.h
-@comment POSIX
@deftypefn Macro int S_TYPEISSHM (struct stat *@var{s})
+@standards{POSIX, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-If the system implement POSIX shared memory objects as distinct objects
+If the system implements POSIX shared memory objects as distinct objects
and the file is a shared memory object, this macro returns a non-zero
value. In all other cases the result is zero.
@end deftypefn
@pindex unistd.h
The prototype for this function is declared in @file{unistd.h}.
-@comment unistd.h
-@comment POSIX.1
@deftypefun int chown (const char *@var{filename}, uid_t @var{owner}, gid_t @var{group})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{chown} function changes the owner of the file @var{filename} to
@var{owner}, and its group owner to @var{group}.
@end table
@end deftypefun
-@comment unistd.h
-@comment BSD
@deftypefun int fchown (int @var{filedes}, uid_t @var{owner}, gid_t @var{group})
+@standards{BSD, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This is like @code{chown}, except that it changes the owner of the open
file with descriptor @var{filedes}.
These symbolic constants are defined for the file mode bits that control
access permission for the file:
-@table @code
-@comment sys/stat.h
-@comment POSIX.1
+@vtable @code
@item S_IRUSR
-@vindex S_IRUSR
-@comment sys/stat.h
-@comment BSD
@itemx S_IREAD
-@vindex S_IREAD
+@standards{POSIX.1, sys/stat.h}
+@standardsx{S_IREAD, BSD, sys/stat.h}
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
-@comment POSIX.1
@item S_IWUSR
-@vindex S_IWUSR
-@comment sys/stat.h
-@comment BSD
@itemx S_IWRITE
-@vindex S_IWRITE
+@standards{POSIX.1, sys/stat.h}
+@standardsx{S_IWRITE, BSD, sys/stat.h}
Write permission bit for the owner of the file. Usually 0200.
@w{@code{S_IWRITE}} is an obsolete synonym provided for BSD compatibility.
-@comment sys/stat.h
-@comment POSIX.1
@item S_IXUSR
-@vindex S_IXUSR
-@comment sys/stat.h
-@comment BSD
@itemx S_IEXEC
-@vindex S_IEXEC
+@standards{POSIX.1, sys/stat.h}
+@standardsx{S_IEXEC, BSD, sys/stat.h}
Execute (for ordinary files) or search (for directories) permission bit
for the owner of the file. Usually 0100. @code{S_IEXEC} is an obsolete
synonym provided for BSD compatibility.
-@comment sys/stat.h
-@comment POSIX.1
@item S_IRWXU
-@vindex S_IRWXU
+@standards{POSIX.1, sys/stat.h}
This is equivalent to @samp{(S_IRUSR | S_IWUSR | S_IXUSR)}.
-@comment sys/stat.h
-@comment POSIX.1
@item S_IRGRP
-@vindex S_IRGRP
+@standards{POSIX.1, sys/stat.h}
Read permission bit for the group owner of the file. Usually 040.
-@comment sys/stat.h
-@comment POSIX.1
@item S_IWGRP
-@vindex S_IWGRP
+@standards{POSIX.1, sys/stat.h}
Write permission bit for the group owner of the file. Usually 020.
-@comment sys/stat.h
-@comment POSIX.1
@item S_IXGRP
-@vindex S_IXGRP
+@standards{POSIX.1, sys/stat.h}
Execute or search permission bit for the group owner of the file.
Usually 010.
-@comment sys/stat.h
-@comment POSIX.1
@item S_IRWXG
-@vindex S_IRWXG
+@standards{POSIX.1, sys/stat.h}
This is equivalent to @samp{(S_IRGRP | S_IWGRP | S_IXGRP)}.
-@comment sys/stat.h
-@comment POSIX.1
@item S_IROTH
-@vindex S_IROTH
+@standards{POSIX.1, sys/stat.h}
Read permission bit for other users. Usually 04.
-@comment sys/stat.h
-@comment POSIX.1
@item S_IWOTH
-@vindex S_IWOTH
+@standards{POSIX.1, sys/stat.h}
Write permission bit for other users. Usually 02.
-@comment sys/stat.h
-@comment POSIX.1
@item S_IXOTH
-@vindex S_IXOTH
+@standards{POSIX.1, sys/stat.h}
Execute or search permission bit for other users. Usually 01.
-@comment sys/stat.h
-@comment POSIX.1
@item S_IRWXO
-@vindex S_IRWXO
+@standards{POSIX.1, sys/stat.h}
This is equivalent to @samp{(S_IROTH | S_IWOTH | S_IXOTH)}.
-@comment sys/stat.h
-@comment POSIX
@item S_ISUID
-@vindex S_ISUID
+@standards{POSIX, sys/stat.h}
This is the set-user-ID on execute bit, usually 04000.
@xref{How Change Persona}.
-@comment sys/stat.h
-@comment POSIX
@item S_ISGID
-@vindex S_ISGID
+@standards{POSIX, sys/stat.h}
This is the set-group-ID on execute bit, usually 02000.
@xref{How Change Persona}.
@cindex sticky bit
-@comment sys/stat.h
-@comment BSD
@item S_ISVTX
-@vindex S_ISVTX
+@standards{BSD, sys/stat.h}
This is the @dfn{sticky} bit, usually 01000.
For a directory it gives permission to delete a file in that directory
them). Therefore one has to use the @code{_GNU_SOURCE} feature select
macro, or not define any feature test macros, to get the definition
(@pxref{Feature Test Macros}).
-@end table
+@end vtable
The actual bit values of the symbols are listed in the table above
so you can decode file mode values when debugging your programs.
The functions in this section are declared in @file{sys/stat.h}.
@pindex sys/stat.h
-@comment sys/stat.h
-@comment POSIX.1
@deftypefun mode_t umask (mode_t @var{mask})
+@standards{POSIX.1, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{umask} function sets the file creation mask of the current
process to @var{mask}, and returns the previous value of the file
you just want to read the mask value, because it is reentrant.
@end deftypefun
-@comment sys/stat.h
-@comment GNU
@deftypefun mode_t getumask (void)
+@standards{GNU, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Return the current value of the file creation mask for the current
process. This function is a GNU extension and is only available on
@gnuhurdsystems{}.
@end deftypefun
-@comment sys/stat.h
-@comment POSIX.1
@deftypefun int chmod (const char *@var{filename}, mode_t @var{mode})
+@standards{POSIX.1, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{chmod} function sets the access permission bits for the file
named by @var{filename} to @var{mode}.
@end table
@end deftypefun
-@comment sys/stat.h
-@comment BSD
@deftypefun int fchmod (int @var{filedes}, mode_t @var{mode})
+@standards{BSD, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This is like @code{chmod}, except that it changes the permissions of the
currently open file given by @var{filedes}.
be written only by the super-user, the modifying program will have to be
owned by @code{root} and the setuid-bit must be set.
-But beside the files the program is intended to change the user should
+But besides the files the program is intended to change the user should
not be allowed to access any file to which s/he would not have access
anyway. The program therefore must explicitly check whether @emph{the
user} would have the necessary access to a file, before it reads or
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.
+@code{access} is @emph{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}.
-@comment unistd.h
-@comment POSIX.1
@deftypefun int access (const char *@var{filename}, int @var{how})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{access} function checks to see whether the file named by
@var{filename} can be accessed in the way specified by the @var{how}
are integer constants.
@pindex unistd.h
-@comment unistd.h
-@comment POSIX.1
@deftypevr Macro int R_OK
+@standards{POSIX.1, unistd.h}
Flag meaning test for read permission.
@end deftypevr
-@comment unistd.h
-@comment POSIX.1
@deftypevr Macro int W_OK
+@standards{POSIX.1, unistd.h}
Flag meaning test for write permission.
@end deftypevr
-@comment unistd.h
-@comment POSIX.1
@deftypevr Macro int X_OK
+@standards{POSIX.1, unistd.h}
Flag meaning test for execute/search permission.
@end deftypevr
-@comment unistd.h
-@comment POSIX.1
@deftypevr Macro int F_OK
+@standards{POSIX.1, unistd.h}
Flag meaning test for existence of the file.
@end deftypevr
need to include the header file @file{utime.h} to use this facility.
@pindex utime.h
-@comment utime.h
-@comment POSIX.1
@deftp {Data Type} {struct utimbuf}
+@standards{POSIX.1, utime.h}
The @code{utimbuf} structure is used with the @code{utime} function to
specify new access and modification times for a file. It contains the
following members:
@end table
@end deftp
-@comment utime.h
-@comment POSIX.1
@deftypefun int utime (const char *@var{filename}, const struct utimbuf *@var{times})
+@standards{POSIX.1, utime.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c In the absence of a utime syscall, it non-atomically converts times
@c to a struct timeval and calls utimes.
in the header file @file{sys/time.h}.
@pindex sys/time.h
-@comment sys/time.h
-@comment BSD
@deftypefun int utimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]})
+@standards{BSD, sys/time.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c In the absence of a utimes syscall, it non-atomically converts tvp
@c to struct timespec array and issues a utimensat syscall, or to
function.
@end deftypefun
-@comment sys/time.h
-@comment BSD
@deftypefun int lutimes (const char *@var{filename}, const struct timeval @var{tvp}@t{[2]})
+@standards{BSD, sys/time.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c Since there's no lutimes syscall, it non-atomically converts tvp
@c to struct timespec array and issues a utimensat syscall.
function.
@end deftypefun
-@comment sys/time.h
-@comment BSD
@deftypefun int futimes (int @var{fd}, const struct timeval @var{tvp}@t{[2]})
+@standards{BSD, sys/time.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c Since there's no futimes syscall, it non-atomically converts tvp
@c to struct timespec array and issues a utimensat syscall, falling back
@emph{undefined} results. On many systems, such a call will appear to
succeed, without actually accomplishing anything.
-@comment unistd.h
-@comment X/Open
@deftypefun int truncate (const char *@var{filename}, off_t @var{length})
+@standards{X/Open, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c In the absence of a truncate syscall, we use open and ftruncate.
@end deftypefun
-@comment unistd.h
-@comment Unix98
@deftypefun int truncate64 (const char *@var{name}, off64_t @var{length})
+@standards{Unix98, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c In the absence of a syscall, try truncate if length fits.
This function is similar to the @code{truncate} function. The
@code{truncate} and so transparently replaces the 32 bits interface.
@end deftypefun
-@comment unistd.h
-@comment POSIX
@deftypefun int ftruncate (int @var{fd}, off_t @var{length})
+@standards{POSIX, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This is like @code{truncate}, but it works on a file descriptor @var{fd}
@end deftypefun
-@comment unistd.h
-@comment Unix98
@deftypefun int ftruncate64 (int @var{id}, off64_t @var{length})
+@standards{Unix98, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c In the absence of a syscall, try ftruncate if length fits.
This function is similar to the @code{ftruncate} function. The
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 extended. Note that it is extended by a whole 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.
@end deftypefun
-@deftypefun int posix_fallocate64 (int @var{fd}, off64_t @var{length}, off64_t @var{offset})
+@deftypefun int posix_fallocate64 (int @var{fd}, off64_t @var{offset}, off64_t @var{length})
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function is a variant of @code{posix_fallocate64} which accepts
The prototype for @code{mknod} is declared in @file{sys/stat.h}.
@pindex sys/stat.h
-@comment sys/stat.h
-@comment BSD
@deftypefun int mknod (const char *@var{filename}, mode_t @var{mode}, dev_t @var{dev})
+@standards{BSD, sys/stat.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c Instead of issuing the syscall directly, we go through xmknod.
@c Although the internal xmknod takes a dev_t*, that could lead to
These facilities are declared in the header file @file{stdio.h}.
@pindex stdio.h
-@comment stdio.h
-@comment ISO
@deftypefun {FILE *} tmpfile (void)
+@standards{ISO, stdio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
@c The unsafety issues are those of fdopen, plus @acsfd because of the
@c open.
interface transparently replaces the old interface.
@end deftypefun
-@comment stdio.h
-@comment Unix98
@deftypefun {FILE *} tmpfile64 (void)
+@standards{Unix98, stdio.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@acsmem{} @acsfd{} @aculock{}}}
This function is similar to @code{tmpfile}, but the stream it returns a
pointer to was opened using @code{tmpfile64}. Therefore this stream can
and so transparently replaces the old interface.
@end deftypefun
-@comment stdio.h
-@comment ISO
@deftypefun {char *} tmpnam (char *@var{result})
+@standards{ISO, stdio.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:tmpnam/!result}}@asunsafe{}@acsafe{}}
@c The passed-in buffer should not be modified concurrently with the
@c call.
@code{tmpfile} or @code{mkstemp} is a safe way to avoid this problem.
@end deftypefun
-@comment stdio.h
-@comment GNU
@deftypefun {char *} tmpnam_r (char *@var{result})
+@standards{GNU, stdio.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function is nearly identical to the @code{tmpnam} function, except
that if @var{result} is a null pointer it returns a null pointer.
@code{tmpnam}.
@end deftypefun
-@comment stdio.h
-@comment ISO
@deftypevr Macro int L_tmpnam
+@standards{ISO, stdio.h}
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
-@comment ISO
@deftypevr Macro int TMP_MAX
+@standards{ISO, stdio.h}
The macro @code{TMP_MAX} is a lower bound for how many temporary names
you can create with @code{tmpnam}. You can rely on being able to call
@code{tmpnam} at least this many times before it might fail saying you
never less than @code{25}.
@end deftypevr
-@comment stdio.h
-@comment SVID
@deftypefun {char *} tempnam (const char *@var{dir}, const char *@var{prefix})
+@standards{SVID, stdio.h}
@safety{@prelim{}@mtsafe{@mtsenv{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
@c There's no way (short of being setuid) to avoid getenv("TMPDIR"),
@c even with a non-NULL dir.
@end deftypefun
@cindex TMPDIR environment variable
-@comment stdio.h
-@comment SVID
@c !!! are we putting SVID/GNU/POSIX.1/BSD in here or not??
@deftypevr {SVID Macro} {char *} P_tmpdir
+@standards{SVID, stdio.h}
This macro is the name of the default directory for temporary files.
@end deftypevr
string. These functions are declared in the header file @file{stdlib.h}.
@pindex stdlib.h
-@comment stdlib.h
-@comment Unix
@deftypefun {char *} mktemp (char *@var{template})
+@standards{Unix, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c __gen_tempname (caller tmpl, __GT_NOCREATE) ok
The @code{mktemp} function generates a unique file name by modifying
@code{mkstemp} is a safe way to avoid this problem.
@end deftypefun
-@comment stdlib.h
-@comment BSD
@deftypefun int mkstemp (char *@var{template})
+@standards{BSD, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{@acsfd{}}}
@c __gen_tempname (caller tmpl, __GT_FILE) ok
The @code{mkstemp} function generates a unique file name just as
@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
@deftypefun {char *} mkdtemp (char *@var{template})
+@standards{BSD, stdlib.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c __gen_tempname (caller tmpl, __GT_DIR) ok
The @code{mkdtemp} function creates a directory with a unique name. If
@samp{XXXXXX}.
If @code{mkdtemp} cannot create an uniquely named directory, it returns
-@code{NULL} and sets @var{errno} appropriately. If @var{template} does
+@code{NULL} and sets @code{errno} appropriately. If @var{template} does
not end with @samp{XXXXXX}, @code{mkdtemp} returns @code{NULL} and does
-not modify @var{template}. @var{errno} will be set to @code{EINVAL} in
+not modify @var{template}. @code{errno} will be set to @code{EINVAL} in
this case.
The directory is created using mode @code{0700}.
@c fchownat
@c futimesat
@c fstatat (there's a commented-out safety assessment for this one)
-@c linkat
+@c statx
@c mkdirat
@c mkfifoat
@c name_to_handle_at
@c open_by_handle_at
@c readlinkat
@c renameat
+@c renameat2
@c scandirat
@c symlinkat
@c unlinkat
projects / thirdparty / glibc.git / blobdiff