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