projects / unix-history / blobdiff
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
my previous version was wrong; this one is right
[unix-history] / usr / src / lib / libc / sys / stat.2
diff --git a/usr/src/lib/libc/sys/stat.2 b/usr/src/lib/libc/sys/stat.2
index bcef9be..5b360e5 100644 (file)
--- a/usr/src/lib/libc/sys/stat.2
+++ b/usr/src/lib/libc/sys/stat.2
@@ -1,206 +1,221 @@
-.\" Copyright (c) 1980 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1980, 1991 Regents of the University of California.
+.\" All rights reserved.
 .\"
 .\"
-.\"    @(#)stat.2      6.1 (Berkeley) %G%
+.\" %sccs.include.redist.man%
 .\"
 .\"
-.TH STAT 2 ""
-.UC 4
-.SH NAME
-stat, lstat, fstat \- get file status
-.SH SYNOPSIS
-.nf
-.ft B
-#include <sys/types.h>
-#include <sys/stat.h>
-.PP
-.ft B
-stat(path, buf)
-char *path;
-struct stat *buf;
-.PP
-.ft B
-lstat(path, buf)
-char *path;
-struct stat *buf;
-.PP
-.ft B
-fstat(fd, buf)
-int fd;
-struct stat *buf;
-.fi
-.ft R
-.SH DESCRIPTION
-.I Stat
-obtains information about the file
-.IR path .
+.\"     @(#)stat.2     6.9 (Berkeley) %G%
+.\"
+.Dd 
+.Dt STAT 2
+.Os BSD 4
+.Sh NAME
+.Nm stat ,
+.Nm lstat ,
+.Nm fstat
+.Nd get file status
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/stat.h>
+.Ft int
+.Fn stat "const char *path" "struct stat *buf"
+.Ft int
+.Fn lstat "const char *path" "struct stat *buf"
+.Ft int
+.Fn fstat "int fd" "struct stat *buf"
+.Sh DESCRIPTION
+The
+.Fn stat
+function obtains information about the file pointed to by
+.Fa path .
 Read, write or execute
 permission of the named file is not required, but all directories
 Read, write or execute
 permission of the named file is not required, but all directories
-listed in the path name leading to the file must be reachable.
-.PP
-.I Lstat
-is like \fIstat\fP except in the case where the named file is a symbolic link,
+listed in the path name leading to the file must be seachable.
+.Pp
+.Fn Lstat
+is like
+.Fn stat
+except in the case where the named file is a symbolic link,
 in which case
 in which case
-.I lstat
+.Fn lstat
 returns information about the link,
 while
 returns information about the link,
 while
-.I stat
+.Fn stat
 returns information about the file the link references.
 returns information about the file the link references.
-.PP
-.I Fstat
+.Pp
+The
+.Fn fstat
 obtains the same information about an open file
 obtains the same information about an open file
-referenced by the argument descriptor, such as would
-be obtained by an \fIopen\fP call.
-.PP
-.I Buf
+known by the file descriptor
+.Fa fd ,
+such as would
+be obtained by an
+.Xr open
+call.
+.Pp
+.Fa Buf
 is a pointer to a
 is a pointer to a
-.I stat
-structure into which information is placed concerning the file.
-The contents of the structure pointed to by
-.I buf
-.PP
-.nf
-.ta 1i 1.7i 2.5i
-     struct stat {
-       dev_t   st_dev; /* device inode resides on */
-       ino_t   st_ino; /* this inode's number */
-       u_short st_mode;        /* protection */
-       short   st_nlink;       /* number or hard links to the file */
-       short   st_uid; /* user-id of owner */
-       short   st_gid; /* group-id of owner */
-       dev_t   st_rdev;        /* the device type, for inode that is device */
-       off_t   st_size;        /* total size of file */
-       time_t  st_atime;       /* file last access time */
-       int     st_spare1;
-       time_t  st_mtime;       /* file last modify time */
-       int     st_spare2;
-       time_t  st_ctime;       /* file last status change time */
-       int     st_spare3;
-       long    st_blksize;     /* optimal blocksize for file system i/o ops */
-       long    st_blocks;      /* actual number of blocks allocated */
-       long    st_spare4[2];
-    };
-.fi
-.DT
-.PP
-.TP 12
-st_atime
-Time when file data was last read or modified.  Changed by the following system
+.Fn stat
+structure
+as defined by
+.Aq Pa sys/stat.h
+(shown below)
+and into which information is placed concerning the file.
+.Bd -literal
+struct stat {
+    dev_t    st_dev;    /* device inode resides on */
+    ino_t    st_ino;    /* inode's number */
+    mode_t   st_mode;   /* inode protection mode */
+    nlink_t  st_nlink;  /* number or hard links to the file */
+    uid_t    st_uid;    /* user-id of owner */
+    gid_t    st_gid;    /* group-id of owner */
+    dev_t    st_rdev;   /* device type, for special file inode */
+    off_t    st_size;   /* file size, in bytes */
+    time_t   st_atime;  /* time of last access */
+    long     st_spare1;
+    time_t   st_mtime;  /* time of last data modification */
+    long     st_spare2;
+    time_t   st_ctime;  /* time of last file status change */
+    long     st_spare3;
+    long     st_blksize;/* optimal file sys I/O ops blocksize */
+    long     st_blocks; /* blocks allocated for file */
+    u_long   st_flags;  /* user defined flags for file */
+    u_long   st_gen;    /* file generation number */
+};
+.Ed
+.Pp
+The time-related fields of
+.Fa struct stat
+are as follows:
+.Bl -tag -width st_blocks
+.It st_atime
+Time when file data last accessed.  Changed by the following system
 calls:
 calls:
-.IR mknod (2),
-.IR utimes (2),
-.IR read (2),
+.Xr mknod 2 ,
+.Xr utimes 2 ,
 and
 and
-.IR write (2).
-For reasons of efficiency, 
-st_atime is not set when a directory
-is searched, although this would be more logical.
-.TP 12
-st_mtime
-Time when data was last modified.
-It is not set by changes of owner, group, link count, or mode.
+.Xr read 2 .
+.It st_mtime
+Time when file data last modified.
 Changed by the following system calls:
 Changed by the following system calls:
-.IR mknod (2),
-.IR utimes (2),
-.IR write (2).
-.TP 12
-st_ctime
-Time when file status was last changed.
-It is set both both by writing and changing the i-node.
+.Xr mknod 2 ,
+.Xr utimes 2 ,
+.Xr write 2 .
+.It st_ctime
+Time when file status was last changed (inode data modification).
 Changed by the following system calls:
 Changed by the following system calls:
-.IR chmod (2)
-.IR chown (2),
-.IR link (2),
-.IR mknod (2),
-.IR unlink (2),
-.IR utimes (2),
-.IR write (2).
-.PP
-The status information word \fIst_mode\fP has bits:
-.nf
-.in +5n
-.ta 1.6i 2.5i 3i
-#define S_IFMT 0170000 /* type of file */
-#define\ \ \ \ S_IFDIR 0040000 /* directory */
-#define\ \ \ \ S_IFCHR 0020000 /* character special */
-#define\ \ \ \ S_IFBLK 0060000 /* block special */
-#define\ \ \ \ S_IFREG 0100000 /* regular */
-#define\ \ \ \ S_IFLNK 0120000 /* symbolic link */
-#define\ \ \ \ S_IFSOCK        0140000 /* socket */
-#define S_ISUID        0004000 /* set user id on execution */
-#define S_ISGID        0002000 /* set group id on execution */
-#define S_ISVTX        0001000 /* save swapped text even after use */
-#define S_IREAD        0000400 /* read permission, owner */
-#define S_IWRITE       0000200 /* write permission, owner */
-#define S_IEXEC        0000100 /* execute/search permission, owner */
-.fi
-.in -5n
-.PP
-The mode bits 0000070 and 0000007 encode group and
-others permissions (see
-.IR chmod (2)).
-.SH "RETURN VALUE
+.Xr chmod 2
+.Xr chown 2 ,
+.Xr link 2 ,
+.Xr mknod 2 ,
+.Xr rename 2 ,
+.Xr unlink 2 ,
+.Xr utimes 2 ,
+.Xr write 2 .
+.It st_blocks
+The actual number of blocks allocated for the file in 512-byte units.
+.El
+.Pp
+The status information word
+.Fa st_mode
+has bits:
+.Bd -literal
+#define S_IFMT 0170000           /* type of file */
+#define        S_IFIFO  0010000  /* named pipe (fifo) */
+#define        S_IFCHR  0020000  /* character special */
+#define        S_IFDIR  0040000  /* directory */
+#define        S_IFBLK  0060000  /* block special */
+#define        S_IFREG  0100000  /* regular */
+#define        S_IFLNK  0120000  /* symbolic link */
+#define        S_IFSOCK 0140000  /* socket */
+#define S_ISUID 0004000  /* set user id on execution */
+#define S_ISGID 0002000  /* set group id on execution */
+#define S_ISVTX 0001000  /* save swapped text even after use */
+#define S_IRUSR 0000400  /* read permission, owner */
+#define S_IWUSR 0000200  /* write permission, owner */
+#define S_IXUSR 0000100  /* execute/search permission, owner */
+.Ed
+.Pp
+For a list of access modes, see
+.Aq Pa sys/stat.h ,
+.Xr access 2
+and
+.Xr chmod 2 .
+.Sh RETURN VALUES
 Upon successful completion a value of 0 is returned.
 Upon successful completion a value of 0 is returned.
-Otherwise, a value of \-1 is returned and
-.I errno
+Otherwise, a value of -1 is returned and
+.Va errno
 is set to indicate the error.
 is set to indicate the error.
-.SH "ERRORS
-.I Stat
+.Sh ERRORS
+.Fn Stat
 and
 and
-.I lstat
-will fail if one or more of the following are true:
-.TP 15
-[ENOTDIR]
+.Fn lstat
+will fail if:
+.Bl -tag -width ENAMETOOLONGAA
+.It Bq Er ENOTDIR
 A component of the path prefix is not a directory.
 A component of the path prefix is not a directory.
-.TP 15
-[EPERM]
+.It Bq Er EINVAL
 The pathname contains a character with the high-order bit set.
 The pathname contains a character with the high-order bit set.
-.TP 15
-[ENOENT]
-The pathname was too long.
-.TP 15
-[ENOENT]
+.It Bq Er ENAMETOOLONG
+A component of a pathname exceeded 255 characters,
+or an entire path name exceeded 1023 characters.
+.It Bq Er ENOENT
 The named file does not exist.
 The named file does not exist.
-.TP 15
-[EACCES]
+.It Bq Er EACCES
 Search permission is denied for a component of the path prefix.
 Search permission is denied for a component of the path prefix.
-.TP 15
-[EFAULT]
-.I Buf
+.It Bq Er ELOOP
+Too many symbolic links were encountered in translating the pathname.
+.It Bq Er EFAULT
+.Fa Buf
 or
 or
-.I name
+.Em name
 points to an invalid address.
 points to an invalid address.
-.TP 15
-[ELOOP]
-Too many symbolic links were encountered in translating the pathname.
-.PP
-.I Fstat
-will fail if one or both of the following are true:
-.TP 15
-[EBADF]
-.I Fildes
+.It Bq Er EIO
+An I/O error occurred while reading from or writing to the file system.
+.El
+.Pp
+.Bl -tag -width [EFAULT]
+.Fn Fstat
+will fail if:
+.It Bq Er EBADF
+.Fa fd
 is not a valid open file descriptor.
 is not a valid open file descriptor.
-.TP 15
-[EFAULT]
-.I Buf
+.It Bq Er EFAULT
+.Fa Buf
 points to an invalid address.
 points to an invalid address.
-.SH CAVEAT
+.It Bq Er EIO
+An I/O error occurred while reading from or writing to the file system.
+.El
+.Sh CAVEAT
 The fields in the stat structure currently marked 
 The fields in the stat structure currently marked 
-.IR st_spare1 ,
-.IR st_spare2 ,
+.Fa st_spare1 ,
+.Fa st_spare2 ,
 and
 and
-.I st_spare3
+.Fa st_spare3
 are present in preparation for inode time stamps expanding
 are present in preparation for inode time stamps expanding
-to 64 bits.  This, however, can break certain programs which
+to 64 bits.  This, however, can break certain programs that
 depend on the time stamps being contiguous (in calls to
 depend on the time stamps being contiguous (in calls to
-.IR utimes (2)).
-.SH "SEE ALSO"
-chmod(2), chown(2), utimes(2)
-.SH BUGS
+.Xr utimes 2 ) .
+.Sh SEE ALSO
+.Xr chmod 2 ,
+.Xr chown 2 ,
+.Xr utimes 2
+.Sh BUGS
 Applying
 Applying
-.I fstat
+.Xr fstat
 to a socket (and thus to a pipe)
 to a socket (and thus to a pipe)
-returns a zero'd buffer, except for the blocksize field.
-.PP
-The list of calls which modify the various fields should be carefully
-checked with reality.
+returns a zero'd buffer,
+except for the blocksize field,
+and a unique device and inode number.
+.Sh STANDARDS
+The
+.Fn stat
+and
+.Fn fstat
+function calls are expected to
+conform to IEEE Std 1003.1-1988
+.Pq Dq Tn POSIX .
+.Sh HISTORY
+A
+.Nm lstat
+function call appeared in
+.Bx 4.2 .
Continuous source code history from original PDP-7 UNIX to FreeBSD 2, the first fully unencumbered FreeBSD release.