]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | '\" t |
2 | .\" Hey Emacs! This file is -*- nroff -*- source. | |
3 | .\" | |
4 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 | |
5 | .\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95 | |
c11b1abf | 6 | .\" and Copyright (c) 2007 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
7 | .\" |
8 | .\" Permission is granted to make and distribute verbatim copies of this | |
9 | .\" manual provided the copyright notice and this permission notice are | |
10 | .\" preserved on all copies. | |
11 | .\" | |
12 | .\" Permission is granted to copy and distribute modified versions of this | |
13 | .\" manual under the conditions for verbatim copying, provided that the | |
14 | .\" entire resulting derived work is distributed under the terms of a | |
15 | .\" permission notice identical to this one. | |
c13182ef | 16 | .\" |
fea681da MK |
17 | .\" Since the Linux kernel and libraries are constantly changing, this |
18 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
19 | .\" responsibility for errors or omissions, or for damages resulting from | |
20 | .\" the use of the information contained herein. The author(s) may not | |
21 | .\" have taken the same level of care in the production of this manual, | |
22 | .\" which is licensed free of charge, as they might when working | |
23 | .\" professionally. | |
c13182ef | 24 | .\" |
fea681da MK |
25 | .\" Formatted or processed versions of this manual, if unaccompanied by |
26 | .\" the source, must acknowledge the copyright and authors of this work. | |
27 | .\" | |
28 | .\" Modified by Michael Haardt <michael@moria.de> | |
29 | .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> | |
30 | .\" Modified 1995-05-18 by Todd Larason <jtl@molehill.org> | |
31 | .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> | |
32 | .\" Modified 1995-01-09 by Richard Kettlewell <richard@greenend.org.uk> | |
33 | .\" Modified 1998-05-13 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de> | |
34 | .\" Modified 1999-07-06 by aeb & Albert Cahalan | |
35 | .\" Modified 2000-01-07 by aeb | |
c11b1abf | 36 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
bc7ff20e | 37 | .\" 2007-06-08 mtk: Added example program |
cd667553 | 38 | .\" 2007-07-05 mtk: Added details on underlying system call interfaces |
c13182ef | 39 | .\" |
50831f9b | 40 | .TH STAT 2 2010-09-20 "Linux" "Linux Programmer's Manual" |
fea681da MK |
41 | .SH NAME |
42 | stat, fstat, lstat \- get file status | |
43 | .SH SYNOPSIS | |
44 | .B #include <sys/types.h> | |
45 | .br | |
46 | .B #include <sys/stat.h> | |
47 | .br | |
48 | .B #include <unistd.h> | |
49 | .sp | |
da2d9dad | 50 | .BI "int stat(const char *" path ", struct stat *" buf ); |
fea681da | 51 | .br |
d3b03141 | 52 | .BI "int fstat(int " fd ", struct stat *" buf ); |
fea681da | 53 | .br |
da2d9dad | 54 | .BI "int lstat(const char *" path ", struct stat *" buf ); |
8179def1 MK |
55 | .sp |
56 | .in -4n | |
57 | Feature Test Macro Requirements for glibc (see | |
58 | .BR feature_test_macros (7)): | |
59 | .in | |
43e0fe7d MK |
60 | .ad l |
61 | .PD 0 | |
8179def1 MK |
62 | .sp |
63 | .BR lstat (): | |
43e0fe7d | 64 | .RS 4 |
43e0fe7d MK |
65 | _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || |
66 | _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED | |
3ba63d80 MK |
67 | .br |
68 | || /* Since glibc 2.10: */ _POSIX_C_SOURCE\ >=\ 200112L | |
43e0fe7d MK |
69 | .RE |
70 | .PD | |
71 | .ad | |
fea681da MK |
72 | .SH DESCRIPTION |
73 | .PP | |
da2d9dad MK |
74 | These functions return information about a file. |
75 | No permissions are required on the file itself, but \(em in the case of | |
76 | .BR stat () | |
c13182ef | 77 | and |
da2d9dad MK |
78 | .BR lstat () |
79 | \(em | |
80 | execute (search) permission is required on all of the directories in | |
81 | .I path | |
82 | that lead to the file. | |
fea681da | 83 | .PP |
da2d9dad | 84 | .BR stat () |
c13182ef | 85 | stats the file pointed to by |
da2d9dad | 86 | .I path |
fea681da MK |
87 | and fills in |
88 | .IR buf . | |
89 | ||
da2d9dad | 90 | .BR lstat () |
fea681da | 91 | is identical to |
da2d9dad MK |
92 | .BR stat (), |
93 | except that if | |
94 | .I path | |
95 | is a symbolic link, then the link itself is stat-ed, | |
fea681da MK |
96 | not the file that it refers to. |
97 | ||
da2d9dad | 98 | .BR fstat () |
fea681da | 99 | is identical to |
da2d9dad MK |
100 | .BR stat (), |
101 | except that the file to be stat-ed is specified by the file descriptor | |
d3b03141 | 102 | .IR fd . |
fea681da | 103 | .PP |
da2d9dad | 104 | All of these system calls return a |
fea681da MK |
105 | .I stat |
106 | structure, which contains the following fields: | |
107 | .PP | |
bd191423 | 108 | .in +4n |
fea681da MK |
109 | .nf |
110 | struct stat { | |
da2d9dad MK |
111 | dev_t st_dev; /* ID of device containing file */ |
112 | ino_t st_ino; /* inode number */ | |
5ae873ff MK |
113 | mode_t st_mode; /* protection */ |
114 | nlink_t st_nlink; /* number of hard links */ | |
115 | uid_t st_uid; /* user ID of owner */ | |
116 | gid_t st_gid; /* group ID of owner */ | |
da2d9dad | 117 | dev_t st_rdev; /* device ID (if special file) */ |
5ae873ff | 118 | off_t st_size; /* total size, in bytes */ |
24d01c53 | 119 | blksize_t st_blksize; /* blocksize for file system I/O */ |
614aae41 | 120 | blkcnt_t st_blocks; /* number of 512B blocks allocated */ |
5ae873ff MK |
121 | time_t st_atime; /* time of last access */ |
122 | time_t st_mtime; /* time of last modification */ | |
123 | time_t st_ctime; /* time of last status change */ | |
fea681da MK |
124 | }; |
125 | .fi | |
bd191423 | 126 | .in |
fea681da | 127 | .PP |
da2d9dad | 128 | The |
29de83af | 129 | .I st_dev |
da2d9dad | 130 | field describes the device on which this file resides. |
e9ef777f MK |
131 | (The |
132 | .BR major (3) | |
133 | and | |
134 | .BR minor (3) | |
135 | macros may be useful to decompose the device ID in this field.) | |
da2d9dad MK |
136 | |
137 | The | |
138 | .I st_rdev | |
139 | field describes the device that this file (inode) represents. | |
140 | ||
141 | The | |
fea681da | 142 | .I st_size |
c13182ef MK |
143 | field gives the size of the file (if it is a regular |
144 | file or a symbolic link) in bytes. | |
da2d9dad | 145 | The size of a symlink is the length of the pathname |
28d88c17 | 146 | it contains, without a trailing null byte. |
fea681da | 147 | |
da2d9dad | 148 | The |
fea681da | 149 | .I st_blocks |
32f30015 | 150 | field indicates the number of blocks allocated to the file, 512-byte units. |
fea681da | 151 | (This may be smaller than |
eee0a2ec MK |
152 | .IR st_size /512 |
153 | when the file has holes.) | |
da2d9dad MK |
154 | |
155 | The | |
0daa9e92 | 156 | .I st_blksize |
da2d9dad | 157 | field gives the "preferred" blocksize for efficient file system I/O. |
fea681da MK |
158 | (Writing to a file in smaller chunks may cause |
159 | an inefficient read-modify-rewrite.) | |
160 | .PP | |
24d01c53 | 161 | Not all of the Linux file systems implement all of the time fields. |
fea681da | 162 | Some file system types allow mounting in such a way that file |
86d89e4c | 163 | and/or directory accesses do not cause an update of the |
fea681da | 164 | .I st_atime |
c13182ef | 165 | field. |
86d89e4c MK |
166 | (See |
167 | .IR noatime , | |
168 | .IR nodiratime , | |
169 | and | |
170 | .I relatime | |
171 | in | |
172 | .BR mount (8), | |
173 | and related information in | |
174 | .BR mount (2).) | |
14adeb6d MK |
175 | In addition, |
176 | .I st_atime | |
177 | is not updated if a file is opened with the | |
178 | .BR O_NOATIME ; | |
179 | see | |
180 | .BR open (2). | |
fea681da MK |
181 | |
182 | The field | |
183 | .I st_atime | |
75b94dc3 | 184 | is changed by file accesses, for example, by |
fea681da MK |
185 | .BR execve (2), |
186 | .BR mknod (2), | |
187 | .BR pipe (2), | |
188 | .BR utime (2) | |
189 | and | |
190 | .BR read (2) | |
7c93fec0 MK |
191 | (of more than zero bytes). |
192 | Other routines, like | |
fea681da MK |
193 | .BR mmap (2), |
194 | may or may not update | |
195 | .IR st_atime . | |
196 | ||
197 | The field | |
198 | .I st_mtime | |
75b94dc3 | 199 | is changed by file modifications, for example, by |
fea681da MK |
200 | .BR mknod (2), |
201 | .BR truncate (2), | |
202 | .BR utime (2) | |
203 | and | |
204 | .BR write (2) | |
205 | (of more than zero bytes). | |
206 | Moreover, | |
207 | .I st_mtime | |
208 | of a directory is changed by the creation or deletion of files | |
209 | in that directory. | |
210 | The | |
211 | .I st_mtime | |
212 | field is | |
213 | .I not | |
214 | changed for changes in owner, group, hard link count, or mode. | |
215 | ||
216 | The field | |
217 | .I st_ctime | |
218 | is changed by writing or by setting inode information | |
219 | (i.e., owner, group, link count, mode, etc.). | |
220 | .PP | |
168df940 MK |
221 | The following POSIX macros are defined to check the file type using the |
222 | .I st_mode | |
223 | field: | |
bd191423 | 224 | .RS 4 |
fea681da | 225 | .TP 1.2i |
c91e381d | 226 | .BR S_ISREG (m) |
fea681da MK |
227 | is it a regular file? |
228 | .TP | |
c91e381d | 229 | .BR S_ISDIR (m) |
fea681da MK |
230 | directory? |
231 | .TP | |
c91e381d | 232 | .BR S_ISCHR (m) |
fea681da MK |
233 | character device? |
234 | .TP | |
c91e381d | 235 | .BR S_ISBLK (m) |
fea681da MK |
236 | block device? |
237 | .TP | |
c91e381d | 238 | .BR S_ISFIFO (m) |
da2d9dad | 239 | FIFO (named pipe)? |
fea681da | 240 | .TP |
c91e381d | 241 | .BR S_ISLNK (m) |
fea681da MK |
242 | symbolic link? (Not in POSIX.1-1996.) |
243 | .TP | |
c91e381d | 244 | .BR S_ISSOCK (m) |
fea681da MK |
245 | socket? (Not in POSIX.1-1996.) |
246 | .RE | |
247 | .PP | |
248 | The following flags are defined for the | |
249 | .I st_mode | |
250 | field: | |
bd191423 | 251 | .in +4n |
fea681da | 252 | .TS |
c91e381d | 253 | lB l l. |
10f5f294 | 254 | S_IFMT 0170000 bit mask for the file type bit fields |
fea681da MK |
255 | S_IFSOCK 0140000 socket |
256 | S_IFLNK 0120000 symbolic link | |
257 | S_IFREG 0100000 regular file | |
258 | S_IFBLK 0060000 block device | |
259 | S_IFDIR 0040000 directory | |
260 | S_IFCHR 0020000 character device | |
da2d9dad | 261 | S_IFIFO 0010000 FIFO |
fea681da | 262 | S_ISUID 0004000 set UID bit |
da2d9dad | 263 | S_ISGID 0002000 set-group-ID bit (see below) |
fea681da MK |
264 | S_ISVTX 0001000 sticky bit (see below) |
265 | S_IRWXU 00700 mask for file owner permissions | |
266 | S_IRUSR 00400 owner has read permission | |
267 | S_IWUSR 00200 owner has write permission | |
268 | S_IXUSR 00100 owner has execute permission | |
269 | S_IRWXG 00070 mask for group permissions | |
270 | S_IRGRP 00040 group has read permission | |
271 | S_IWGRP 00020 group has write permission | |
272 | S_IXGRP 00010 group has execute permission | |
273 | S_IRWXO 00007 mask for permissions for others (not in group) | |
274 | S_IROTH 00004 others have read permission | |
704a18f0 | 275 | S_IWOTH 00002 others have write permission |
fea681da MK |
276 | S_IXOTH 00001 others have execute permission |
277 | .TE | |
bd191423 | 278 | .in |
fea681da | 279 | .P |
2f0af33b MK |
280 | The set-group-ID bit |
281 | .RB ( S_ISGID ) | |
282 | has several special uses. | |
fea681da MK |
283 | For a directory it indicates that BSD semantics is to be used |
284 | for that directory: files created there inherit their group ID from | |
285 | the directory, not from the effective group ID of the creating process, | |
2f0af33b MK |
286 | and directories created there will also get the |
287 | .B S_ISGID | |
288 | bit set. | |
66ee0c7e | 289 | For a file that does not have the group execution bit |
2f0af33b MK |
290 | .RB ( S_IXGRP ) |
291 | set, | |
da2d9dad | 292 | the set-group-ID bit indicates mandatory file/record locking. |
fea681da | 293 | .P |
2d986c92 | 294 | The sticky bit |
2f0af33b MK |
295 | .RB ( S_ISVTX ) |
296 | on a directory means that a file | |
fea681da MK |
297 | in that directory can be renamed or deleted only by the owner |
298 | of the file, by the owner of the directory, and by a privileged | |
299 | process. | |
300 | .SH "RETURN VALUE" | |
c13182ef MK |
301 | On success, zero is returned. |
302 | On error, \-1 is returned, and | |
fea681da MK |
303 | .I errno |
304 | is set appropriately. | |
305 | .SH ERRORS | |
306 | .TP | |
307 | .B EACCES | |
308 | Search permission is denied for one of the directories | |
309 | in the path prefix of | |
da2d9dad | 310 | .IR path . |
fea681da | 311 | (See also |
ad7cc990 | 312 | .BR path_resolution (7).) |
fea681da MK |
313 | .TP |
314 | .B EBADF | |
d3b03141 | 315 | .I fd |
fea681da MK |
316 | is bad. |
317 | .TP | |
318 | .B EFAULT | |
319 | Bad address. | |
320 | .TP | |
321 | .B ELOOP | |
322 | Too many symbolic links encountered while traversing the path. | |
323 | .TP | |
324 | .B ENAMETOOLONG | |
325 | File name too long. | |
326 | .TP | |
327 | .B ENOENT | |
5cf0b3b4 | 328 | A component of |
da2d9dad | 329 | .I path |
5cf0b3b4 MK |
330 | does not exist, or |
331 | .I path | |
332 | is an empty string. | |
fea681da MK |
333 | .TP |
334 | .B ENOMEM | |
75b94dc3 | 335 | Out of memory (i.e., kernel memory). |
fea681da MK |
336 | .TP |
337 | .B ENOTDIR | |
94ea1e9d | 338 | A component of the path prefix of |
5cf0b3b4 MK |
339 | .I path |
340 | is not a directory. | |
9dcc4605 MK |
341 | .TP |
342 | .B EOVERFLOW | |
343 | .RB ( stat ()) | |
344 | .I path | |