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