diff options
Diffstat (limited to 'man0p/sys_stat.h.0p')
| -rw-r--r-- | man0p/sys_stat.h.0p | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/man0p/sys_stat.h.0p b/man0p/sys_stat.h.0p new file mode 100644 index 000000000..40990938e --- /dev/null +++ b/man0p/sys_stat.h.0p @@ -0,0 +1,355 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "<sys/stat.h>" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" <sys/stat.h> +.SH NAME +sys/stat.h \- data returned by the stat() function +.SH SYNOPSIS +.LP +\fB#include <sys/stat.h>\fP +.SH DESCRIPTION +.LP +The \fI<sys/stat.h>\fP header shall define the structure of the data +returned by the functions \fIfstat\fP(), \fIlstat\fP(), and \fIstat\fP(). +.LP +The \fBstat\fP structure shall contain at least the following members: +.sp +.RS +.nf + +\fBdev_t st_dev \fP Device ID of device containing file. \fB +ino_t st_ino \fP File serial number. \fB +mode_t st_mode \fP Mode of file (see below). \fB +nlink_t st_nlink \fP Number of hard links to the file. \fB +uid_t st_uid \fP User ID of file. \fB +gid_t st_gid \fP Group ID of file. \fB + +dev_t st_rdev \fP Device ID (if file is character or block special). \fB + +off_t st_size \fP For regular files, the file size in bytes. \fB + \fP For symbolic links, the length in bytes of the \fB + \fP pathname contained in the symbolic link. \fB + + \fP For a shared memory object, the length in bytes. \fB + + + \fP For a typed memory object, the length in bytes. \fB + + \fP For other file types, the use of this field is \fB + \fP unspecified. \fB +time_t st_atime \fP Time of last access. \fB +time_t st_mtime \fP Time of last data modification. \fB +time_t st_ctime \fP Time of last status change. \fB + +blksize_t st_blksize\fP A file system-specific preferred I/O block size for \fB + \fP this object. In some file system types, this may \fB + \fP vary from file to file. \fB +blkcnt_t st_blocks \fP Number of blocks allocated for this object. \fB + +\fP +.fi +.RE +.LP +The \fIst_ino\fP and \fIst_dev\fP fields taken together uniquely identify +the file within the system. The \fBblkcnt_t\fP, +\fBblksize_t\fP, \fBdev_t\fP, \fBino_t\fP, \fBmode_t\fP, \fBnlink_t\fP, +\fBuid_t\fP, \fBgid_t\fP, \fBoff_t\fP, and +\fBtime_t\fP types shall be defined as described in \fI<sys/types.h>\fP +\&. Times +shall be given in seconds since the Epoch. +.LP +Unless otherwise specified, the structure members \fIst_mode\fP, \fIst_ino\fP, +\fIst_dev\fP, \fIst_uid\fP, \fIst_gid\fP, +\fIst_atime\fP, \fIst_ctime\fP, and \fIst_mtime\fP shall have meaningful +values for all file types defined in +IEEE\ Std\ 1003.1-2001. +.LP +For symbolic links, the \fIst_mode\fP member shall contain meaningful +information, which can be used with the file type macros +described below, that take a \fImode\fP argument. The \fIst_size\fP +member shall contain the length, in bytes, of the pathname +contained in the symbolic link. File mode bits and the contents of +the remaining members of the \fBstat\fP structure are +unspecified. The value returned in the \fIst_size\fP field shall be +the length of the contents of the symbolic link, and shall not +count a trailing null if one is present. +.LP +The following symbolic names for the values of type \fBmode_t\fP shall +also be defined. +.LP +File type: +.TP 7 +S_IFMT +Type of file. +.TP 7 +S_IFBLK +.RS +Block special. +.RE +.TP 7 +S_IFCHR +.RS +Character special. +.RE +.TP 7 +S_IFIFO +.RS +FIFO special. +.RE +.TP 7 +S_IFREG +.RS +Regular. +.RE +.TP 7 +S_IFDIR +.RS +Directory. +.RE +.TP 7 +S_IFLNK +.RS +Symbolic link. +.RE +.TP 7 +S_IFSOCK +.RS +Socket. +.RE +.sp +.sp +.LP +File mode bits: +.TP 7 +S_IRWXU +Read, write, execute/search by owner. +.TP 7 +S_IRUSR +.RS +Read permission, owner. +.RE +.TP 7 +S_IWUSR +.RS +Write permission, owner. +.RE +.TP 7 +S_IXUSR +.RS +Execute/search permission, owner. +.RE +.sp +.TP 7 +S_IRWXG +Read, write, execute/search by group. +.TP 7 +S_IRGRP +.RS +Read permission, group. +.RE +.TP 7 +S_IWGRP +.RS +Write permission, group. +.RE +.TP 7 +S_IXGRP +.RS +Execute/search permission, group. +.RE +.sp +.TP 7 +S_IRWXO +Read, write, execute/search by others. +.TP 7 +S_IROTH +.RS +Read permission, others. +.RE +.TP 7 +S_IWOTH +.RS +Write permission, others. +.RE +.TP 7 +S_IXOTH +.RS +Execute/search permission, others. +.RE +.sp +.TP 7 +S_ISUID +Set-user-ID on execution. +.TP 7 +S_ISGID +Set-group-ID on execution. +.TP 7 +S_ISVTX +On directories, restricted deletion flag. +.sp +.LP +The bits defined by S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP, S_IXGRP, +S_IROTH, S_IWOTH, S_IXOTH, S_ISUID, S_ISGID, \ and +S_ISVTX \ shall be unique. +.LP +S_IRWXU is the bitwise-inclusive OR of S_IRUSR, S_IWUSR, and S_IXUSR. +.LP +S_IRWXG is the bitwise-inclusive OR of S_IRGRP, S_IWGRP, and S_IXGRP. +.LP +S_IRWXO is the bitwise-inclusive OR of S_IROTH, S_IWOTH, and S_IXOTH. +.LP +Implementations may OR other implementation-defined bits into S_IRWXU, +S_IRWXG, and S_IRWXO, but they shall not overlap any of +the other bits defined in this volume of IEEE\ Std\ 1003.1-2001. The +\fIfile permission bits\fP are defined to be those +corresponding to the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and +S_IRWXO. +.LP +The following macros shall be provided to test whether a file is of +the specified type. The value \fIm\fP supplied to the +macros is the value of \fIst_mode\fP from a \fBstat\fP structure. +The macro shall evaluate to a non-zero value if the test is +true; 0 if the test is false. +.TP 7 +S_ISBLK(\fIm\fP) +Test for a block special file. +.TP 7 +S_ISCHR(\fIm\fP) +Test for a character special file. +.TP 7 +S_ISDIR(\fIm\fP) +Test for a directory. +.TP 7 +S_ISFIFO(\fIm\fP) +Test for a pipe or FIFO special file. +.TP 7 +S_ISREG(\fIm\fP) +Test for a regular file. +.TP 7 +S_ISLNK(\fIm\fP) +Test for a symbolic link. +.TP 7 +S_ISSOCK(\fIm\fP) +Test for a socket. +.sp +.LP +The implementation may implement message queues, semaphores, or shared +memory objects as distinct file types. The following +macros shall be provided to test whether a file is of the specified +type. The value of the \fIbuf\fP argument supplied to the +macros is a pointer to a \fBstat\fP structure. The macro shall evaluate +to a non-zero value if the specified object is implemented +as a distinct file type and the specified file type is contained in +the \fBstat\fP structure referenced by \fIbuf\fP. Otherwise, +the macro shall evaluate to zero. +.TP 7 +S_TYPEISMQ(\fIbuf\fP) +Test for a message queue. +.TP 7 +S_TYPEISSEM(\fIbuf\fP) +Test for a semaphore. +.TP 7 +S_TYPEISSHM(\fIbuf\fP) +Test for a shared memory object. +.sp +.LP +The implementation may implement typed memory objects as distinct +file types, and the following macro shall test whether a +file is of the specified type. The value of the \fIbuf\fP argument +supplied to the macros is a pointer to a \fBstat\fP structure. +The macro shall evaluate to a non-zero value if the specified object +is implemented as a distinct file type and the specified file +type is contained in the \fBstat\fP structure referenced by \fIbuf\fP. +Otherwise, the macro shall evaluate to zero. +.TP 7 +S_TYPEISTMO(\fIbuf\fP) +Test macro for a typed memory object. +.sp +.LP +The following shall be declared as functions and may also be defined +as macros. Function prototypes shall be provided. +.sp +.RS +.nf + +\fBint chmod(const char *, mode_t); +int fchmod(int, mode_t); +int fstat(int, struct stat *); +int lstat(const char *restrict, struct stat *restrict); +int mkdir(const char *, mode_t); +int mkfifo(const char *, mode_t); + +int mknod(const char *, mode_t, dev_t); + +int stat(const char *restrict, struct stat *restrict); +mode_t umask(mode_t); +\fP +.fi +.RE +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Use of the macros is recommended for determining the type of a file. +.SH RATIONALE +.LP +A conforming C-language application must include \fI<sys/stat.h>\fP +for functions that have arguments or return values of +type \fBmode_t\fP, so that symbolic values for that type can be used. +An alternative would be to require that these constants are +also defined by including \fI<sys/types.h>\fP. +.LP +The S_ISUID and S_ISGID bits may be cleared on any write, not just +on \fIopen\fP(), as +some historical implementations do. +.LP +System calls that update the time entry fields in the \fBstat\fP structure +must be documented by the implementors. +POSIX-conforming systems should not update the time entry fields for +functions listed in the System Interfaces volume of +IEEE\ Std\ 1003.1-2001 unless the standard requires that they do, +except in the case of documented extensions to the +standard. +.LP +Note that \fIst_dev\fP must be unique within a Local Area Network +(LAN) in a ``system'' made up of multiple computers' file +systems connected by a LAN. +.LP +Networked implementations of a POSIX-conforming system must guarantee +that all files visible within the file tree (including +parts of the tree that may be remotely mounted from other machines +on the network) on each individual processor are uniquely +identified by the combination of the \fIst_ino\fP and \fIst_dev\fP +fields. +.LP +The unit for the \fIst_blocks\fP member of the \fBstat\fP structure +is not defined within IEEE\ Std\ 1003.1-2001. In +some implementations it is 512 bytes. It may differ on a file system +basis. There is no correlation between values of the +\fIst_blocks\fP and \fIst_blksize\fP, and the \fIf_bsize\fP (from +\fI<sys/statvfs.h>\fP) structure members. +.LP +Traditionally, some implementations defined the multiplier for \fIst_blocks\fP +in +\fI<sys/param.h>\fP as the symbol DEV_BSIZE. +.SH FUTURE DIRECTIONS +.LP +No new S_IFMT symbolic names for the file type values of \fBmode_t\fP +will be defined by IEEE\ Std\ 1003.1-2001; if new +file types are required, they will only be testable through \fIS_ISxx\fP() +or \fIS_TYPEISxxx\fP() macros instead. +.SH SEE ALSO +.LP +\fI<sys/statvfs.h>\fP , \fI<sys/types.h>\fP , the System Interfaces +volume of IEEE\ Std\ 1003.1-2001, \fIchmod\fP(), \fIfchmod\fP(), \fIfstat\fP(), +\fIlstat\fP(), \fImkdir\fP(), \fImkfifo\fP(), \fImknod\fP(), \fIstat\fP(), +\fIumask\fP() +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |