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