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