Debian Codegraph @

upstream/debian-unstable/man7/inode.7

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