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