summaryrefslogtreecommitdiffstats
path: root/man7/inode.7
blob: 7054fe8b8d20afe7479c29ba2bdb2c2a3035bb03 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
'\" t
.\" Copyright (c) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH inode 7 2023-10-31 "Linux man-pages 6.7"
.SH NAME
inode \- file inode information
.SH DESCRIPTION
Each file has an inode containing metadata about the file.
An application can retrieve this metadata using
.BR stat (2)
(or related calls), which returns a
.I stat
structure, or
.BR statx (2),
which returns a
.I statx
structure.
.P
The following is a list of the information typically found in,
or associated with, the file inode,
with the names of the corresponding structure fields returned by
.BR stat (2)
and
.BR statx (2):
.TP
Device where inode resides
\fIstat.st_dev\fP; \fIstatx.stx_dev_minor\fP and \fIstatx.stx_dev_major\fP
.IP
Each inode (as well as the associated file) resides in a filesystem
that is hosted on a device.
That device is identified by the combination of its major ID
(which identifies the general class of device)
and minor ID (which identifies a specific instance in the general class).
.TP
Inode number
\fIstat.st_ino\fP; \fIstatx.stx_ino\fP
.IP
Each file in a filesystem has a unique inode number.
Inode numbers are guaranteed to be unique only within a filesystem
(i.e., the same inode numbers may be used by different filesystems,
which is the reason that hard links may not cross filesystem boundaries).
This field contains the file's inode number.
.TP
File type and mode
\fIstat.st_mode\fP; \fIstatx.stx_mode\fP
.IP
See the discussion of file type and mode, below.
.TP
Link count
\fIstat.st_nlink\fP; \fIstatx.stx_nlink\fP
.IP
This field contains the number of hard links to the file.
Additional links to an existing file are created using
.BR link (2).
.TP
User ID
\fIstat.st_uid\fP; \fIstatx.stx_uid\fP
.IP
This field records the user ID of the owner of the file.
For newly created files,
the file user ID is the effective user ID of the creating process.
The user ID of a file can be changed using
.BR chown (2).
.TP
Group ID
\fIstat.st_gid\fP; \fIstatx.stx_gid\fP
.IP
The inode records the ID of the group owner of the file.
For newly created files,
the file group ID is either the group ID of the parent directory or
the effective group ID of the creating process,
depending on whether or not the set-group-ID bit
is set on the parent directory (see below).
The group ID of a file can be changed using
.BR chown (2).
.TP
Device represented by this inode
\fIstat.st_rdev\fP; \fIstatx.stx_rdev_minor\fP and \fIstatx.stx_rdev_major\fP
.IP
If this file (inode) represents a device,
then the inode records the major and minor ID of that device.
.TP
File size
\fIstat.st_size\fP; \fIstatx.stx_size\fP
.IP
This field gives the size of the file (if it is a regular
file or a symbolic link) in bytes.
The size of a symbolic link is the length of the pathname
it contains, without a terminating null byte.
.TP
Preferred block size for I/O
\fIstat.st_blksize\fP; \fIstatx.stx_blksize\fP
.IP
This field gives the "preferred" blocksize for efficient filesystem I/O.
(Writing to a file in smaller chunks may cause
an inefficient read-modify-rewrite.)
.TP
Number of blocks allocated to the file
\fIstat.st_blocks\fP; \fIstatx.stx_blocks\fP
.IP
This field indicates the number of blocks allocated to the file,
512-byte units,
(This may be smaller than
.IR st_size /512
when the file has holes.)
.IP
The POSIX.1 standard notes
.\" Rationale for sys/stat.h in POSIX.1-2008
that the unit for the
.I st_blocks
member of the
.I stat
structure is not defined by the standard.
On many  implementations it is 512 bytes;
on a few systems, a different unit is used, such as 1024.
Furthermore, the unit may differ on a per-filesystem basis.
.TP
Last access timestamp (atime)
\fIstat.st_atime\fP; \fIstatx.stx_atime\fP
.IP
This is the file's last access timestamp.
It is changed by file accesses, for example, by
.BR execve (2),
.BR mknod (2),
.BR pipe (2),
.BR utime (2),
and
.BR read (2)
(of more than zero bytes).
Other interfaces, such as
.BR mmap (2),
may or may not update the atime timestamp
.IP
Some filesystem types allow mounting in such a way that file
and/or directory accesses do not cause an update of the atime timestamp.
(See
.IR noatime ,
.IR nodiratime ,
and
.I relatime
in
.BR mount (8),
and related information in
.BR mount (2).)
In addition, the atime timestamp
is not updated if a file is opened with the
.B O_NOATIME
flag; see
.BR open (2).
.TP
File creation (birth) timestamp (btime)
(not returned in the \fIstat\fP structure); \fIstatx.stx_btime\fP
.IP
The file's creation timestamp.
This is set on file creation and not changed subsequently.
.IP
The btime timestamp was not historically present on UNIX systems
and is not currently supported by most Linux filesystems.
.\" FIXME Is it supported on ext4 and XFS?
.TP
Last modification timestamp (mtime)
\fIstat.st_mtime\fP; \fIstatx.stx_mtime\fP
.IP
This is the file's last modification timestamp.
It is changed by file modifications, for example, by
.BR mknod (2),
.BR truncate (2),
.BR utime (2),
and
.BR write (2)
(of more than zero bytes).
Moreover, the mtime timestamp
of a directory is changed by the creation or deletion of files
in that directory.
The mtime timestamp is
.I not
changed for changes in owner, group, hard link count, or mode.
.TP
Last status change timestamp (ctime)
\fIstat.st_ctime\fP; \fIstatx.stx_ctime\fP
.IP
This is the file's last status change timestamp.
It is changed by writing or by setting inode information
(i.e., owner, group, link count, mode, etc.).
.P
The timestamp fields report time measured with a zero point at the
.IR Epoch ,
1970-01-01 00:00:00 +0000, UTC (see
.BR time (7)).
.P
Nanosecond timestamps are supported on XFS, JFS, Btrfs, and
ext4 (since Linux 2.6.23).
.\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80
Nanosecond timestamps are not supported in ext2, ext3, and Reiserfs.
In order to return timestamps with nanosecond precision,
the timestamp fields in the
.I stat
and
.I statx
structures are defined as structures that include a nanosecond component.
See
.BR stat (2)
and
.BR statx (2)
for details.
On filesystems that do not support subsecond timestamps,
the nanosecond fields in the
.I stat
and
.I statx
structures are returned with the value 0.
.\"
.SS The file type and mode
The
.I stat.st_mode
field (for
.BR statx (2),
the
.I statx.stx_mode
field) contains the file type and mode.
.P
POSIX refers to the
.I stat.st_mode
bits corresponding to the mask
.B S_IFMT
(see below) as the
.IR "file type" ,
the 12 bits corresponding to the mask 07777 as the
.I file mode bits
and the least significant 9 bits (0777) as the
.IR "file permission bits" .
.P
The following mask values are defined for the file type:
.in +4n
.TS
lB l l.
S_IFMT	0170000	bit mask for the file type bit field

S_IFSOCK	0140000	socket
S_IFLNK	0120000	symbolic link
S_IFREG	0100000	regular file
S_IFBLK	0060000	block device
S_IFDIR	0040000	directory
S_IFCHR	0020000	character device
S_IFIFO	0010000	FIFO
.TE
.in
.P
Thus, to test for a regular file (for example), one could write:
.P
.in +4n
.EX
stat(pathname, &sb);
if ((sb.st_mode & S_IFMT) == S_IFREG) {
    /* Handle regular file */
}
.EE
.in
.P
Because tests of the above form are common, additional
macros are defined by POSIX to allow the test of the file type in
.I st_mode
to be written more concisely:
.RS 4
.TP 1.2i
.BR S_ISREG (m)
is it a regular file?
.TP
.BR S_ISDIR (m)
directory?
.TP
.BR S_ISCHR (m)
character device?
.TP
.BR S_ISBLK (m)
block device?
.TP
.BR S_ISFIFO (m)
FIFO (named pipe)?
.TP
.BR S_ISLNK (m)
symbolic link?  (Not in POSIX.1-1996.)
.TP
.BR S_ISSOCK (m)
socket?  (Not in POSIX.1-1996.)
.RE
.P
The preceding code snippet could thus be rewritten as:
.P
.in +4n
.EX
stat(pathname, &sb);
if (S_ISREG(sb.st_mode)) {
    /* Handle regular file */
}
.EE
.in
.P
The definitions of most of the above file type test macros
are provided if any of the following feature test macros is defined:
.B _BSD_SOURCE
(in glibc 2.19 and earlier),
.B _SVID_SOURCE
(in glibc 2.19 and earlier),
or
.B _DEFAULT_SOURCE
(in glibc 2.20 and later).
In addition, definitions of all of the above macros except
.B S_IFSOCK
and
.BR S_ISSOCK ()
are provided if
.B _XOPEN_SOURCE
is defined.
.P
The definition of
.B S_IFSOCK
can also be exposed either by defining
.B _XOPEN_SOURCE
with a value of 500 or greater or (since glibc 2.24) by defining both
.B _XOPEN_SOURCE
and
.BR _XOPEN_SOURCE_EXTENDED .
.P
The definition of
.BR S_ISSOCK ()
is exposed if any of the following feature test macros is defined:
.B _BSD_SOURCE
(in glibc 2.19 and earlier),
.B _DEFAULT_SOURCE
(in glibc 2.20 and later),
.B _XOPEN_SOURCE
with a value of 500 or greater,
.B _POSIX_C_SOURCE
with a value of 200112L or greater, or (since glibc 2.24) by defining both
.B _XOPEN_SOURCE
and
.BR _XOPEN_SOURCE_EXTENDED .
.P
The following mask values are defined for
the file mode component of the
.I st_mode
field:
.in +4n
.TS
lB l lx.
S_ISUID	  04000	T{
set-user-ID bit (see \fBexecve\fP(2))
T}
S_ISGID	  02000	T{
set-group-ID bit (see below)
T}
S_ISVTX	  01000	T{
sticky bit (see below)
T}

S_IRWXU	  00700	T{
owner has read, write, and execute permission
T}
S_IRUSR	  00400	T{
owner has read permission
T}
S_IWUSR	  00200	T{
owner has write permission
T}
S_IXUSR	  00100	T{
owner has execute permission
T}

S_IRWXG	  00070	T{
group has read, write, and execute permission
T}
S_IRGRP	  00040	T{
group has read permission
T}
S_IWGRP	  00020	T{
group has write permission
T}
S_IXGRP	  00010	T{
group has execute permission
T}

S_IRWXO	  00007	T{
others (not in group) have read, write, and execute permission
T}
S_IROTH	  00004	T{
others have read permission
T}
S_IWOTH	  00002	T{
others have write permission
T}
S_IXOTH	  00001	T{
others have execute permission
T}
.TE
.in
.P
The set-group-ID bit
.RB ( S_ISGID )
has several special uses.
For a directory, it indicates that BSD semantics are to be used
for that directory: files created there inherit their group ID from
the directory, not from the effective group ID of the creating process,
and directories created there will also get the
.B S_ISGID
bit set.
For an executable file, the set-group-ID bit causes the effective group ID
of a process that executes the file to change as described in
.BR execve (2).
For a file that does not have the group execution bit
.RB ( S_IXGRP )
set,
the set-group-ID bit indicates mandatory file/record locking.
.P
The sticky bit
.RB ( S_ISVTX )
on a directory means that a file
in that directory can be renamed or deleted only by the owner
of the file, by the owner of the directory, and by a privileged
process.
.SH STANDARDS
POSIX.1-2008.
.SH HISTORY
POSIX.1-2001.
.P
POSIX.1-1990 did not describe the
.BR S_IFMT ,
.BR S_IFSOCK ,
.BR S_IFLNK ,
.BR S_IFREG ,
.BR S_IFBLK ,
.BR S_IFDIR ,
.BR S_IFCHR ,
.BR S_IFIFO ,
and
.B S_ISVTX
constants, but instead specified the use of
the macros
.BR S_ISDIR ()
and so on.
.P
The
.BR S_ISLNK ()
and
.BR S_ISSOCK ()
macros were not in
POSIX.1-1996;
the former is from SVID 4, the latter from SUSv2.
.P
UNIX\ V7 (and later systems) had
.BR S_IREAD ,
.BR S_IWRITE ,
.BR S_IEXEC ,
and
where POSIX
prescribes the synonyms
.BR S_IRUSR ,
.BR S_IWUSR ,
and
.BR S_IXUSR .
.SH NOTES
For pseudofiles that are autogenerated by the kernel, the file size
(\fIstat.st_size\fP; \fIstatx.stx_size\fP)
reported by the kernel is not accurate.
For example, the value 0 is returned for many files under the
.I /proc
directory,
while various files under
.I /sys
report a size of 4096 bytes, even though the file content is smaller.
For such files, one should simply try to read as many bytes as possible
(and append \[aq]\e0\[aq] to the returned buffer
if it is to be interpreted as a string).
.SH SEE ALSO
.BR stat (1),
.BR stat (2),
.BR statx (2),
.BR symlink (7)