| blob | 7f51600d26d8cbdb1662a26178a8a561b762eebe |
1 .\" $NetBSD: stat.2,v 1.50 2012/01/04 10:53:39 wiz Exp $
2 .\"
3 .\" Copyright (c) 1980, 1991, 1993, 1994
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)stat.2 8.4 (Berkeley) 5/1/95
31 .\"
32 .Dd September 14, 2011
33 .Dt STAT 2
34 .Os
35 .Sh NAME
36 .Nm stat ,
37 .Nm lstat ,
38 .Nm fstat
39 .Nd get file status
40 .Sh LIBRARY
41 .Lb libc
42 .Sh SYNOPSIS
43 .In sys/stat.h
44 .Ft int
45 .Fn stat "const char *path" "struct stat *sb"
46 .Ft int
47 .Fn lstat "const char *path" "struct stat *sb"
48 .Ft int
49 .Fn fstat "int fd" "struct stat *sb"
50 .Sh DESCRIPTION
51 The
52 .Fn stat
53 function obtains information about the file pointed to by
54 .Fa path .
55 Read, write or execute
56 permission of the named file is not required, but all directories
57 listed in the path name leading to the file must be searchable.
58 .Pp
59 The function
60 .Fn lstat
61 is like
62 .Fn stat
63 except in the case where the named file is a symbolic link,
64 in which case
65 .Fn lstat
66 returns information about the link,
67 while
68 .Fn stat
69 returns information about the file the link references.
70 The
71 .Fn fstat
72 function obtains the same information about an open file
73 known by the file descriptor
74 .Fa fd .
75 .Pp
76 The
77 .Fa sb
78 argument is a pointer to a
79 .Fa stat
80 structure
81 as defined by
82 .In sys/stat.h
83 and into which information is placed concerning the file.
84 .Ss The Standard Structure
85 The following standards-compliant fields are defined in the structure:
86 .Bl -column -offset indent \
87 "nlink_t " "st_nlink " "Description"
88 .It Sy Type Ta Sy Entry Ta Sy Description
89 .It Vt dev_t Ta st_dev Ta device ID containing the file
90 .It Vt ino_t Ta st_ino Ta serial number of the file
91 .It Vt mode_t Ta st_mode Ta mode of the file
92 .It Vt nlink_t Ta st_nlink Ta number of hard links to the file
93 .It Vt uid_t Ta st_uid Ta user ID of the owner
94 .It Vt gid_t Ta st_gid Ta group ID of the owner
95 .It Vt dev_t Ta st_rdev Ta device type (character or block special)
96 .It Vt off_t Ta st_size Ta size of the file in bytes
97 .It Vt time_t Ta st_atime Ta time of last access
98 .It Vt time_t Ta st_mtime Ta time of last data modification
99 .It Vt time_t Ta st_ctime Ta time of last file status change
100 .It Vt blksize_t Ta st_blksize Ta preferred I/O block size (fs-specific)
101 .It Vt blkcnt_t Ta st_blocks Ta blocks allocated for the file
102 .El
103 .Pp
104 These are specified in the
105 .St -p1003.1-2004
106 standard.
107 The
108 .Va st_ino
109 and
110 .Va st_dev
111 fields taken together uniquely identify the file within the system.
112 Most of the types are defined in
113 .Xr types 3 .
114 .Pp
115 The time-related fields are:
116 .Bl -tag -width st_blksize -offset indent
117 .It Va st_atime
118 Time when file data was last accessed.
119 Changed by the
120 .Xr mknod 2 ,
121 .Xr utimes 2 ,
122 and
123 .Xr read 2
124 system calls.
125 .It Va st_mtime
126 Time when file data was last modified.
127 Changed by the
128 .Xr mknod 2 ,
129 .Xr utimes 2 ,
130 and
131 .Xr write 2
132 system calls.
133 .It Va st_ctime
134 Time when file status was last changed (file metadata modification).
135 Changed by the
136 .Xr chflags 2 ,
137 .Xr chmod 2 ,
138 .Xr chown 2 ,
139 .Xr link 2 ,
140 .Xr mknod 2 ,
141 .Xr rename 2 ,
142 .Xr unlink 2 ,
143 .Xr utimes 2 ,
144 and
145 .Xr write 2
146 system calls.
147 .El
148 .Pp
149 The size-related fields of the
150 .Fa struct stat
151 are as follows:
152 .Bl -tag -width st_blksize -offset indent
153 .It Va st_size
154 The size of the file in bytes.
155 The meaning of the size reported for a directory is file system
156 dependent.
157 Some file systems (e.g. FFS) return the total size used for the
158 directory metadata, possibly including free slots; others (notably
159 ZFS) return the number of entries in the directory.
160 Some may also return other things or always report zero.
161 .It Va st_blksize
162 The optimal I/O block size for the file.
163 .It Va st_blocks
164 The actual number of blocks allocated for the file in 512-byte units.
165 As short symbolic links are stored in the inode, this number may
166 be zero.
167 .El
168 .Pp
169 The status information word
170 .Fa st_mode
171 contains bits that define the access mode (see
172 .Xr chmod 2 )
173 and the type (see
174 .Xr dirent 3 )
175 of the file.
176 The following macros can be used to test
177 whether a file is of the specified type.
178 The value
179 .Fa m
180 supplied to the macros is the value of
181 .Va st_mode .
182 .Bl -tag -width "S_ISSOCK(m)" -offset indent
183 .It Fn S_ISBLK "m"
184 Test for a block special file.
185 .It Fn S_ISCHR "m"
186 Test for a character special file.
187 .It Fn S_ISDIR "m"
188 Test for a directory.
189 .It Fn S_ISFIFO "m"
190 Test for a pipe or FIFO special file.
191 .It Fn S_ISREG "m"
192 Test for a regular file.
193 .It Fn S_ISLNK "m"
194 Test for a symbolic link.
195 .It Fn S_ISSOCK "m"
196 Test for a socket.
197 .El
198 .Pp
199 The macros evaluate to a non-zero value if the test
200 is true or to the value 0 if the test is false.
201 .Ss NetBSD Extensions
202 The following additional
203 .Nx
204 specific fields are present:
205 .Bl -column -offset indent \
206 "uint32_t" "st_birthtimensec" "Description"
207 .It Sy Type Ta Sy Entry Ta Sy Description
208 .It Vt long Ta st_atimensec Ta last access (nanoseconds)
209 .It Vt long Ta st_mtimensec Ta last modification (nanoseconds)
210 .It Vt long Ta st_ctimensec Ta last status change (nanoseconds)
211 .It Vt time_t Ta st_birthtime Ta time of inode creation
212 .It Vt long Ta st_birthtimensec Ta inode creation (nanoseconds)
213 .It Vt uint32_t Ta st_flags Ta user defined flags for the file
214 .It Vt uint32_t Ta st_gen Ta file generation number
215 .\"
216 .\" XXX: What is this?
217 .\"
218 .It Vt uint32_t Ta st_spare[2] Ta implementation detail
219 .El
220 .Pp
221 However, if
222 _NETBSD_SOURCE
223 is furthermore defined, instead of the above,
224 the following are present in the structure:
225 .Bl -column -offset indent \
226 "struct timespec " "st_birthtimensec" "Description"
227 .It Sy Type Ta Sy Entry Ta Sy Description
228 .It Vt struct timespec Ta st_atimespec Ta time of last access
229 .It Vt struct timespec Ta st_mtimespec Ta time of last modification
230 .It Vt struct timespec Ta st_birthtimespec Ta time of creation
231 .It Vt uint32_t Ta st_flags Ta user defined flags
232 .It Vt uint32_t Ta st_gen Ta file generation number
233 .\"
234 .\" XXX: What is this?
235 .\"
236 .It Vt uint32_t Ta st_spare[2] Ta implementation detail
237 .El
238 .Pp
239 In this case the following macros are provided for convenience:
240 .Bd -literal -offset indent
241 #if defined(_NETBSD_SOURCE)
242 #define st_atime st_atimespec.tv_sec
243 #define st_atimensec st_atimespec.tv_nsec
244 #define st_mtime st_mtimespec.tv_sec
245 #define st_mtimensec st_mtimespec.tv_nsec
246 #define st_ctime st_ctimespec.tv_sec
247 #define st_ctimensec st_ctimespec.tv_nsec
248 #define st_birthtime st_birthtimespec.tv_sec
249 #define st_birthtimensec st_birthtimespec.tv_nsec
250 #endif
251 .Ed
252 .Pp
253 The status information word
254 .Fa st_flags
255 has the following bits:
256 .Bl -column -offset indent \
257 "struct timespec " "st_birthtimensec"
258 .It Sy Constant Ta Sy Description
259 .It Dv UF_NODUMP Ta do not dump a file
260 .It Dv UF_IMMUTABLE Ta file may not be changed
261 .It Dv UF_APPEND Ta writes to file may only append
262 .It Dv UF_OPAQUE Ta directory is opaque wrt. union
263 .It Dv SF_ARCHIVED Ta file is archived
264 .It Dv SF_IMMUTABLE Ta file may not be changed
265 .It Dv SF_APPEND Ta writes to file may only append
266 .El
267 .Pp
268 For a description of the flags, see
269 .Xr chflags 2 .
270 .Sh RETURN VALUES
271 Upon successful completion a value of 0 is returned.
272 Otherwise, a value of \-1 is returned and
273 .Va errno
274 is set to indicate the error.
275 .Sh COMPATIBILITY
276 Previous versions of the system used different types for the
277 .Li st_dev ,
278 .Li st_uid ,
279 .Li st_gid ,
280 .Li st_rdev ,
281 .Li st_size ,
282 .Li st_blksize
283 and
284 .Li st_blocks
285 fields.
286 .Sh ERRORS
287 .Fn stat
288 and
289 .Fn lstat
290 will fail if:
291 .Bl -tag -width Er
292 .It Bq Er EACCES
293 Search permission is denied for a component of the path prefix.
294 .It Bq Er EBADF
295 A badly formed vnode was encountered.
296 This can happen if a file system information node is incorrect.
297 .It Bq Er EFAULT
298 .Fa sb
299 or
300 .Em name
301 points to an invalid address.
302 .It Bq Er EIO
303 An I/O error occurred while reading from or writing to the file system.
304 .It Bq Er ELOOP
305 Too many symbolic links were encountered in translating the pathname.
306 .It Bq Er ENAMETOOLONG
307 A component of a pathname exceeded
308 .Brq Dv NAME_MAX
309 characters, or an entire path name exceeded
310 .Brq Dv PATH_MAX
311 characters.
312 .It Bq Er ENOENT
313 The named file does not exist.
314 .It Bq Er ENOTDIR
315 A component of the path prefix is not a directory.
316 .It Bq Er ENXIO
317 The named file is a character special or block
318 special file, and the device associated with this special file
319 does not exist.
320 .El
321 .Pp
322 .Fn fstat
323 will fail if:
324 .Bl -tag -width Er
325 .It Bq Er EBADF
326 .Fa fd
327 is not a valid open file descriptor.
328 .It Bq Er EFAULT
329 .Fa sb
330 points to an invalid address.
331 .It Bq Er EIO
332 An I/O error occurred while reading from or writing to the file system.
333 .El
334 .Sh SEE ALSO
335 .Xr chflags 2 ,
336 .Xr chmod 2 ,
337 .Xr chown 2 ,
338 .Xr utimes 2 ,
339 .Xr dirent 3 ,
340 .Xr types 3 ,
341 .Xr symlink 7
342 .Sh STANDARDS
343 The described functions conform to
344 .St -p1003.1-2004 .
345 .Sh HISTORY
346 A
347 .Fn stat
348 function call appeared in
349 .At v2 .
350 A
351 .Fn lstat
352 function call appeared in
353 .Bx 4.2 .
354 .Sh BUGS
355 Applying
356 .Fn fstat
357 to a socket (and thus to a pipe)
358 returns a zero'd buffer,
359 except for the blocksize field,
360 and a unique device and file serial number.