Lines Matching refs:code
45 using the @code{getpwuid} or @code{getpwnam} functions; see @ref{User
49 @code{cd}. The functions described in this section are the primitives
79 The @code{getcwd} function returns an absolute file name representing
85 null pointer for the @var{buffer} argument. Then @code{getcwd}
86 allocates a buffer automatically, as with @code{malloc}
92 The following @code{errno} error conditions are defined for this function:
94 @table @code
107 You could implement the behavior of GNU's @w{@code{getcwd (NULL, 0)}}
108 using only the standard behavior of @code{getcwd}:
130 @xref{Malloc Examples}, for information about @code{xmalloc}, which is
139 This is similar to @code{getcwd}, but has no way to specify the size of
140 the buffer. @Theglibc{} provides @code{getwd} only
144 @code{PATH_MAX} bytes long (@pxref{Limits for Files}). On @gnuhurdsystems{}
156 The @code{get_current_dir_name} function is basically equivalent to
157 @w{@code{getcwd (NULL, 0)}}, except the value of the @env{PWD}
162 the value returned by @code{getcwd} would resolve the symbolic links
174 The normal, successful return value from @code{chdir} is @code{0}. A
175 value of @code{-1} is returned to indicate an error. The @code{errno}
177 syntax errors (@pxref{File Name Errors}), plus @code{ENOTDIR} if the
187 The normal, successful return value from @code{fchdir} is @code{0}. A
188 value of @code{-1} is returned to indicate an error. The following
189 @code{errno} error conditions are defined for this function:
191 @table @code
193 Read permission is denied for the directory named by @code{dirname}.
221 The @code{opendir} function opens a @dfn{directory stream} whose
222 elements are directory entries. Alternatively @code{fdopendir} can be
225 allows, for instance, to pass the @code{O_NOATIME} flag to
226 @code{open}.
228 You use the @code{readdir} function on the directory stream to
229 retrieve these entries, represented as @w{@code{struct dirent}}
231 @code{d_name} member of this structure. There are obvious parallels
261 @table @code
268 refer to this member as @code{d_ino}. On @gnulinuxhurdsystems{} and most POSIX
269 systems, for most files this the same as the @code{st_ino} member that
270 @code{stat} will return for the file. @xref{File Attributes}.
274 null character. Its type is @code{unsigned char} because that is the
276 The symbol @code{_DIRENT_HAVE_D_NAMLEN} is defined if this member is
283 @vtable @code
310 This member is a BSD extension. The symbol @code{_DIRENT_HAVE_D_TYPE}
312 corresponds to the file type bits in the @code{st_mode} member of
313 @code{struct stat}. If the value cannot be determined the member
314 value is DT_UNKNOWN. These two macros convert between @code{d_type}
315 values and @code{st_mode} values:
320 This returns the @code{d_type} value corresponding to @var{mode}.
326 This returns the @code{st_mode} value corresponding to @var{dtype}.
332 macro named @code{_DIRENT_HAVE_D_@var{xxx}} where @var{xxx} is replaced
333 by the name of the new member. For instance, the member @code{d_reclen}
335 @code{_DIRENT_HAVE_D_RECLEN}.
339 single file is that they have the same value for the @code{d_fileno}
356 The @code{DIR} data type represents a directory stream.
359 You shouldn't ever allocate objects of the @code{struct dirent} or
360 @code{DIR} data types, since the directory access functions do that for
373 The @code{opendir} function opens and returns a directory stream for
375 type @code{DIR *}.
377 If unsuccessful, @code{opendir} returns a null pointer. In addition to
379 following @code{errno} error conditions are defined for this function:
381 @table @code
383 Read permission is denied for the directory named by @code{dirname}.
397 The @code{DIR} type is typically implemented using a file descriptor,
398 and the @code{opendir} function in terms of the @code{open} function.
400 file descriptors are closed on @code{exec} (@pxref{Executing a File}).
403 The directory which is opened for reading by @code{opendir} is
405 Or the way @code{opendir} implicitly creates a file descriptor for the
413 The @code{fdopendir} function works just like @code{opendir} but
422 If the @code{fdopendir} call returns successfully the file descriptor
424 way the descriptor implicitly created by @code{opendir} can be used
429 @code{errno} error conditions are defined for this function:
431 @table @code
447 descriptor which is created by the @code{opendir} call. For instance,
449 @code{fchdir} function could be used. Historically the @code{DIR} type
457 The function @code{dirfd} returns the file descriptor associated with
459 the directory is closed with @code{closedir}. If the directory stream
461 @code{-1}.
485 @strong{Portability Note:} On some systems @code{readdir} may not
490 @code{readdir} returns a null pointer. The following @code{errno} error
493 @table @code
499 must set @code{errno} to zero before calling @code{readdir}. To avoid
503 @strong{Caution:} The pointer returned by @code{readdir} points to
504 a buffer within the @code{DIR} object. The data in that buffer will
505 be overwritten by the next call to @code{readdir}. You must take care,
506 for instance, to copy the @code{d_name} string if you need it later.
508 Because of this, it is not safe to share a @code{DIR} object among
510 no thread calls @code{readdir} while another thread is still using the
512 @code{readdir} from multiple threads as long as each thread uses
513 its own @code{DIR} object. POSIX.1-2008 does not require this to
517 @code{readdir_r} allows you to provide your own buffer for the
518 @code{struct dirent}, but it is less portable than @code{readdir}, and
520 you use @code{readdir}, but do not share @code{DIR} objects.
526 This function is a version of @code{readdir} which performs internal
527 locking. Like @code{readdir} it returns the next entry from the
531 @strong{Portability Note:} @code{readdir_r} is deprecated. It is
532 recommended to use @code{readdir} instead of @code{readdir_r} for the
537 On systems which do not define @code{NAME_MAX}, it may not be possible
538 to use @code{readdir_r} safely because the caller does not specify the
542 On some systems, @code{readdir_r} cannot read directory entries with
544 implementation of @code{readdir_r} returns with an error code of
545 @code{ENAMETOOLONG} after the final directory entry has been read. On
546 other systems, @code{readdir_r} may return successfully, but the
547 @code{d_name} member may not be NUL-terminated or may be truncated.
550 POSIX-1.2008 does not guarantee that @code{readdir} is thread-safe,
553 @code{readdir} concurrently on different @var{dirstream}s, so there is
554 no need to use @code{readdir_r} in most multi-threaded programs. In
556 @var{dirstream}, it is still better to use @code{readdir} and external
561 @code{readdir_r} and mandate the level of thread safety for
562 @code{readdir} which is provided by @theglibc{} and other
566 Normally @code{readdir_r} returns zero and sets @code{*@var{result}}
568 error is detected, @code{readdir_r} sets @code{*@var{result}} to a
569 null pointer and returns a nonzero error code, also stored in
570 @code{errno}, as described for @code{readdir}.
572 It is also important to look at the definition of the @code{struct
574 the second parameter of @code{readdir_r} might not be enough. Some
575 systems don't define the @code{d_name} element sufficiently long. In
577 for at least @code{NAME_MAX + 1} characters in the @code{d_name} array.
578 Code to call @code{readdir_r} could look like this:
598 The @code{readdir64} function is just like the @code{readdir} function
599 except that it returns a pointer to a record of type @code{struct
600 dirent64}. Some of the members of this data type (notably @code{d_ino})
603 In all other aspects this function is equivalent to @code{readdir}.
609 The deprecated @code{readdir64_r} function is equivalent to the
610 @code{readdir_r} function except that it takes parameters of base type
611 @code{struct dirent64} instead of @code{struct dirent} in the second and
613 @code{readdir_r} also apply here.
623 @code{0} on success and @code{-1} on failure.
625 The following @code{errno} error conditions are defined for this
628 @table @code
661 The @code{rewinddir} function is used to reinitialize the directory
662 stream @var{dirstream}, so that if you call @code{readdir} it
665 directory since it was opened with @code{opendir}. (Entries for these
666 files might or might not be returned by @code{readdir} if they were
667 added or removed since you last called @code{opendir} or
668 @code{rewinddir}.)
677 The @code{telldir} function returns the file position of the directory
678 stream @var{dirstream}. You can use this value with @code{seekdir} to
688 The @code{seekdir} function sets the file position of the directory
690 result of a previous call to @code{telldir} on this particular stream;
692 @code{telldir}.
700 @code{scandir} function. With its help one can select a subset of the
721 The @code{scandir} function scans the contents of the directory selected
723 structures of type @code{struct dirent} which describe all selected
724 directory entries and which is allocated using @code{malloc}. Instead
732 function are of type @code{struct dirent **}, therefore one cannot
733 directly use the @code{strcmp} or @code{strcoll} functions; instead see
734 the functions @code{alphasort} and @code{versionsort} below.
737 *@var{namelist}. If it is @code{-1} an error occurred (either the
739 the global variable @code{errno} contains more information on the error.
742 As described above, the fourth argument to the @code{scandir} function
752 The @code{alphasort} function behaves like the @code{strcoll} function
755 @code{struct dirent **}.
757 The return value of @code{alphasort} is less than, equal to, or greater
766 The @code{versionsort} function is like @code{alphasort} except that it
767 uses the @code{strverscmp} function internally.
770 If the filesystem supports large files we cannot use the @code{scandir}
771 anymore since the @code{dirent} structure might not able to contain all
772 the information. The LFS provides the new type @w{@code{struct
779 The @code{scandir64} function works like the @code{scandir} function
781 of type @w{@code{struct dirent64}}. The function pointed to by
784 @w{@code{struct dirent64 *}} parameter.
787 of type @code{struct dirent64 **}.
791 @code{alphasort} and @code{versionsort} cannot be supplied for that
798 The @code{alphasort64} function behaves like the @code{strcoll} function
801 @code{struct dirent64 **}.
803 Return value of @code{alphasort64} is less than, equal to, or greater
811 The @code{versionsort64} function is like @code{alphasort64}, excepted that it
812 uses the @code{strverscmp} function internally.
815 It is important not to mix the use of @code{scandir} and the 64-bit
823 (@pxref{Simple Directory Lister}). Using the @code{scandir} function we
832 all directory entries we always return @code{1}.
838 used after @code{vfork}. @xref{POSIX Safety Concepts}. The functions
842 @code{open} function, with or without the @code{O_DIRECTORY} flag.
848 The @code{getdents64} function reads at most @var{length} bytes of
854 directory stream. On error, the function returns @code{-1} and sets
855 @code{errno} to the appropriate error code.
857 The data is stored as a sequence of @code{struct dirent64} records,
858 which can be traversed using the @code{d_reclen} member. The buffer
861 @code{NAME_MAX} bytes (e.g., because they support up to 255 Unicode
876 process all the files as a group (see @code{scandir}). Sometimes it is
884 There are four functions in this family: @code{ftw}, @code{nftw} and
885 their 64-bit counterparts @code{ftw64} and @code{nftw64}. These
896 The type of callback functions given to the @code{ftw} function. The
898 object of type @code{struct stat} which is filled in for the file named
905 @vtable @code
912 The @code{stat} call failed and so the information pointed to by the
918 seeing this value in a @code{ftw} callback function means the referenced
919 file does not exist. The situation for @code{nftw} is different.
922 @code{_XOPEN_EXTENDED} defined before including
926 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
927 type is in fact @code{__ftw64_func_t} since this mode changes
928 @code{struct stat} to be @code{struct stat64}.
931 For the LFS interface and for use in the function @code{ftw64}, the
941 This type is used just like @code{__ftw_func_t} for the callback
942 function, but this time is called from @code{ftw64}. The second
944 @code{struct stat64} which is able to represent the larger values.
954 The first three arguments are the same as for the @code{__ftw_func_t}
957 @vtable @code
960 visited and reported. This flag is returned instead of @code{FTW_D} if
961 the @code{FTW_DEPTH} flag is passed to @code{nftw} (see below).
970 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
971 type is in fact @code{__nftw64_func_t} since this mode changes
972 @code{struct stat} to be @code{struct stat64}.
976 available which has to be used with the @code{nftw64} function.
985 This type is used just like @code{__nftw_func_t} for the callback
986 function, but this time is called from @code{nftw64}. The second
988 @code{struct stat64} which is able to represent the larger values.
997 @table @code
1002 important if the @code{FTW_CHDIR} flag was set in calling @code{nftw}
1006 Whilst processing, the code tracks how many directories down it has gone
1018 The @code{ftw} function calls the callback function given in the
1028 use this parameter to access the file. @code{ftw} also calls
1029 @code{stat} for the file and passes that information on to the callback
1030 function. If this @code{stat} call is not successful the failure is
1032 @code{FTW_NS}. Otherwise it is set according to the description given
1033 in the account of @code{__ftw_func_t} above.
1037 occurred in the callback function or it wants @code{ftw} to return
1040 program must not use @code{setjmp} or similar techniques to continue
1042 @code{ftw} function unfreed.
1044 The @var{descriptors} parameter to @code{ftw} specifies how many file
1053 The return value of the @code{ftw} function is @math{0} if all callback
1055 @code{ftw} succeeded. If a function call failed (other than calling
1056 @code{stat} on an item) the function returns @math{-1}. If a callback
1058 the return value of @code{ftw}.
1060 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
1061 32-bit system this function is in fact @code{ftw64}, i.e., the LFS
1068 This function is similar to @code{ftw} but it can work on filesystems
1070 @code{struct stat64} which is passed by reference to the callback
1073 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
1074 32-bit system this function is available under the name @code{ftw} and
1091 The @code{nftw} function works like the @code{ftw} functions. They call
1094 are consumed during the @code{nftw} call.
1097 is of type @w{@code{struct FTW *}} and provides the callback function
1100 A second difference is that @code{nftw} takes a fourth argument, which
1103 @vtable @code
1106 symbolic links are reported using the @code{FTW_SL} value for the type
1108 symbolic link does not exist @code{FTW_SLN} is returned instead.
1112 parameter to @code{nftw}.
1116 When @code{ntfw} finally returns the current directory is restored to
1122 callback function is @code{FTW_DP} and not @code{FTW_D}.
1125 are handled differently. If the callback returns @code{FTW_CONTINUE},
1126 walking continues normally. @code{FTW_STOP} means walking stops
1127 and @code{FTW_STOP} is returned to the caller. If @code{FTW_SKIP_SUBTREE}
1128 is returned by the callback with @code{FTW_D} argument, the subtree
1130 If @code{FTW_SKIP_SIBLINGS} is returned by the callback, all siblings
1136 The return value is computed in the same way as for @code{ftw}.
1137 @code{nftw} returns @math{0} if no failures occurred and all callback
1139 problems, the return value is @math{-1} and @code{errno} is set
1143 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
1144 32-bit system this function is in fact @code{nftw64}, i.e., the LFS
1151 This function is similar to @code{nftw} but it can work on filesystems
1153 @code{struct stat64} which is passed by reference to the callback
1156 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
1157 32-bit system this function is available under the name @code{nftw} and
1173 To add a name to a file, use the @code{link} function. (The new name is
1183 same file in multiple file systems. @code{link} reports an error if you
1187 The prototype for the @code{link} function is declared in the header
1194 The @code{link} function makes a new link to the existing file named by
1197 This function returns a value of @code{0} if it is successful and
1198 @code{-1} on failure. In addition to the usual file name errors
1200 following @code{errno} error conditions are defined for this function:
1202 @table @code
1217 (The maximum number of links to a file is @w{@code{LINK_MAX}}; see
1251 The @code{linkat} function is analogous to the @code{link} function,
1255 file descriptor. The special file descriptor @code{AT_FDCWD} denotes
1260 @table @code
1263 symbolic link, @code{linkat} follows the symbolic link and creates a
1266 @code{linkat} can fail in this case.
1271 is created, which may have been opened with @code{O_PATH} or
1272 @code{O_TMPFILE}. This flag is a GNU extension.
1294 happen when you try to open the link. The @code{open} function realizes
1296 the link, and opens that file name instead. The @code{stat} function
1301 operate on the link itself. The functions @code{readlink} and
1302 @code{lstat} also refrain from following symbolic links, because their
1303 purpose is to obtain information about the link. @code{link}, the
1314 The macro @code{MAXSYMLINKS} specifies how many symlinks some function
1315 will follow before returning @code{ELOOP}. Not all functions behave the
1317 @code{_SC_SYMLOOP} by @code{sysconf}. In fact, the @code{sysconf}
1319 @code{MAXSYMLINKS} exists and has a finite value.
1329 The @code{symlink} function makes a symbolic link to @var{oldname} named
1332 The normal return value from @code{symlink} is @code{0}. A return value
1333 of @code{-1} indicates an error. In addition to the usual file name
1334 syntax errors (@pxref{File Name Errors}), the following @code{errno}
1337 @table @code
1366 The @code{readlink} function gets the value of the symbolic link
1369 @code{readlink} normally returns the number of characters copied. The
1375 call @code{readlink} again. Here is an example:
1401 A value of @code{-1} is returned in case of error. In addition to the
1403 @code{errno} error conditions are defined for this function:
1405 @table @code
1418 and no filename in the path is @code{.} or @code{..}. This is for
1427 The @code{canonicalize_file_name} function returns the absolute name of
1428 the file named by @var{name} which contains no @code{.}, @code{..}
1429 components nor any repeated path separators (@code{/}) or symlinks. The
1431 memory allocated with @code{malloc}. If the result is not used anymore
1432 the memory should be freed with a call to @code{free}.
1436 reaches or exceeds @code{PATH_MAX} characters. In any case
1437 @code{errno} is set accordingly.
1439 @table @code
1454 More than @code{MAXSYMLINKS} many symlinks have been followed.
1461 @code{canonicalize_file_name} in that the user has to provide the buffer
1469 A call to @code{realpath} where the @var{resolved} parameter is
1470 @code{NULL} behaves exactly like @code{canonicalize_file_name}. The
1472 it. If @var{resolved} is not @code{NULL} it points to a buffer into
1475 @code{PATH_MAX} this means the buffer must be large enough for a
1478 @code{realpath} with anything but @code{NULL} for the second parameter.
1482 readable if the function returns @code{NULL} and @code{errno} is set to
1483 @code{EACCES} or @code{ENOENT}.
1498 You can delete a file with @code{unlink} or @code{remove}.
1507 The @code{unlink} function deletes the file name @var{filename}. If
1513 The function @code{unlink} is declared in the header file @file{unistd.h}.
1515 This function returns @code{0} on successful completion, and @code{-1}
1517 (@pxref{File Name Errors}), the following @code{errno} error conditions are
1520 @table @code
1535 On some systems @code{unlink} cannot be used to delete the name of a
1537 To avoid such problems, use @code{rmdir} to delete directories. (On
1538 @gnulinuxhurdsystems{} @code{unlink} can never delete the name of a directory.)
1551 The @code{rmdir} function deletes a directory. The directory must be
1555 In most other respects, @code{rmdir} behaves like @code{unlink}. There
1556 are two additional @code{errno} error conditions defined for
1557 @code{rmdir}:
1559 @table @code
1566 the other. @gnulinuxhurdsystems{} always use @code{ENOTEMPTY}.
1578 @code{unlink} for files and like @code{rmdir} for directories.
1579 @code{remove} is declared in @file{stdio.h}.
1586 The @code{rename} function is used to change a file's name.
1595 The @code{rename} function renames the file @var{oldname} to
1604 One special case for @code{rename} is when @var{oldname} and
1607 POSIX requires that @code{rename} do nothing and report success---which
1612 @var{newname} is the name of a directory, @code{rename} fails in this
1619 @code{oldname} which is being renamed.
1621 One useful feature of @code{rename} is that the meaning of @var{newname}
1629 If @code{rename} fails, it returns @code{-1}. In addition to the usual
1631 @code{errno} error conditions are defined for this function:
1633 @table @code
1648 @code{ENOTEMPTY} for this, but some other systems return @code{EEXIST}.
1683 Directories are created with the @code{mkdir} function. (There is also
1684 a shell command @code{mkdir} which does the same thing.)
1690 The @code{mkdir} function creates a new, empty directory with name
1697 A return value of @code{0} indicates successful completion, and
1698 @code{-1} indicates failure. In addition to the usual file name syntax
1699 errors (@pxref{File Name Errors}), the following @code{errno} error
1702 @table @code
1770 called @code{struct stat}. This section describes the names of the
1780 The @code{stat} structure type is used to return information about the
1783 @table @code
1794 Identifies the device containing the file. The @code{st_ino} and
1795 @code{st_dev}, taken together, uniquely identify the file. The
1796 @code{st_dev} value is not necessarily consistent across reboots or
1852 value with @code{st_size}, like this:
1865 writing the file. (This is unrelated to @code{st_blocks}.)
1871 Therefore a new definition of @code{struct stat} is necessary.
1876 in @code{struct stat}. The only difference is that the members
1877 @code{st_ino}, @code{st_size}, and @code{st_blocks} have a different
1880 @table @code
1891 Identifies the device containing the file. The @code{st_ino} and
1892 @code{st_dev}, taken together, uniquely identify the file. The
1893 @code{st_dev} value is not necessarily consistent across reboots or
1945 writing the file. (This is unrelated to @code{st_blocks}.)
1958 @theglibc{}, this is an unsigned type no narrower than @code{unsigned
1967 In @theglibc{}, this type is no narrower than @code{unsigned int}.
1969 If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
1970 is transparently replaced by @code{ino64_t}.
1977 @code{unsigned int}.
1979 When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
1980 available under the name @code{ino_t}.
1986 In @theglibc{}, this is an integer type no narrower than @code{int}.
1997 In @theglibc{}, this type is no narrower than @code{int}.
1999 If the source is compiled with @code{_FILE_OFFSET_BITS == 64} this type
2000 is transparently replaced by @code{blkcnt64_t}.
2006 use in LFS. In @theglibc{}, this type is no narrower than @code{int}.
2008 When compiling with @code{_FILE_OFFSET_BITS == 64} this type is
2009 available under the name @code{blkcnt_t}.
2015 To examine the attributes of files, use the functions @code{stat},
2016 @code{fstat} and @code{lstat}. They return the attribute information in
2017 a @code{struct stat} object. All three functions are declared in the
2023 The @code{stat} function returns information about the attributes of the
2028 nonexistent file name, then @code{stat} fails reporting a nonexistent
2031 The return value is @code{0} if the operation is successful, or
2032 @code{-1} on failure. In addition to the usual file name errors
2033 (@pxref{File Name Errors}, the following @code{errno} error conditions
2036 @table @code
2041 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2042 function is in fact @code{stat64} since the LFS interface transparently
2049 This function is similar to @code{stat} but it is also able to work on
2051 this the result is stored in a variable of type @code{struct stat64} to
2054 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2055 function is available under the name @code{stat} and so transparently
2062 The @code{fstat} function is like @code{stat}, except that it takes an
2066 Like @code{stat}, @code{fstat} returns @code{0} on success and @code{-1}
2067 on failure. The following @code{errno} error conditions are defined for
2068 @code{fstat}:
2070 @table @code
2075 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2076 function is in fact @code{fstat64} since the LFS interface transparently
2083 This function is similar to @code{fstat} but is able to work on large
2085 @var{filedes} should be obtained by @code{open64} or @code{creat64}.
2086 The @var{buf} pointer points to a variable of type @code{struct stat64}
2089 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2090 function is available under the name @code{fstat} and so transparently
2103 The @code{lstat} function is like @code{stat}, except that it does not
2105 link, @code{lstat} returns information about the link itself; otherwise
2106 @code{lstat} works like @code{stat}. @xref{Symbolic Links}.
2108 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2109 function is in fact @code{lstat64} since the LFS interface transparently
2118 This function is similar to @code{lstat} but it is also able to work on
2120 this the result is stored in a variable of type @code{struct stat64} to
2123 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} this
2124 function is available under the name @code{lstat} and so transparently
2131 The @dfn{file mode}, stored in the @code{st_mode} field of the file
2132 attributes, contains two kinds of information: the file type code, and
2133 the access permission bits. This section discusses only the type code,
2142 just the file type code, and compare this against constants for each of
2150 @var{m} which is the @code{st_mode} field returned by @code{stat} on
2201 @code{S_IFMT} to extract the file type code, and compared to the
2217 This is a bit mask used to extract the file type code from a mode value.
2222 @vtable @code
2257 @code{st_mode} field as the parameter. Instead they expect a pointer to
2258 the whole @code{struct stat} structure.
2314 the @code{chown} function. This is the primitive for the @code{chown}
2315 and @code{chgrp} shell commands.
2323 The @code{chown} function changes the owner of the file @var{filename} to
2331 The return value is @code{0} on success and @code{-1} on failure.
2333 the following @code{errno} error conditions are defined for this function:
2335 @table @code
2347 @code{_POSIX_CHOWN_RESTRICTED} macro.
2357 This is like @code{chown}, except that it changes the owner of the open
2360 The return value from @code{fchown} is @code{0} on success and @code{-1}
2361 on failure. The following @code{errno} error codes are defined for this
2364 @table @code
2374 see @code{chmod} above.
2384 The @dfn{file mode}, stored in the @code{st_mode} field of the file
2385 attributes, contains two kinds of information: the file type code, and
2388 @xref{Testing File Type}, for information about the file type code.
2398 @vtable @code
2404 is 0400. @code{S_IREAD} is an obsolete synonym provided for BSD
2412 @w{@code{S_IWRITE}} is an obsolete synonym provided for BSD compatibility.
2419 for the owner of the file. Usually 0100. @code{S_IEXEC} is an obsolete
2498 If you try, @code{chmod} fails with @code{EFTYPE};
2513 them). Therefore one has to use the @code{_GNU_SOURCE} feature select
2557 The primitive functions for creating files (for example, @code{open} or
2558 @code{mkdir}) take a @var{mode} argument, which specifies the file
2579 @code{chmod}. This function uses the specified permission bits and
2584 shell (using the @code{umask} shell command), and inherited by all
2590 access permissions, the easiest way to do this is to use @code{fchmod}
2593 @code{umask} function.
2601 The @code{umask} function sets the file creation mask of the current
2605 Here is an example showing how to read the mask with @code{umask}
2619 However, on @gnuhurdsystems{} it is better to use @code{getumask} if
2634 The @code{chmod} function sets the access permission bits for the file
2637 If @var{filename} is a symbolic link, @code{chmod} changes the
2641 This function returns @code{0} if successful and @code{-1} if not. In
2643 Errors}), the following @code{errno} error conditions are defined for
2646 @table @code
2659 @var{mode} has the @code{S_ISVTX} bit (the ``sticky bit'') set,
2664 You only get @code{EFTYPE} on systems where the sticky bit has no useful
2666 bit in @var{mode} and call @code{chmod} again. @xref{Permission Bits},
2674 This is like @code{chmod}, except that it changes the permissions of the
2677 The return value from @code{fchmod} is @code{0} on success and @code{-1}
2678 on failure. The following @code{errno} error codes are defined for this
2681 @table @code
2712 owned by @code{root} and the setuid-bit must be set.
2720 To do this, use the function @code{access}, which checks for access
2731 have. Using @code{access} is simple and automatically does whatever is
2734 @code{access} is @emph{only} appropriate to use in setuid programs.
2744 The @code{access} function checks to see whether the file named by
2747 flags @code{R_OK}, @code{W_OK}, @code{X_OK}, or the existence test
2748 @code{F_OK}.
2752 permission. As a result, if you use the function from a @code{setuid}
2753 or @code{setgid} program (@pxref{How Change Persona}), it gives
2756 The return value is @code{0} if the access is permitted, and @code{-1}
2758 @code{access} returns true if the requested access is @emph{denied}.)
2761 Errors}), the following @code{errno} error conditions are defined for
2764 @table @code
2777 as the @var{how} argument to the @code{access} function. The values
2809 correspond to the @code{st_atime}, @code{st_mtime}, and @code{st_ctime}
2810 members of the @code{stat} structure; see @ref{File Attributes}.
2813 @code{time_t} objects. This data type is defined in @file{time.h}.
2824 Adding a new name for a file with the @code{link} function updates the
2828 is deleted with @code{unlink}, @code{remove} or @code{rmdir}. Renaming
2829 a file with @code{rename} affects only the attribute change time and
2833 Changing the attributes of a file (for example, with @code{chmod})
2837 the @code{utime} function---all except the attribute change time. You
2843 The @code{utimbuf} structure is used with the @code{utime} function to
2847 @table @code
2866 values from the @code{actime} and @code{modtime} members (respectively)
2867 of the @code{utimbuf} structure pointed to by @var{times}.
2873 The @code{utime} function returns @code{0} if successful and @code{-1}
2875 (@pxref{File Name Errors}), the following @code{errno} error conditions
2878 @table @code
2899 @code{st_atime_usec}, @code{st_mtime_usec}, and @code{st_ctime_usec};
2901 microseconds. They correspond to the @code{tv_usec} field of a
2902 @code{timeval} structure; see @ref{Time Types}.
2904 The @code{utimes} function is like @code{utime}, but also lets you specify
2917 @code{@var{tvp}[0]}, and the new modification time by
2918 @code{@var{tvp}[1]}. Similar to @code{utime}, if @var{tvp} is a null
2922 The return values and error conditions are the same as for the @code{utime}
2931 This function is like @code{utimes}, except that it does not follow
2933 @code{lutimes} sets the file access and modification times of the
2934 symbolic link special file itself (as seen by @code{lstat};
2935 @pxref{Symbolic Links}) while @code{utimes} sets the file access and
2938 not available, it will fail with @code{ENOSYS}).
2940 The return values and error conditions are the same as for the @code{utime}
2950 This function is like @code{utimes}, except that it takes an open file
2953 platforms (if not available, it will fail with @code{ENOSYS}).
2955 Like @code{utimes}, @code{futimes} returns @code{0} on success and @code{-1}
2956 on failure. The following @code{errno} error conditions are defined for
2957 @code{futimes}:
2959 @table @code
2984 @code{open} or @code{fopen} call.
2987 This can be done with the @code{truncate} and @code{ftruncate} functions.
2988 They were introduced in BSD Unix. @code{ftruncate} was later added to
2994 However, it is not portable but must be implemented if @code{mmap}
2995 allows mapping of files (i.e., @code{_POSIX_MAPPED_FILES} is defined).
3006 The @code{truncate} function changes the size of @var{filename} to
3014 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
3015 @code{truncate} function is in fact @code{truncate64} and the type
3016 @code{off_t} has 64 bits which makes it possible to handle files up to
3022 @table @code
3050 This function is similar to the @code{truncate} function. The
3055 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
3057 @code{truncate} and so transparently replaces the 32 bits interface.
3064 This is like @code{truncate}, but it works on a file descriptor @var{fd}
3070 The @code{ftruncate} function might simply leave the file alone and do
3072 case the extended area should be zero-filled. So using @code{ftruncate}
3077 @code{ftruncate} is especially useful in combination with @code{mmap}.
3083 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} the
3084 @code{ftruncate} function is in fact @code{ftruncate64} and the type
3085 @code{off_t} has 64 bits which makes it possible to handle files up to
3091 @table @code
3128 This function is similar to the @code{ftruncate} function. The
3133 When the source file is compiled with @code{_FILE_OFFSET_BITS == 64} on a
3135 @code{ftruncate} and so transparently replaces the 32 bits interface.
3138 As announced here is a little example of how to use @code{ftruncate} in
3139 combination with @code{mmap}:
3168 The function @code{add} writes a block of memory at an arbitrary
3171 is a requirement of @code{mmap}. The program has to keep track of the
3172 real size, and when it has finished a final @code{ftruncate} call should
3203 writes to memory-mapped regions created with @code{mmap} can still
3204 result in @code{SIGBUS}.
3209 @c @code{posix_fallocate} has a race with file extension (if
3217 @var{fd} must be a regular file opened for writing, or @code{EBADF} is
3219 request, @code{ENOSPC} is returned.
3221 @strong{Note:} If @code{fallocate} is not available (because the file
3222 system does not support it), @code{posix_fallocate} is emulated, which
3229 potentially rewritten. In contrast, with proper @code{fallocate}
3241 If @var{fd} has been opened with the @code{O_WRONLY} flag, the function
3242 will fail with an @code{errno} value of @code{EBADF}.
3245 If @var{fd} has been opened with the @code{O_APPEND} flag, the function
3246 will fail with an @code{errno} value of @code{EBADF}.
3249 If @var{length} is zero, @code{ftruncate} is used to increase the file
3251 race condition which means that @code{ftruncate} can accidentally
3257 application can use the Linux-specific @code{fallocate} function, with a
3258 zero flag argument. For the @code{fallocate} function, @theglibc{} does
3260 allocation. Instead, an @code{EOPNOTSUPP} is returned to the caller.
3267 This function is a variant of @code{posix_fallocate64} which accepts
3277 The @code{mknod} function is the primitive for making special files,
3281 The prototype for @code{mknod} is declared in @file{sys/stat.h}.
3290 The @code{mknod} function makes a special file with name @var{filename}.
3292 special file bits, such as @code{S_IFCHR} (for a character special file)
3293 or @code{S_IFBLK} (for a block special file). @xref{Testing File Type}.
3298 The return value is @code{0} on success and @code{-1} on error. In addition
3300 following @code{errno} error conditions are defined for this function:
3302 @table @code
3325 @code{tmpfile} function to open it. Or you can use the @code{tmpnam}
3326 (better: @code{tmpnam_r}) function to provide a name for a temporary
3327 file and then you can open it in the usual way with @code{fopen}.
3329 The @code{tempnam} function is like @code{tmpnam} but lets you choose
3332 is that @code{tempnam} is reentrant, while @code{tmpnam} is not since it
3355 calling @code{fopen} with mode @code{"wb+"}. The file is deleted
3362 When the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a
3363 32-bit system this function is in fact @code{tmpfile64}, i.e., the LFS
3370 This function is similar to @code{tmpfile}, but the stream it returns a
3371 pointer to was opened using @code{tmpfile64}. Therefore this stream can
3374 Please note that the return type is still @code{FILE *}. There is no
3375 special @code{FILE} type for the LFS interface.
3377 If the sources are compiled with @code{_FILE_OFFSET_BITS == 64} on a 32
3378 bits machine this function is available under the name @code{tmpfile}
3394 a pointer to an array of at least @code{L_tmpnam} characters, and the
3397 It is possible for @code{tmpnam} to fail if you call it too many times
3400 of different names. If @code{tmpnam} fails it returns a null pointer.
3404 name using @code{tmpnam}, leading to a possible security hole. The
3406 opening the file you should use the @code{O_EXCL} flag. Using
3407 @code{tmpfile} or @code{mkstemp} is a safe way to avoid this problem.
3413 This function is nearly identical to the @code{tmpnam} function, except
3417 @code{tmpnam} cannot happen here.
3420 @code{tmpnam}.
3427 generated by the @code{tmpnam} function.
3432 The macro @code{TMP_MAX} is a lower bound for how many temporary names
3433 you can create with @code{tmpnam}. You can rely on being able to call
3434 @code{tmpnam} at least this many times before it might fail saying you
3441 never less than @code{25}.
3456 allocated with @code{malloc}, so you should release its storage with
3457 @code{free} when it is no longer needed.
3467 The environment variable @code{TMPDIR}, if it is defined. For security
3474 The value of the @code{P_tmpdir} macro.
3484 name using @code{tempnam}, leading to a possible security hole. The
3486 opening the file you should use the @code{O_EXCL} flag. Using
3487 @code{tmpfile} or @code{mkstemp} is a safe way to avoid this problem.
3498 they used @code{mktemp} and @code{mkstemp}. Both of these functions
3505 @strong{NB:} Because @code{mktemp} and @code{mkstemp} modify the
3508 would crash when @code{mktemp} or @code{mkstemp} tried to modify the
3516 The @code{mktemp} function generates a unique file name by modifying
3518 @var{template} as modified. If @code{mktemp} cannot find a unique file
3520 @var{template} does not end with @samp{XXXXXX}, @code{mktemp} returns a
3525 name using @code{mktemp}, leading to a possible security hole. The
3527 opening the file you should use the @code{O_EXCL} flag. Using
3528 @code{mkstemp} is a safe way to avoid this problem.
3535 The @code{mkstemp} function generates a unique file name just as
3536 @code{mktemp} does, but it also opens the file for you with @code{open}
3539 for reading and writing. If @code{mkstemp} cannot create a
3540 uniquely-named file, it returns @code{-1}. If @var{template} does not
3541 end with @samp{XXXXXX}, @code{mkstemp} returns @code{-1} and does not
3544 The file is opened using mode @code{0600}. If the file is meant to be
3548 Unlike @code{mktemp}, @code{mkstemp} is actually guaranteed to create a
3551 @code{open} with the @code{O_EXCL} flag, which says you want to create a
3558 The @code{mkdtemp} function creates a directory with a unique name. If
3560 directory, and returns @var{template}. As with @code{mktemp} and
3561 @code{mkstemp}, @var{template} should be a string ending with
3564 If @code{mkdtemp} cannot create an uniquely named directory, it returns
3565 @code{NULL} and sets @code{errno} appropriately. If @var{template} does
3566 not end with @samp{XXXXXX}, @code{mkdtemp} returns @code{NULL} and does
3567 not modify @var{template}. @code{errno} will be set to @code{EINVAL} in
3570 The directory is created using mode @code{0700}.
3573 The directory created by @code{mkdtemp} cannot clash with temporary
3575 creation always works like @code{open} with @code{O_EXCL}.
3578 The @code{mkdtemp} function comes from OpenBSD.