| blob | e70178b9fda2edfe532e12a4b1d8d4b44ae71d82 |
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 .\"
25 .TH INODE 7 2021-03-22 "Linux" "Linux Programmer's Manual"
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.
39 .PP
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
49 .IP
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
58 .IP
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
67 .IP
68 See the discussion of file type and mode, below.
69 .TP
70 Link count
71 \fIstat.st_nlink\fP; \fIstatx.stx_nlink\fP
72 .IP
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
80 .IP
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
89 .IP
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,
94 depending on whether or not the set-group-ID bit
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
101 .IP
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
107 .IP
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
115 .IP
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
122 .IP
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.)
128 .IP
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
142 .IP
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
155 .IP
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
175 .IP
176 The file's creation timestamp.
177 This is set on file creation and not changed subsequently.
178 .IP
179 The btime timestamp was not historically present on UNIX systems
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)
184 \fIstat.st_mtime\fP; \fIstatx.stx_mtime\fP
185 .IP
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
203 .IP
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
208 The timestamp fields report time measured with a zero point at the
209 .IR Epoch ,
210 1970-01-01 00:00:00 +0000, UTC (see
211 .BR time (7)).
212 .PP
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.
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.
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.
243 .PP
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
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:
272 .PP
273 .in +4n
274 .EX
275 stat(pathname, &sb);
276 if ((sb.st_mode & S_IFMT) == S_IFREG) {
277 /* Handle regular file */
278 }
279 .EE
280 .in
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:
311 .PP
312 .in +4n
313 .EX
314 stat(pathname, &sb);
315 if (S_ISREG(sb.st_mode)) {
316 /* Handle regular file */
317 }
318 .EE
319 .in
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.
337 .PP
338 The definition of
339 .BR S_IFSOCK
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
343 .BR _XOPEN_SOURCE
344 and
345 .BR _XOPEN_SOURCE_EXTENDED .
346 .PP
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
355 with a value of 500 or greater,
356 .BR _POSIX_C_SOURCE
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 .
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
367 .nh
368 .ad l
369 .TS
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}
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}
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}
407 S_IRWXO 00007 T{
408 others (not in group) have read, write, and execute permission
409 T}
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}
419 .TE
420 .ad
421 .hy
422 .in
423 .PP
424 The set-group-ID bit
425 .RB ( S_ISGID )
426 has several special uses.
427 For a directory, it indicates that BSD semantics are to be used
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.
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).
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.
440 .PP
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).
459 .PP
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 and
470 .B S_ISVTX
471 constants, but instead specified the use of
472 the macros
473 .BR S_ISDIR ()
474 and so on.
475 The
476 .BR S_IF*
477 constants are present in POSIX.1-2001 and later.
478 .PP
479 The
480 .BR S_ISLNK ()
481 and
482 .BR S_ISSOCK ()
483 macros were not in
484 POSIX.1-1996, but both are present in POSIX.1-2001;
485 the former is from SVID 4, the latter from SUSv2.
486 .PP
487 UNIX\ V7 (and later systems) had
488 .BR S_IREAD ,
489 .BR S_IWRITE ,
490 .BR S_IEXEC ,
491 and
492 where POSIX
493 prescribes the synonyms
494 .BR S_IRUSR ,
495 .BR S_IWUSR ,
496 and
497 .BR S_IXUSR .
498 .SH NOTES
499 For pseudofiles that are autogenerated by the kernel, the file size
500 (\fIstat.st_size\fP; \fIstatx.stx_size\fP)
501 reported by the kernel is not accurate.
502 For example, the value 0 is returned for many files under the
503 .I /proc
504 directory,
505 while various files under
506 .IR /sys
507 report a size of 4096 bytes, even though the file content is smaller.
508 For such files, one should simply try to read as many bytes as possible
509 (and append \(aq\e0\(aq to the returned buffer
510 if it is to be interpreted as a string).
511 .SH SEE ALSO
512 .BR stat (1),
513 .BR stat (2),
514 .BR statx (2),
515 .BR symlink (7)