Return to stat.2 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys

Annotation of 43BSDReno/lib/libc/sys/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.8 (Berkeley) 8/21/89
        !             6: .\"
        !             7: .TH STAT 2 "August 21, 1989"
        !             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
        !            54: .I open
        !            55: call.
        !            56: .PP
        !            57: .I Buf
        !            58: is a pointer to a
        !            59: .I stat
        !            60: structure into which information is placed concerning the file.
        !            61: The contents of the structure pointed to by
        !            62: .IR buf :
        !            63: .PP
        !            64: .nf
        !            65:     struct stat {
        !            66:         dev_t    st_dev;      /* device inode resides on */
        !            67:         ino_t    st_ino;      /* inode's number */
        !            68:         u_short  st_mode;     /* inode protection mode */
        !            69:         short    st_nlink;    /* number or hard links to the file */
        !            70:         uid_t    st_uid;      /* user-id of owner */
        !            71:         gid_t    st_gid;      /* group-id of owner */
        !            72:         dev_t    st_rdev;     /* device type, for special file inode */
        !            73:         off_t    st_size;     /* file size, in bytes */
        !            74:         time_t   st_atime;    /* time of last access */
        !            75:         int      st_spare1;
        !            76:         time_t   st_mtime;    /* time of last data modification */
        !            77:         int      st_spare2;
        !            78:         time_t   st_ctime;    /* time of last file status change */
        !            79:         int      st_spare3;
        !            80:         long     st_blksize;  /* optimal file system I/O ops blocksize */
        !            81:         long     st_blocks;   /* blocks allocated for file */
        !            82:         u_long   st_flags;    /* user defined flags for file */
        !            83:         u_long   st_gen;      /* file generation number */
        !            84:     };
        !            85: .fi
        !            86: .DT
        !            87: .PP
        !            88: .TP
        !            89: st_atime
        !            90: Time when file data was last accessed.  Changed by the following system
        !            91: calls:
        !            92: .IR mknod (2),
        !            93: .IR utimes (2),
        !            94: and
        !            95: .IR read (2).
        !            96: For reasons of efficiency, 
        !            97: st_atime is not set when a directory
        !            98: is searched, although this would be more logical.
        !            99: .TP
        !           100: st_mtime
        !           101: Time when data was last modified.
        !           102: It is not set by changes of owner, group, link count, or mode.
        !           103: Changed by the following system calls:
        !           104: .IR mknod (2),
        !           105: .IR utimes (2),
        !           106: .IR write (2).
        !           107: .TP
        !           108: st_ctime
        !           109: Time when file status was last changed.
        !           110: It is set both both by writing and changing the i-node.
        !           111: Changed by the following system calls:
        !           112: .IR chmod (2)
        !           113: .IR chown (2),
        !           114: .IR link (2),
        !           115: .IR mknod (2),
        !           116: .IR rename (2),
        !           117: .IR unlink (2),
        !           118: .IR utimes (2),
        !           119: .IR write (2).
        !           120: .TP
        !           121: st_blocks
        !           122: The actual number of blocks allocated for the file in 512-byte units.
        !           123: .PP
        !           124: The status information word \fIst_mode\fP has bits:
        !           125: .nf
        !           126: .in +5n
        !           127: .ta 1.6i 2.5i 3i
        !           128: #define S_IFMT 0170000 /* type of file */
        !           129: #define\ \ \ \ S_IFDIR 0040000 /* directory */
        !           130: #define\ \ \ \ S_IFCHR 0020000 /* character special */
        !           131: #define\ \ \ \ S_IFBLK 0060000 /* block special */
        !           132: #define\ \ \ \ S_IFREG 0100000 /* regular */
        !           133: #define\ \ \ \ S_IFLNK 0120000 /* symbolic link */
        !           134: #define\ \ \ \ S_IFSOCK        0140000 /* socket */
        !           135: #define S_ISUID        0004000 /* set user id on execution */
        !           136: #define S_ISGID        0002000 /* set group id on execution */
        !           137: #define S_ISVTX        0001000 /* save swapped text even after use */
        !           138: #define S_IREAD        0000400 /* read permission, owner */
        !           139: #define S_IWRITE       0000200 /* write permission, owner */
        !           140: #define S_IEXEC        0000100 /* execute/search permission, owner */
        !           141: .fi
        !           142: .in -5n
        !           143: .PP
        !           144: The mode bits 0000070 and 0000007 encode group and
        !           145: others permissions (see
        !           146: .IR chmod (2)).
        !           147: .SH "RETURN VALUE
        !           148: Upon successful completion a value of 0 is returned.
        !           149: Otherwise, a value of \-1 is returned and
        !           150: .I errno
        !           151: is set to indicate the error.
        !           152: .SH "ERRORS
        !           153: .I Stat
        !           154: and
        !           155: .I lstat
        !           156: will fail if one or more of the following are true:
        !           157: .TP 15
        !           158: [ENOTDIR]
        !           159: A component of the path prefix is not a directory.
        !           160: .TP 15
        !           161: [EINVAL]
        !           162: The pathname contains a character with the high-order bit set.
        !           163: .TP 15
        !           164: [ENAMETOOLONG]
        !           165: A component of a pathname exceeded 255 characters,
        !           166: or an entire path name exceeded 1023 characters.
        !           167: .TP 15
        !           168: [ENOENT]
        !           169: The named file does not exist.
        !           170: .TP 15
        !           171: [EACCES]
        !           172: Search permission is denied for a component of the path prefix.
        !           173: .TP 15
        !           174: [ELOOP]
        !           175: Too many symbolic links were encountered in translating the pathname.
        !           176: .TP 15
        !           177: [EFAULT]
        !           178: .I Buf
        !           179: or
        !           180: .I name
        !           181: points to an invalid address.
        !           182: .TP 15
        !           183: [EIO]
        !           184: An I/O error occurred while reading from or writing to the file system.
        !           185: .PP
        !           186: .I Fstat
        !           187: will fail if one or both of the following are true:
        !           188: .TP 15
        !           189: [EBADF]
        !           190: .I Fildes
        !           191: is not a valid open file descriptor.
        !           192: .TP 15
        !           193: [EFAULT]
        !           194: .I Buf
        !           195: points to an invalid address.
        !           196: .TP 15
        !           197: [EIO]
        !           198: An I/O error occurred while reading from or writing to the file system.
        !           199: .SH CAVEAT
        !           200: The fields in the stat structure currently marked 
        !           201: .IR st_spare1 ,
        !           202: .IR st_spare2 ,
        !           203: and
        !           204: .I st_spare3
        !           205: are present in preparation for inode time stamps expanding
        !           206: to 64 bits.  This, however, can break certain programs that
        !           207: depend on the time stamps being contiguous (in calls to
        !           208: .IR utimes (2)).
        !           209: .SH "SEE ALSO"
        !           210: chmod(2), chown(2), utimes(2)
        !           211: .SH BUGS
        !           212: Applying
        !           213: .I fstat
        !           214: to a socket (and thus to a pipe)
        !           215: returns a zero'd buffer,
        !           216: except for the blocksize field,
        !           217: 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.