]>
Commit | Line | Data |
---|---|---|
b48c7572 MK |
1 | '\" t |
2 | .\" Copyright (c) 2017 Michael Kerrisk <mtk.manpages@gmail.com> | |
3 | .\" | |
4 | .\" %%%LICENSE_START(VERBATIM) | |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
24 | .\" %%%LICENSE_END | |
25 | .\" | |
4b8c67d9 | 26 | .TH INODE 7 2017-09-15 "Linux" "Linux Programmer's Manual" |
b48c7572 MK |
27 | .SH NAME |
28 | inode \- file inode information | |
29 | .SH DESCRIPTION | |
30 | Each file has an inode containing metadata about the file. | |
31 | An application can retrieve this metadata using | |
32 | .BR stat (2) | |
33 | (or related calls), which returns a | |
34 | .I stat | |
35 | structure, or | |
36 | .BR statx (2), | |
37 | which returns a | |
38 | .I statx | |
39 | structure. | |
a721e8b2 | 40 | .PP |
b48c7572 MK |
41 | The following is a list of the information typically found in, |
42 | or associated with, the file inode, | |
43 | with the names of the corresponding structure fields returned by | |
44 | .BR stat (2) | |
45 | and | |
46 | .BR statx (2): | |
47 | .TP | |
48 | Device where inode resides | |
49 | \fIstat.st_dev\fP; \fIstatx.stx_dev_minor\fP and \fIstatx.stx_dev_major\fP | |
a721e8b2 | 50 | .IP |
b48c7572 MK |
51 | Each inode (as well as the associated file) resides in a filesystem |
52 | that is hosted on a device. | |
53 | That device is identified by the combination of its major ID | |
54 | (which identifies the general class of device) | |
55 | and minor ID (which identifies a specific instance in the general class). | |
56 | .TP | |
57 | Inode number | |
58 | \fIstat.st_ino\fP; \fIstatx.stx_ino\fP | |
a721e8b2 | 59 | .IP |
b48c7572 MK |
60 | Each file in a filesystem has a unique inode number. |
61 | Inode numbers are guaranteed to be unique only within a filesystem | |
62 | (i.e., the same inode numbers may be used by different filesystems, | |
63 | which is the reason that hard links may not cross filesystem boundaries). | |
64 | This field contains the file's inode number. | |
65 | .TP | |
66 | File type and mode | |
67 | \fIstat.st_mode\fP; \fIstatx.stx_mode\fP | |
a721e8b2 | 68 | .IP |
b48c7572 MK |
69 | See the discussion of file type and mode, below. |
70 | .TP | |
71 | Link count | |
72 | \fIstat.st_nlink\fP; \fIstatx.stx_nlink\fP | |
a721e8b2 | 73 | .IP |
b48c7572 MK |
74 | This field contains the number of hard links to the file. |
75 | Additional links to an existing file are created using | |
76 | .BR link (2). | |
77 | .TP | |
78 | User ID | |
79 | .I st_uid | |
80 | \fIstat.st_uid\fP; \fIstatx.stx_uid\fP | |
a721e8b2 | 81 | .IP |
b48c7572 MK |
82 | This field records the user ID of the owner of the file. |
83 | For newly created files, | |
84 | the file user ID is the effective user ID of the creating process. | |
85 | The user ID of a file can be changed using | |
86 | .BR chown (2). | |
87 | .TP | |
88 | Group ID | |
89 | \fIstat.st_gid\fP; \fIstatx.stx_gid\fP | |
a721e8b2 | 90 | .IP |
b48c7572 MK |
91 | The inode records the ID of the group owner of the file. |
92 | For newly created files, | |
93 | the file group ID is either the group ID of the parent directory or | |
94 | the effective group ID of the creating process, | |
b132d423 | 95 | depending on whether or not the set-group-ID bit |
b48c7572 MK |
96 | is set on the parent directory (see below). |
97 | The group ID of a file can be changed using | |
98 | .BR chown (2). | |
99 | .TP | |
100 | Device represented by this inode | |
101 | \fIstat.st_rdev\fP; \fIstatx.stx_rdev_minor\fP and \fIstatx.stx_rdev_major\fP | |
a721e8b2 | 102 | .IP |
b48c7572 MK |
103 | If this file (inode) represents a device, |
104 | then the inode records the major and minor ID of that device. | |
105 | .TP | |
106 | File size | |
107 | \fIstat.st_size\fP; \fIstatx.stx_size\fP | |
a721e8b2 | 108 | .IP |
b48c7572 MK |
109 | This field gives the size of the file (if it is a regular |
110 | file or a symbolic link) in bytes. | |
111 | The size of a symbolic link is the length of the pathname | |
112 | it contains, without a terminating null byte. | |
113 | .TP | |
114 | Preferred block size for I/O | |
115 | \fIstat.st_blksize\fP; \fIstatx.stx_blksize\fP | |
a721e8b2 | 116 | .IP |
b48c7572 MK |
117 | This field gives the "preferred" blocksize for efficient filesystem I/O. |
118 | (Writing to a file in smaller chunks may cause | |
119 | an inefficient read-modify-rewrite.) | |
120 | .TP | |
121 | Number of blocks allocated to the file | |
122 | \fIstat.st_blocks\fP; \fIstatx.stx_size\fP | |
a721e8b2 | 123 | .IP |
b48c7572 MK |
124 | This field indicates the number of blocks allocated to the file, |
125 | 512-byte units, | |
126 | (This may be smaller than | |
127 | .IR st_size /512 | |
128 | when the file has holes.) | |
a721e8b2 | 129 | .IP |
b48c7572 MK |
130 | The POSIX.1 standard notes |
131 | .\" Rationale for sys/stat.h in POSIX.1-2008 | |
132 | that the unit for the | |
133 | .I st_blocks | |
134 | member of the | |
135 | .I stat | |
136 | structure is not defined by the standard. | |
137 | On many implementations it is 512 bytes; | |
138 | on a few systems, a different unit is used, such as 1024. | |
139 | Furthermore, the unit may differ on a per-filesystem basis. | |
140 | .TP | |
141 | Last access timestamp (atime) | |
142 | \fIstat.st_atime\fP; \fIstatx.stx_atime\fP | |
a721e8b2 | 143 | .IP |
b48c7572 MK |
144 | This is the file's last access timestamp. |
145 | It is changed by file accesses, for example, by | |
146 | .BR execve (2), | |
147 | .BR mknod (2), | |
148 | .BR pipe (2), | |
149 | .BR utime (2), | |
150 | and | |
151 | .BR read (2) | |
152 | (of more than zero bytes). | |
153 | Other interfaces, such as | |
154 | .BR mmap (2), | |
155 | may or may not update the atime timestamp | |
a721e8b2 | 156 | .IP |
b48c7572 MK |
157 | Some filesystem types allow mounting in such a way that file |
158 | and/or directory accesses do not cause an update of the atime timestamp. | |
159 | (See | |
160 | .IR noatime , | |
161 | .IR nodiratime , | |
162 | and | |
163 | .I relatime | |
164 | in | |
165 | .BR mount (8), | |
166 | and related information in | |
167 | .BR mount (2).) | |
168 | In addition, the atime timestamp | |
169 | is not updated if a file is opened with the | |
170 | .BR O_NOATIME | |
171 | flag; see | |
172 | .BR open (2). | |
173 | .TP | |
174 | File creation (birth) timestamp (btime) | |
175 | (not returned in the \fIstat\fP structure); \fIstatx.stx_btime\fP | |
a721e8b2 | 176 | .IP |
b48c7572 MK |
177 | The file's creation timestamp. |
178 | This is set on file creation and not changed subsequently. | |
a721e8b2 | 179 | .IP |
b132d423 | 180 | The btime timestamp was not historically present on UNIX systems |
b48c7572 MK |
181 | and is not currently supported by most Linux filesystems. |
182 | .\" FIXME Is it supported on ext4 and XFS? | |
183 | .TP | |
184 | Last modification timestamp (mtime) | |
e1b1b898 | 185 | \fIstat.st_mtime\fP; \fIstatx.stx_mtime\fP |
a721e8b2 | 186 | .IP |
b48c7572 MK |
187 | This is the file's last modification timestamp. |
188 | It is changed by file modifications, for example, by | |
189 | .BR mknod (2), | |
190 | .BR truncate (2), | |
191 | .BR utime (2), | |
192 | and | |
193 | .BR write (2) | |
194 | (of more than zero bytes). | |
195 | Moreover, the mtime timestamp | |
196 | of a directory is changed by the creation or deletion of files | |
197 | in that directory. | |
198 | The mtime timestamp is | |
199 | .I not | |
200 | changed for changes in owner, group, hard link count, or mode. | |
201 | .TP | |
202 | Last status change timestamp (ctime) | |
203 | \fIstat.st_ctime\fP; \fIstatx.stx_ctime\fP | |
a721e8b2 | 204 | .IP |
b48c7572 MK |
205 | This is the file's last status change timestamp. |
206 | It is changed by writing or by setting inode information | |
207 | (i.e., owner, group, link count, mode, etc.). | |
208 | .PP | |
0f0a2e4d MK |
209 | The timestamp fields report time measured with a zero point at the |
210 | .IR Epoch , | |
211 | 1970-01-02 00:00:00 +0000, UTC (see | |
212 | .BR time (7)). | |
213 | .PP | |
b48c7572 MK |
214 | Nanosecond timestamps are supported on XFS, JFS, Btrfs, and |
215 | ext4 (since Linux 2.6.23). | |
216 | .\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80 | |
217 | Nanosecond timestamps are not supported in ext2, ext3, and Reiserfs. | |
59c0f675 MK |
218 | In order to return timestamps with nanosecond precision, |
219 | the timestamp fields in the | |
220 | .I stat | |
221 | and | |
222 | .I statx | |
223 | structures are defined as structures that include a nanosecond component. | |
224 | See | |
225 | .BR stat (2) | |
226 | and | |
227 | .BR statx (2) | |
228 | for details. | |
b48c7572 MK |
229 | On filesystems that do not support subsecond timestamps, |
230 | the nanosecond fields in the | |
231 | .I stat | |
232 | and | |
233 | .I statx | |
234 | structures are returned with the value 0. | |
235 | .\" | |
236 | .SS The file type and mode | |
237 | The | |
238 | .I stat.st_mode | |
239 | field (for | |
240 | .BR statx (2), | |
241 | the | |
242 | .I statx.stx_mode | |
243 | field) contains the file type and mode. | |
a721e8b2 | 244 | .PP |
b48c7572 MK |
245 | POSIX refers to the |
246 | .I stat.st_mode | |
247 | bits corresponding to the mask | |
248 | .B S_IFMT | |
249 | (see below) as the | |
250 | .IR "file type" , | |
251 | the 12 bits corresponding to the mask 07777 as the | |
252 | .IR "file mode bits" | |
253 | and the least significant 9 bits (0777) as the | |
254 | .IR "file permission bits" . | |
255 | .PP | |
256 | The following mask values are defined for the file type: | |
257 | .in +4n | |
258 | .TS | |
259 | lB l l. | |
260 | S_IFMT 0170000 bit mask for the file type bit field | |
261 | ||
262 | S_IFSOCK 0140000 socket | |
263 | S_IFLNK 0120000 symbolic link | |
264 | S_IFREG 0100000 regular file | |
265 | S_IFBLK 0060000 block device | |
266 | S_IFDIR 0040000 directory | |
267 | S_IFCHR 0020000 character device | |
268 | S_IFIFO 0010000 FIFO | |
269 | .TE | |
270 | .in | |
271 | .PP | |
272 | Thus, to test for a regular file (for example), one could write: | |
a721e8b2 | 273 | .PP |
b48c7572 | 274 | .in +4n |
b8302363 | 275 | .EX |
b48c7572 MK |
276 | stat(pathname, &sb); |
277 | if ((sb.st_mode & S_IFMT) == S_IFREG) { | |
278 | /* Handle regular file */ | |
279 | } | |
b8302363 | 280 | .EE |
e646a1ba | 281 | .in |
b48c7572 MK |
282 | .PP |
283 | Because tests of the above form are common, additional | |
284 | macros are defined by POSIX to allow the test of the file type in | |
285 | .I st_mode | |
286 | to be written more concisely: | |
287 | .RS 4 | |
288 | .TP 1.2i | |
289 | .BR S_ISREG (m) | |
290 | is it a regular file? | |
291 | .TP | |
292 | .BR S_ISDIR (m) | |
293 | directory? | |
294 | .TP | |
295 | .BR S_ISCHR (m) | |
296 | character device? | |
297 | .TP | |
298 | .BR S_ISBLK (m) | |
299 | block device? | |
300 | .TP | |
301 | .BR S_ISFIFO (m) | |
302 | FIFO (named pipe)? | |
303 | .TP | |
304 | .BR S_ISLNK (m) | |
305 | symbolic link? (Not in POSIX.1-1996.) | |
306 | .TP | |
307 | .BR S_ISSOCK (m) | |
308 | socket? (Not in POSIX.1-1996.) | |
309 | .RE | |
310 | .PP | |
311 | The preceding code snippet could thus be rewritten as: | |
a721e8b2 | 312 | .PP |
b48c7572 | 313 | .in +4n |
b8302363 | 314 | .EX |
b48c7572 MK |
315 | stat(pathname, &sb); |
316 | if (S_ISREG(sb.st_mode)) { | |
317 | /* Handle regular file */ | |
318 | } | |
b8302363 | 319 | .EE |
e646a1ba | 320 | .in |
b48c7572 MK |
321 | .PP |
322 | The definitions of most of the above file type test macros | |
323 | are provided if any of the following feature test macros is defined: | |
324 | .BR _BSD_SOURCE | |
325 | (in glibc 2.19 and earlier), | |
326 | .BR _SVID_SOURCE | |
327 | (in glibc 2.19 and earlier), | |
328 | or | |
329 | .BR _DEFAULT_SOURCE | |
330 | (in glibc 2.20 and later). | |
331 | In addition, definitions of all of the above macros except | |
332 | .BR S_IFSOCK | |
333 | and | |
334 | .BR S_ISSOCK () | |
335 | are provided if | |
336 | .BR _XOPEN_SOURCE | |
337 | is defined. | |
a721e8b2 | 338 | .PP |
b48c7572 MK |
339 | The definition of |
340 | .BR S_IFSOCK | |
45375b20 MK |
341 | can also be exposed either by defining |
342 | .BR _XOPEN_SOURCE | |
343 | with a value of 500 or greater or (since glibc 2.24) by defining both | |
b48c7572 | 344 | .BR _XOPEN_SOURCE |
45375b20 MK |
345 | and |
346 | .BR _XOPEN_SOURCE_EXTENDED . | |
a721e8b2 | 347 | .PP |
b48c7572 MK |
348 | The definition of |
349 | .BR S_ISSOCK () | |
350 | is exposed if any of the following feature test macros is defined: | |
351 | .BR _BSD_SOURCE | |
352 | (in glibc 2.19 and earlier), | |
353 | .BR _DEFAULT_SOURCE | |
354 | (in glibc 2.20 and later), | |
355 | .BR _XOPEN_SOURCE | |
45375b20 | 356 | with a value of 500 or greater, |
b48c7572 | 357 | .BR _POSIX_C_SOURCE |
45375b20 MK |
358 | with a value of 200112L or greater, or (since glibc 2.24) by defining both |
359 | .BR _XOPEN_SOURCE | |
360 | and | |
361 | .BR _XOPEN_SOURCE_EXTENDED . | |
b48c7572 MK |
362 | .PP |
363 | The following mask values are defined for | |
364 | the file mode component of the | |
365 | .I st_mode | |
366 | field: | |
367 | .in +4n | |
368 | .TS | |
369 | lB l l. | |
d08cb7ae | 370 | S_ISUID 04000 set-user-ID bit (see \fBexecve\fP(2)) |
b48c7572 MK |
371 | S_ISGID 02000 set-group-ID bit (see below) |
372 | S_ISVTX 01000 sticky bit (see below) | |
373 | ||
374 | S_IRWXU 00700 owner has read, write, and execute permission | |
375 | S_IRUSR 00400 owner has read permission | |
376 | S_IWUSR 00200 owner has write permission | |
377 | S_IXUSR 00100 owner has execute permission | |
378 | ||
379 | S_IRWXG 00070 group has read, write, and execute permission | |
380 | S_IRGRP 00040 group has read permission | |
381 | S_IWGRP 00020 group has write permission | |
382 | S_IXGRP 00010 group has execute permission | |
383 | ||
384 | S_IRWXO 00007 T{ | |
385 | others (not in group) have read, write, and execute permission | |
386 | T} | |
387 | S_IROTH 00004 others have read permission | |
388 | S_IWOTH 00002 others have write permission | |
389 | S_IXOTH 00001 others have execute permission | |
390 | .TE | |
391 | .in | |
11ac5b51 | 392 | .PP |
b48c7572 MK |
393 | The set-group-ID bit |
394 | .RB ( S_ISGID ) | |
395 | has several special uses. | |
76028487 | 396 | For a directory, it indicates that BSD semantics are to be used |
b48c7572 MK |
397 | for that directory: files created there inherit their group ID from |
398 | the directory, not from the effective group ID of the creating process, | |
399 | and directories created there will also get the | |
400 | .B S_ISGID | |
401 | bit set. | |
d08cb7ae MK |
402 | For an executable file, the set-group-ID bit causes the effective group ID |
403 | of a process that executes the file to change as described in | |
404 | .BR execve (2). | |
b48c7572 MK |
405 | For a file that does not have the group execution bit |
406 | .RB ( S_IXGRP ) | |
407 | set, | |
408 | the set-group-ID bit indicates mandatory file/record locking. | |
11ac5b51 | 409 | .PP |
b48c7572 MK |
410 | The sticky bit |
411 | .RB ( S_ISVTX ) | |
412 | on a directory means that a file | |
413 | in that directory can be renamed or deleted only by the owner | |
414 | of the file, by the owner of the directory, and by a privileged | |
415 | process. | |
416 | .SH CONFORMING TO | |
417 | If you need to obtain the definition of the | |
418 | .IR blkcnt_t | |
419 | or | |
420 | .IR blksize_t | |
421 | types from | |
422 | .IR <sys/stat.h> , | |
423 | then define | |
424 | .BR _XOPEN_SOURCE | |
425 | with the value 500 or greater (before including | |
426 | .I any | |
427 | header files). | |
dd3568a1 | 428 | .PP |
b48c7572 MK |
429 | POSIX.1-1990 did not describe the |
430 | .BR S_IFMT , | |
431 | .BR S_IFSOCK , | |
432 | .BR S_IFLNK , | |
433 | .BR S_IFREG , | |
434 | .BR S_IFBLK , | |
435 | .BR S_IFDIR , | |
436 | .BR S_IFCHR , | |
437 | .BR S_IFIFO , | |
438 | .B S_ISVTX | |
439 | constants, but instead specified the use of | |
440 | the macros | |
441 | .BR S_ISDIR (), | |
442 | and so on. | |
443 | The | |
444 | .BR S_IF* | |
445 | constants are present in POSIX.1-2001 and later. | |
a721e8b2 | 446 | .PP |
b48c7572 MK |
447 | The |
448 | .BR S_ISLNK () | |
449 | and | |
450 | .BR S_ISSOCK () | |
451 | macros were not in | |
452 | POSIX.1-1996, but both are present in POSIX.1-2001; | |
453 | the former is from SVID 4, the latter from SUSv2. | |
dd3568a1 | 454 | .PP |
b48c7572 MK |
455 | UNIX\ V7 (and later systems) had |
456 | .BR S_IREAD , | |
457 | .BR S_IWRITE , | |
458 | .BR S_IEXEC , | |
459 | where POSIX | |
460 | prescribes the synonyms | |
461 | .BR S_IRUSR , | |
462 | .BR S_IWUSR , | |
463 | .BR S_IXUSR . | |
464 | .SH NOTES | |
465 | For pseudofiles that are autogenerated by the kernel, the file size | |
466 | (\fIstat.st_size\fP; \fIstatx.stx_size\fP) | |
467 | reported by the kernel is not accurate. | |
468 | For example, the value 0 is returned for many files under the | |
469 | .I /proc | |
470 | directory, | |
471 | while various files under | |
472 | .IR /sys | |
473 | report a size of 4096 bytes, even though the file content is smaller. | |
474 | For such files, one should simply try to read as many bytes as possible | |
475 | (and append \(aq\e0\(aq to the returned buffer | |
476 | if it is to be interpreted as a string). | |
b48c7572 MK |
477 | .SH SEE ALSO |
478 | .BR stat (1), | |
479 | .BR stat (2), | |
480 | .BR statx (2), | |
481 | .BR symlink (7) |