Return to stat.2 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / man / man2

Annotation of 43BSDTahoe/man/man2/stat.2, revision 1.1

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

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