Return to stat.2 CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man2

Annotation of cci/usr/src/man/man2/stat.2, revision 1.1

1.1     ! root        1: .TH STAT 2 "27 July 1983"
        !             2: .UC 4
        !             3: .SH NAME
        !             4: stat, lstat, fstat \- get file status
        !             5: .SH SYNOPSIS
        !             6: .nf
        !             7: .ft B
        !             8: #include <sys/types.h>
        !             9: #include <sys/stat.h>
        !            10: .PP
        !            11: .ft B
        !            12: stat(path, buf)
        !            13: char *path;
        !            14: struct stat *buf;
        !            15: .PP
        !            16: .ft B
        !            17: lstat(path, buf)
        !            18: char *path;
        !            19: struct stat *buf;
        !            20: .PP
        !            21: .ft B
        !            22: fstat(fd, buf)
        !            23: int fd;
        !            24: struct stat *buf;
        !            25: .fi
        !            26: .ft R
        !            27: .SH DESCRIPTION
        !            28: .I Stat
        !            29: obtains information about the file
        !            30: .IR path .
        !            31: Read, write or execute
        !            32: permission of the named file is not required, but all directories
        !            33: listed in the path name leading to the file must be reachable.
        !            34: .PP
        !            35: .I Lstat
        !            36: is like \fIstat\fP except in the case where the named file is a symbolic link,
        !            37: in which case
        !            38: .I lstat
        !            39: returns information about the link,
        !            40: while
        !            41: .I stat
        !            42: returns information about the file the link references.
        !            43: .PP
        !            44: .I Fstat
        !            45: obtains the same information about an open file
        !            46: referenced by the argument descriptor, such as would
        !            47: be obtained by an \fIopen\fP call.
        !            48: .PP
        !            49: .I Buf
        !            50: is a pointer to a
        !            51: .I stat
        !            52: structure into which information is placed concerning the file.
        !            53: The contents of the structure pointed to by
        !            54: .I buf
        !            55: .PP
        !            56: .nf
        !            57: .ta 1i 1.7i 2.5i
        !            58:      struct stat {
        !            59:        dev_t   st_dev; /* device inode resides on */
        !            60:        ino_t   st_ino; /* this inode's number */
        !            61:        u_short st_mode;        /* protection */
        !            62:        short   st_nlink;       /* number or hard links to the file */
        !            63:        short   st_uid; /* user-id of owner */
        !            64:        short   st_gid; /* group-id of owner */
        !            65:        dev_t   st_rdev;        /* the device type, for inode that is device */
        !            66:        off_t   st_size;        /* total size of file */
        !            67:        time_t  st_atime;       /* file last access time */
        !            68:        int     st_spare1;
        !            69:        time_t  st_mtime;       /* file last modify time */
        !            70:        int     st_spare2;
        !            71:        time_t  st_ctime;       /* file last status change time */
        !            72:        int     st_spare3;
        !            73:        long    st_blksize;     /* optimal blocksize for file system i/o ops */
        !            74:        long    st_blocks;      /* actual number of blocks allocated */
        !            75:        long    st_spare4[2];
        !            76:     };
        !            77: .fi
        !            78: .DT
        !            79: .PP
        !            80: .TP 12
        !            81: st_atime
        !            82: Time when file data was last read or modified.  Changed by the following system
        !            83: calls:
        !            84: .IR mknod (2),
        !            85: .IR utimes (2),
        !            86: .IR read (2),
        !            87: and
        !            88: .IR write (2).
        !            89: For reasons of efficiency, 
        !            90: st_atime is not set when a directory
        !            91: is searched, although this would be more logical.
        !            92: .TP 12
        !            93: st_mtime
        !            94: Time when data was last modified.
        !            95: It is not set by changes of owner, group, link count, or mode.
        !            96: Changed by the following system calls:
        !            97: .IR mknod (2),
        !            98: .IR utimes (2),
        !            99: .IR write (2).
        !           100: .TP 12
        !           101: st_ctime
        !           102: Time when file status was last changed.
        !           103: It is set both both by writing and changing the i-node.
        !           104: Changed by the following system calls:
        !           105: .IR chmod (2)
        !           106: .IR chown (2),
        !           107: .IR link (2),
        !           108: .IR mknod (2),
        !           109: .IR unlink (2),
        !           110: .IR utimes (2),
        !           111: .IR write (2).
        !           112: .PP
        !           113: The status information word \fIst_mode\fP has bits:
        !           114: .nf
        !           115: .in +5n
        !           116: .ta 1.6i 2.5i 3i
        !           117: #define S_IFMT 0170000 /* type of file */
        !           118: #define\ \ \ \ S_IFDIR 0040000 /* directory */
        !           119: #define\ \ \ \ S_IFCHR 0020000 /* character special */
        !           120: #define\ \ \ \ S_IFBLK 0060000 /* block special */
        !           121: #define\ \ \ \ S_IFREG 0100000 /* regular */
        !           122: #define\ \ \ \ S_IFLNK 0120000 /* symbolic link */
        !           123: #define\ \ \ \ S_IFSOCK        0140000 /* socket */
        !           124: #define S_ISUID        0004000 /* set user id on execution */
        !           125: #define S_ISGID        0002000 /* set group id on execution */
        !           126: #define S_ISVTX        0001000 /* save swapped text even after use */
        !           127: #define S_IREAD        0000400 /* read permission, owner */
        !           128: #define S_IWRITE       0000200 /* write permission, owner */
        !           129: #define S_IEXEC        0000100 /* execute/search permission, owner */
        !           130: .fi
        !           131: .in -5n
        !           132: .PP
        !           133: The mode bits 0000070 and 0000007 encode group and
        !           134: others permissions (see
        !           135: .IR chmod (2)).
        !           136: .PP
        !           137: When
        !           138: .I fd
        !           139: is associated with a pipe,
        !           140: .I fstat
        !           141: reports an ordinary file with an i-node number,
        !           142: restricted permissions,
        !           143: and a not necessarily meaningful length.
        !           144: .SH "RETURN VALUE
        !           145: Upon successful completion a value of 0 is returned.
        !           146: Otherwise, a value of \-1 is returned and
        !           147: .I errno
        !           148: is set to indicate the error.
        !           149: .SH "ERRORS
        !           150: .I Stat
        !           151: and
        !           152: .I lstat
        !           153: will fail if one or more of the following are true:
        !           154: .TP 15
        !           155: [ENOTDIR]
        !           156: A component of the path prefix is not a directory.
        !           157: .TP 15
        !           158: [EPERM]
        !           159: The pathname contains a character with the high-order bit set.
        !           160: .TP 15
        !           161: [ENOENT]
        !           162: The pathname was too long.
        !           163: .TP 15
        !           164: [ENOENT]
        !           165: The named file does not exist.
        !           166: .TP 15
        !           167: [EACCES]
        !           168: Search permission is denied for a component of the path prefix.
        !           169: .TP 15
        !           170: [EFAULT]
        !           171: .I Buf
        !           172: or
        !           173: .I name
        !           174: points to an invalid address.
        !           175: .PP
        !           176: .I Fstat
        !           177: will fail if one or both of the following are true:
        !           178: .TP 15
        !           179: [EBADF]
        !           180: .I Fildes
        !           181: is not a valid open file descriptor.
        !           182: .TP 15
        !           183: [EFAULT]
        !           184: .I Buf
        !           185: points to an invalid address.
        !           186: .TP 15
        !           187: [ELOOP]
        !           188: Too many symbolic links were encountered in translating the pathname.
        !           189: .SH CAVEAT
        !           190: The fields in the stat structure currently marked 
        !           191: .IR st_spare1 ,
        !           192: .IR st_spare2 ,
        !           193: and
        !           194: .I st_spare3
        !           195: are present in preparation for inode time stamps expanding
        !           196: to 64 bits.  This, however, can break certain programs which
        !           197: depend on the time stamps being contiguous (in calls to
        !           198: .IR utimes (2)).
        !           199: .SH "SEE ALSO"
        !           200: chmod(2), chown(2), utimes(2)
        !           201: .SH BUGS
        !           202: Applying
        !           203: .I fstat
        !           204: to a socket returns a zero'd buffer.
        !           205: .PP
        !           206: The list of calls which modify the various fields should be carefully
        !           207: checked with reality.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.