BSD 4_3 release

[unix-history] / usr / man / man2 / stat.2

diff --git a/usr/man/man2/stat.2 b/usr/man/man2/stat.2
index 2b36262..ddbd2e8 100644 (file)
--- a/usr/man/man2/stat.2
+++ b/usr/man/man2/stat.2
@@ -1,4 +1,11 @@
-.TH STAT 2 2/13/83
+.\" Copyright (c) 1980 Regents of the University of California.
+.\" All rights reserved.  The Berkeley software License Agreement
+.\" specifies the terms and conditions for redistribution.
+.\"
+.\"    @(#)stat.2      6.5 (Berkeley) 5/12/86
+.\"
+.TH STAT 2 "May 12, 1986"
+.UC 4

 .SH NAME
 stat, lstat, fstat \- get file status
 .SH SYNOPSIS
 .SH NAME
 stat, lstat, fstat \- get file status
 .SH SYNOPSIS


@@ -26,7 +33,7 @@ struct stat *buf;
 .SH DESCRIPTION
 .I Stat
 obtains information about the file
 .SH DESCRIPTION
 .I Stat
 obtains information about the file

-.IR name .
+.IR path .

 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.
 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.


@@ -43,7 +50,7 @@ returns information about the file the link references.
 .I Fstat
 obtains the same information about an open file
 referenced by the argument descriptor, such as would
 .I Fstat
 obtains the same information about an open file
 referenced by the argument descriptor, such as would

-be obtained by a \fIopen\fP call.
+be obtained by an \fIopen\fP call.

 .PP
 .I Buf
 is a pointer to a
 .PP
 .I Buf
 is a pointer to a


@@ -70,7 +77,8 @@ The contents of the structure pointed to by
        time_t  st_ctime;       /* file last status change time */
        int     st_spare3;
        long    st_blksize;     /* optimal blocksize for file system i/o ops */
        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_spare4[3];
+       long    st_blocks;      /* actual number of blocks allocated */
+       long    st_spare4[2];

     };
 .fi
 .DT
     };
 .fi
 .DT


@@ -79,22 +87,20 @@ The contents of the structure pointed to by
 st_atime
 Time when file data was last read or modified.  Changed by the following system
 calls:
 st_atime
 Time when file data was last read or modified.  Changed by the following system
 calls:

-.IR creat (2),

 .IR mknod (2),
 .IR mknod (2),

-.IR utime (2),
+.IR utimes (2),

 .IR read (2),
 and
 .IR write (2).
 .IR read (2),
 and
 .IR write (2).

-For reasons of efficiency, it is not set when a directory
+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.
 Changed by the following system calls:
 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.
 Changed by the following system calls:

-.IR creat (2),

 .IR mknod (2),
 .IR mknod (2),

-.IR pipe (2),

 .IR utimes (2),
 .IR write (2).
 .TP 12
 .IR utimes (2),
 .IR write (2).
 .TP 12


@@ -104,10 +110,9 @@ It is set both both by writing and changing the i-node.
 Changed by the following system calls:
 .IR chmod (2)
 .IR chown (2),
 Changed by the following system calls:
 .IR chmod (2)
 .IR chown (2),

-.IR creat (2),

 .IR link (2),
 .IR mknod (2),
 .IR link (2),
 .IR mknod (2),

-.IR pipe (2),
+.IR rename (2),

 .IR unlink (2),
 .IR utimes (2),
 .IR write (2).
 .IR unlink (2),
 .IR utimes (2),
 .IR write (2).


@@ -117,12 +122,12 @@ The status information word \fIst_mode\fP has bits:
 .in +5n
 .ta 1.6i 2.5i 3i
 #define S_IFMT 0170000 /* type of file */
 .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_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_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 */


@@ -135,14 +140,6 @@ The status information word \fIst_mode\fP has bits:
 The mode bits 0000070 and 0000007 encode group and
 others permissions (see
 .IR chmod (2)).
 The mode bits 0000070 and 0000007 encode group and
 others permissions (see
 .IR chmod (2)).

-.PP
-When
-.I fd
-is associated with a pipe,
-.I fstat
-reports an ordinary file with an i-node number,
-restricted permissions,
-and a not necessarily meaningful length.

 .SH "RETURN VALUE
 Upon successful completion a value of 0 is returned.
 Otherwise, a value of \-1 is returned and
 .SH "RETURN VALUE
 Upon successful completion a value of 0 is returned.
 Otherwise, a value of \-1 is returned and


@@ -157,11 +154,12 @@ will fail if one or more of the following are true:
 [ENOTDIR]
 A component of the path prefix is not a directory.
 .TP 15
 [ENOTDIR]
 A component of the path prefix is not a directory.
 .TP 15

-[EPERM]
-The pathname contained a non-ASCII character.
+[EINVAL]
+The pathname contains a character with the high-order bit set.

 .TP 15
 .TP 15

-[ENOENT]
-The pathname was too long.
+[ENAMETOOLONG]
+A component of a pathname exceeded 255 characters,
+or an entire path name exceeded 1023 characters.

 .TP 15
 [ENOENT]
 The named file does not exist.
 .TP 15
 [ENOENT]
 The named file does not exist.


@@ -169,11 +167,17 @@ The named file does not exist.
 [EACCES]
 Search permission is denied for a component of the path prefix.
 .TP 15
 [EACCES]
 Search permission is denied for a component of the path prefix.
 .TP 15

+[ELOOP]
+Too many symbolic links were encountered in translating the pathname.
+.TP 15

 [EFAULT]
 .I Buf
 or
 .I name
 points to an invalid address.
 [EFAULT]
 .I Buf
 or
 .I name
 points to an invalid address.

+.TP 15
+[EIO]
+An I/O error occurred while reading from or writing to the file system.

 .PP
 .I Fstat
 will fail if one or both of the following are true:
 .PP
 .I Fstat
 will fail if one or both of the following are true:


@@ -186,8 +190,8 @@ is not a valid open file descriptor.
 .I Buf
 points to an invalid address.
 .TP 15
 .I Buf
 points to an invalid address.
 .TP 15

-[ELOOP]
-Too many symbolic links were encountered in translating the pathname.
+[EIO]
+An I/O error occurred while reading from or writing to the file system.

 .SH CAVEAT
 The fields in the stat structure currently marked 
 .IR st_spare1 ,
 .SH CAVEAT
 The fields in the stat structure currently marked 
 .IR st_spare1 ,


@@ -195,15 +199,15 @@ The fields in the stat structure currently marked
 and
 .I st_spare3
 are present in preparation for inode time stamps expanding
 and
 .I st_spare3
 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 utime (2)).
+.IR utimes (2)).

 .SH "SEE ALSO"
 chmod(2), chown(2), utimes(2)
 .SH BUGS
 Applying
 .I fstat
 .SH "SEE ALSO"
 chmod(2), chown(2), utimes(2)
 .SH BUGS
 Applying
 .I fstat

-to a socket returns a zero'd buffer.
-.PP
-The list of calls which modify the varous fields should be carefully
-checked with reality.
+to a socket (and thus to a pipe)
+returns a zero'd buffer,
+except for the blocksize field,
+and a unique device and inode number.