Commit | Line | Data |
---|---|---|
924d83cf KM |
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 | .\" | |
08cf11bd | 5 | .\" @(#)stat.2 6.7 (Berkeley) %G% |
924d83cf | 6 | .\" |
9d2e549b | 7 | .TH STAT 2 "" |
924d83cf KM |
8 | .UC 4 |
9 | .SH NAME | |
7b1f0e33 | 10 | stat, lstat, fstat \- get file status |
924d83cf KM |
11 | .SH SYNOPSIS |
12 | .nf | |
7b1f0e33 KM |
13 | .ft B |
14 | #include <sys/types.h> | |
15 | #include <sys/stat.h> | |
924d83cf | 16 | .PP |
7b1f0e33 KM |
17 | .ft B |
18 | stat(path, buf) | |
19 | char *path; | |
20 | struct stat *buf; | |
924d83cf | 21 | .PP |
7b1f0e33 KM |
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; | |
924d83cf | 31 | .fi |
7b1f0e33 | 32 | .ft R |
924d83cf KM |
33 | .SH DESCRIPTION |
34 | .I Stat | |
7b1f0e33 KM |
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 | |
924d83cf KM |
50 | .I Fstat |
51 | obtains the same information about an open file | |
7b1f0e33 KM |
52 | referenced by the argument descriptor, such as would |
53 | be obtained by an \fIopen\fP call. | |
924d83cf | 54 | .PP |
7b1f0e33 KM |
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 | |
924d83cf | 60 | .I buf |
924d83cf KM |
61 | .PP |
62 | .nf | |
7b1f0e33 KM |
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 */ | |
08cf11bd KB |
69 | uid_t st_uid; /* user-id of owner */ |
70 | gid_t st_gid; /* group-id of owner */ | |
7b1f0e33 KM |
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 | }; | |
924d83cf KM |
83 | .fi |
84 | .DT | |
85 | .PP | |
7b1f0e33 KM |
86 | .TP 12 |
87 | st_atime | |
70abc759 | 88 | Time when file data was last accessed. Changed by the following system |
7b1f0e33 KM |
89 | calls: |
90 | .IR mknod (2), | |
91 | .IR utimes (2), | |
7b1f0e33 | 92 | and |
70abc759 | 93 | .IR read (2). |
7b1f0e33 KM |
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), | |
460177a7 | 114 | .IR rename (2), |
7b1f0e33 KM |
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 | |
924d83cf KM |
139 | The mode bits 0000070 and 0000007 encode group and |
140 | others permissions (see | |
141 | .IR chmod (2)). | |
7b1f0e33 KM |
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 | |
b5984ffe | 156 | [EINVAL] |
7b1f0e33 KM |
157 | The pathname contains a character with the high-order bit set. |
158 | .TP 15 | |
b5984ffe KM |
159 | [ENAMETOOLONG] |
160 | A component of a pathname exceeded 255 characters, | |
161 | or an entire path name exceeded 1023 characters. | |
7b1f0e33 KM |
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 | |
b5984ffe KM |
169 | [ELOOP] |
170 | Too many symbolic links were encountered in translating the pathname. | |
171 | .TP 15 | |
7b1f0e33 KM |
172 | [EFAULT] |
173 | .I Buf | |
174 | or | |
175 | .I name | |
176 | points to an invalid address. | |
fd690c8b KM |
177 | .TP 15 |
178 | [EIO] | |
179 | An I/O error occurred while reading from or writing to the file system. | |
924d83cf | 180 | .PP |
7b1f0e33 KM |
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. | |
fd690c8b KM |
191 | .TP 15 |
192 | [EIO] | |
193 | An I/O error occurred while reading from or writing to the file system. | |
7b1f0e33 KM |
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 | |
eff6446c | 201 | to 64 bits. This, however, can break certain programs that |
7b1f0e33 KM |
202 | depend on the time stamps being contiguous (in calls to |
203 | .IR utimes (2)). | |
924d83cf | 204 | .SH "SEE ALSO" |
7b1f0e33 KM |
205 | chmod(2), chown(2), utimes(2) |
206 | .SH BUGS | |
207 | Applying | |
208 | .I fstat | |
9d2e549b | 209 | to a socket (and thus to a pipe) |
460177a7 KM |
210 | returns a zero'd buffer, |
211 | except for the blocksize field, | |
212 | and a unique device and inode number. |