1inode(7)               Miscellaneous Information Manual               inode(7)
2
3
4

NAME

6       inode - file inode information
7

DESCRIPTION

9       Each file has an inode containing metadata about the file.  An applica‐
10       tion can retrieve this metadata using stat(2) (or related calls), which
11       returns a stat structure, or statx(2), which returns a statx structure.
12
13       The following is a list of the information typically found in, or asso‐
14       ciated with, the file inode, with the names of the corresponding struc‐
15       ture fields returned by stat(2) and statx(2):
16
17       Device where inode resides
18              stat.st_dev; statx.stx_dev_minor and statx.stx_dev_major
19
20              Each  inode  (as  well  as  the  associated  file)  resides in a
21              filesystem that is hosted on a device.  That device  is  identi‐
22              fied  by  the  combination of its major ID (which identifies the
23              general class of device) and minor ID (which identifies  a  spe‐
24              cific instance in the general class).
25
26       Inode number
27              stat.st_ino; statx.stx_ino
28
29              Each file in a filesystem has a unique inode number.  Inode num‐
30              bers are guaranteed to be unique only within a filesystem (i.e.,
31              the  same  inode  numbers  may be used by different filesystems,
32              which is the reason that hard links  may  not  cross  filesystem
33              boundaries).  This field contains the file's inode number.
34
35       File type and mode
36              stat.st_mode; statx.stx_mode
37
38              See the discussion of file type and mode, below.
39
40       Link count
41              stat.st_nlink; statx.stx_nlink
42
43              This field contains the number of hard links to the file.  Addi‐
44              tional links to an existing file are created using link(2).
45
46       User ID
47              st_uid stat.st_uid; statx.stx_uid
48
49              This field records the user ID of the owner of  the  file.   For
50              newly  created  files, the file user ID is the effective user ID
51              of the creating process.  The user ID of a file can  be  changed
52              using chown(2).
53
54       Group ID
55              stat.st_gid; statx.stx_gid
56
57              The  inode  records  the ID of the group owner of the file.  For
58              newly created files, the file group ID is either the group ID of
59              the  parent  directory or the effective group ID of the creating
60              process, depending on whether or not the set-group-ID bit is set
61              on the parent directory (see below).  The group ID of a file can
62              be changed using chown(2).
63
64       Device represented by this inode
65              stat.st_rdev; statx.stx_rdev_minor and statx.stx_rdev_major
66
67              If this file (inode) represents a device, then the inode records
68              the major and minor ID of that device.
69
70       File size
71              stat.st_size; statx.stx_size
72
73              This  field  gives the size of the file (if it is a regular file
74              or a symbolic link) in bytes.  The size of a  symbolic  link  is
75              the  length  of  the pathname it contains, without a terminating
76              null byte.
77
78       Preferred block size for I/O
79              stat.st_blksize; statx.stx_blksize
80
81              This  field  gives  the  "preferred"  blocksize  for   efficient
82              filesystem  I/O.  (Writing to a file in smaller chunks may cause
83              an inefficient read-modify-rewrite.)
84
85       Number of blocks allocated to the file
86              stat.st_blocks; statx.stx_size
87
88              This field indicates the number of blocks allocated to the file,
89              512-byte  units,  (This may be smaller than st_size/512 when the
90              file has holes.)
91
92              The POSIX.1 standard notes that the unit for the st_blocks  mem‐
93              ber  of  the  stat structure is not defined by the standard.  On
94              many  implementations it is 512 bytes; on a few systems, a  dif‐
95              ferent  unit  is  used, such as 1024.  Furthermore, the unit may
96              differ on a per-filesystem basis.
97
98       Last access timestamp (atime)
99              stat.st_atime; statx.stx_atime
100
101              This is the file's last access timestamp.  It is changed by file
102              accesses,   for   example,   by  execve(2),  mknod(2),  pipe(2),
103              utime(2), and read(2) (of more than zero bytes).   Other  inter‐
104              faces,  such  as  mmap(2), may or may not update the atime time‐
105              stamp
106
107              Some filesystem types allow mounting in such  a  way  that  file
108              and/or  directory  accesses  do not cause an update of the atime
109              timestamp.  (See noatime, nodiratime, and relatime in  mount(8),
110              and  related  information  in mount(2).)  In addition, the atime
111              timestamp is not updated if a file is opened with the  O_NOATIME
112              flag; see open(2).
113
114       File creation (birth) timestamp (btime)
115              (not returned in the stat structure); statx.stx_btime
116
117              The file's creation timestamp.  This is set on file creation and
118              not changed subsequently.
119
120              The btime timestamp was not historically present on UNIX systems
121              and is not currently supported by most Linux filesystems.
122
123       Last modification timestamp (mtime)
124              stat.st_mtime; statx.stx_mtime
125
126              This  is  the file's last modification timestamp.  It is changed
127              by file modifications, for example,  by  mknod(2),  truncate(2),
128              utime(2), and write(2) (of more than zero bytes).  Moreover, the
129              mtime timestamp of a directory is changed  by  the  creation  or
130              deletion of files in that directory.  The mtime timestamp is not
131              changed for changes in owner, group, hard link count, or mode.
132
133       Last status change timestamp (ctime)
134              stat.st_ctime; statx.stx_ctime
135
136              This is the file's last status change timestamp.  It is  changed
137              by  writing or by setting inode information (i.e., owner, group,
138              link count, mode, etc.).
139
140       The timestamp fields report time measured with  a  zero  point  at  the
141       Epoch, 1970-01-01 00:00:00 +0000, UTC (see time(7)).
142
143       Nanosecond timestamps are supported on XFS, JFS, Btrfs, and ext4 (since
144       Linux 2.6.23).  Nanosecond timestamps are not supported in ext2,  ext3,
145       and Reiserfs.  In order to return timestamps with nanosecond precision,
146       the timestamp fields in the stat and statx structures  are  defined  as
147       structures  that  include  a  nanosecond  component.   See  stat(2) and
148       statx(2) for details.  On filesystems that  do  not  support  subsecond
149       timestamps,  the nanosecond fields in the stat and statx structures are
150       returned with the value 0.
151
152   The file type and mode
153       The stat.st_mode field (for statx(2), the  statx.stx_mode  field)  con‐
154       tains the file type and mode.
155
156       POSIX  refers to the stat.st_mode bits corresponding to the mask S_IFMT
157       (see below) as the file type, the 12 bits  corresponding  to  the  mask
158       07777  as the file mode bits and the least significant 9 bits (0777) as
159       the file permission bits.
160
161       The following mask values are defined for the file type:
162
163           S_IFMT     0170000   bit mask for the file type bit field
164
165           S_IFSOCK   0140000   socket
166           S_IFLNK    0120000   symbolic link
167           S_IFREG    0100000   regular file
168           S_IFBLK    0060000   block device
169           S_IFDIR    0040000   directory
170           S_IFCHR    0020000   character device
171           S_IFIFO    0010000   FIFO
172
173       Thus, to test for a regular file (for example), one could write:
174
175           stat(pathname, &sb);
176           if ((sb.st_mode & S_IFMT) == S_IFREG) {
177               /* Handle regular file */
178           }
179
180       Because tests of the above form are common, additional macros  are  de‐
181       fined  by  POSIX  to  allow  the test of the file type in st_mode to be
182       written more concisely:
183
184           S_ISREG(m)  is it a regular file?
185
186           S_ISDIR(m)  directory?
187
188           S_ISCHR(m)  character device?
189
190           S_ISBLK(m)  block device?
191
192           S_ISFIFO(m) FIFO (named pipe)?
193
194           S_ISLNK(m)  symbolic link?  (Not in POSIX.1-1996.)
195
196           S_ISSOCK(m) socket?  (Not in POSIX.1-1996.)
197
198       The preceding code snippet could thus be rewritten as:
199
200           stat(pathname, &sb);
201           if (S_ISREG(sb.st_mode)) {
202               /* Handle regular file */
203           }
204
205       The definitions of most of the above file type test macros are provided
206       if any of the following feature test macros is defined: _BSD_SOURCE (in
207       glibc 2.19 and earlier), _SVID_SOURCE (in glibc 2.19 and  earlier),  or
208       _DEFAULT_SOURCE (in glibc 2.20 and later).  In addition, definitions of
209       all of the above macros except S_IFSOCK and S_ISSOCK() are provided  if
210       _XOPEN_SOURCE is defined.
211
212       The  definition  of  S_IFSOCK  can  also  be exposed either by defining
213       _XOPEN_SOURCE with a value of 500 or greater or (since glibc  2.24)  by
214       defining both _XOPEN_SOURCE and _XOPEN_SOURCE_EXTENDED.
215
216       The definition of S_ISSOCK() is exposed if any of the following feature
217       test macros is defined: _BSD_SOURCE (in glibc 2.19 and  earlier),  _DE‐
218       FAULT_SOURCE  (in  glibc 2.20 and later), _XOPEN_SOURCE with a value of
219       500 or greater, _POSIX_C_SOURCE with a value of 200112L or greater,  or
220       (since glibc 2.24) by defining both _XOPEN_SOURCE and _XOPEN_SOURCE_EX‐
221       TENDED.
222
223       The following mask values are defined for the file  mode  component  of
224       the st_mode field:
225
226           S_ISUID     04000   set-user-ID bit (see execve(2))
227           S_ISGID     02000   set-group-ID bit (see below)
228           S_ISVTX     01000   sticky bit (see below)
229
230           S_IRWXU     00700   owner has read, write, and execute permission
231           S_IRUSR     00400   owner has read permission
232           S_IWUSR     00200   owner has write permission
233           S_IXUSR     00100   owner has execute permission
234
235           S_IRWXG     00070   group has read, write, and execute permission
236           S_IRGRP     00040   group has read permission
237           S_IWGRP     00020   group has write permission
238           S_IXGRP     00010   group has execute permission
239
240           S_IRWXO     00007   others (not in group) have read, write, and ex‐
241                               ecute permission
242           S_IROTH     00004   others have read permission
243           S_IWOTH     00002   others have write permission
244           S_IXOTH     00001   others have execute permission
245
246       The set-group-ID bit (S_ISGID) has several special uses.  For a  direc‐
247       tory,  it  indicates  that BSD semantics are to be used for that direc‐
248       tory: files created there inherit their group ID  from  the  directory,
249       not  from  the effective group ID of the creating process, and directo‐
250       ries created there will also get the S_ISGID  bit  set.   For  an  exe‐
251       cutable  file,  the set-group-ID bit causes the effective group ID of a
252       process that executes the file to change  as  described  in  execve(2).
253       For  a  file  that does not have the group execution bit (S_IXGRP) set,
254       the set-group-ID bit indicates mandatory file/record locking.
255
256       The sticky bit (S_ISVTX) on a directory means that a file in  that  di‐
257       rectory can be renamed or deleted only by the owner of the file, by the
258       owner of the directory, and by a privileged process.
259

STANDARDS

261       POSIX.1-2008.
262

HISTORY

264       POSIX.1-2001.
265
266       POSIX.1-1990 did not describe the S_IFMT, S_IFSOCK,  S_IFLNK,  S_IFREG,
267       S_IFBLK,  S_IFDIR, S_IFCHR, S_IFIFO, and S_ISVTX constants, but instead
268       specified the use of the macros S_ISDIR() and so on.
269
270       The S_ISLNK() and S_ISSOCK() macros were not in POSIX.1-1996; the  for‐
271       mer is from SVID 4, the latter from SUSv2.
272
273       UNIX V7  (and  later systems) had S_IREAD, S_IWRITE, S_IEXEC, and where
274       POSIX prescribes the synonyms S_IRUSR, S_IWUSR, and S_IXUSR.
275

NOTES

277       For pseudofiles that are autogenerated by the  kernel,  the  file  size
278       (stat.st_size;  statx.stx_size) reported by the kernel is not accurate.
279       For example, the value 0 is returned for many files under the /proc di‐
280       rectory,  while  various  files under /sys report a size of 4096 bytes,
281       even though the file content is smaller.  For such  files,  one  should
282       simply  try  to  read as many bytes as possible (and append '\0' to the
283       returned buffer if it is to be interpreted as a string).
284

SEE ALSO

286       stat(1), stat(2), statx(2), symlink(7)
287
288
289
290Linux man-pages 6.05              2023-07-30                          inode(7)
Impressum