![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to stat.2 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys|
Return to stat.2 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys |
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.