Debian Codegraph @

upstream/debian-unstable/man3/stat.3type

raw
1 .\" Copyright 2020, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH stat 3type 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 stat \- file status
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc )
12 .SH SYNOPSIS
13 .EX
14 .B #include <sys/stat.h>
15 .P
16 .B struct stat {
17 .BR " dev_t st_dev;" " /* ID of device containing file */"
18 .BR " ino_t st_ino;" " /* Inode number */"
19 .BR " mode_t st_mode;" " /* File type and mode */"
20 .BR " nlink_t st_nlink;" " /* Number of hard links */"
21 .BR " uid_t st_uid;" " /* User ID of owner */"
22 .BR " gid_t st_gid;" " /* Group ID of owner */"
23 .BR " dev_t st_rdev;" " /* Device ID (if special file) */"
24 .BR " off_t st_size;" " /* Total size, in bytes */"
25 .BR " blksize_t st_blksize;" " /* Block size for filesystem I/O */"
26 .BR " blkcnt_t st_blocks;" " /* Number of 512 B blocks allocated */"
27 \&
28 /* Since POSIX.1-2008, this structure supports nanosecond
29 precision for the following timestamp fields.
30 For the details before POSIX.1-2008, see HISTORY. */
31 \&
32 .BR " struct timespec st_atim;" " /* Time of last access */"
33 .BR " struct timespec st_mtim;" " /* Time of last modification */"
34 .BR " struct timespec st_ctim;" " /* Time of last status change */"
35 \&
36 .BR "#define st_atime st_atim.tv_sec" " /* Backward compatibility */"
37 .B "#define st_mtime st_mtim.tv_sec"
38 .B "#define st_ctime st_ctim.tv_sec"
39 .B };
40 .EE
41 .P
42 .RS -4
43 Feature Test Macro Requirements for glibc (see
44 .BR feature_test_macros (7)):
45 .RE
46 .P
47 .IR .st_atim ,
48 .IR .st_mtim ,
49 .IR .st_ctim :
50 .nf
51 Since glibc 2.12:
52 _POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700
53 glibc 2.19 and earlier:
54 _BSD_SOURCE || _SVID_SOURCE
55 .fi
56 .SH DESCRIPTION
57 Describes information about a file.
58 .P
59 The fields are as follows:
60 .TP
61 .I .st_dev
62 This field describes the device on which this file resides.
63 (The
64 .BR major (3)
65 and
66 .BR minor (3)
67 macros may be useful to decompose the device ID in this field.)
68 .TP
69 .I .st_ino
70 This field contains the file's inode number
71 in the filesystem on
72 .IR .st_dev .
73 If
74 .BR stat (2)
75 was called on the mount point,
76 then
77 .I .st_ino
78 differs from
79 .I .d_ino
80 returned by
81 .BR readdir (3)
82 for the corresponding directory entry in the parent directory.
83 In this case,
84 .I .st_ino
85 is the inode number of the root directory of the mounted filesystem,
86 while
87 .I .d_ino
88 is the inode number of the mount point in the parent filesystem.
89 .TP
90 .I .st_mode
91 This field contains the file type and mode.
92 See
93 .BR inode (7)
94 for further information.
95 .TP
96 .I .st_nlink
97 This field contains the number of hard links to the file.
98 .TP
99 .I .st_uid
100 This field contains the user ID of the owner of the file.
101 .TP
102 .I .st_gid
103 This field contains the ID of the group owner of the file.
104 .TP
105 .I .st_rdev
106 This field describes the device that this file (inode) represents.
107 .TP
108 .I .st_size
109 This field gives the size of the file (if it is a regular
110 file or a symbolic link) in bytes.
111 The size of a symbolic link is the length of the pathname
112 it contains, without a terminating null byte.
113 .TP
114 .I .st_blksize
115 This field gives the "preferred" block size for efficient filesystem I/O.
116 .TP
117 .I .st_blocks
118 This field indicates the number of blocks allocated to the file,
119 in 512-byte units.
120 (This may be smaller than
121 .IR .st_size /512
122 when the file has holes.)
123 .TP
124 .I .st_atime
125 This is the time of the last access of file data.
126 .TP
127 .I .st_mtime
128 This is the time of last modification of file data.
129 .TP
130 .I .st_ctime
131 This is the file's last status change timestamp
132 (time of last change to the inode).
133 .P
134 For further information on the above fields, see
135 .BR inode (7).
136 .SH STANDARDS
137 POSIX.1-2024.
138 .SH HISTORY
139 .TP
140 .I stat
141 POSIX.1-1988.
142 .TP
143 .I .st_rdev
144 .TQ
145 .I .st_blksize
146 .TQ
147 .I .st_blocks
148 SUSv1,
149 POSIX.1-2001 XSI.
150 .P
151 Initially, SUSv1 specified
152 .I .st_blksize
153 and
154 .I .st_blocks
155 with type
156 .IR long .
157 This was remedied in SUSv2.
158 .P
159 Old kernels and old standards did not support nanosecond timestamp fields.
160 Instead, there were three timestamp fields
161 .RI \[em] .st_atime ,
162 .IR .st_mtime ,
163 and
164 .IR .st_ctime \[em]
165 typed
166 as
167 .I time_t
168 that recorded timestamps with one-second precision.
169 .P
170 Since Linux 2.5.48, the
171 .I stat
172 structure supports nanosecond resolution for the three file timestamp fields.
173 The nanosecond components of each timestamp are available
174 via names of the form
175 .IR .st_atim.tv_nsec ,
176 if suitable test macros are defined.
177 Nanosecond timestamps were standardized in POSIX.1-2008,
178 and, starting with glibc 2.12,
179 glibc exposes the nanosecond component names if
180 .B _POSIX_C_SOURCE
181 is defined with the value 200809L or greater, or
182 .B _XOPEN_SOURCE
183 is defined with the value 700 or greater.
184 Up to and including glibc 2.19,
185 the definitions of the nanoseconds components are also defined if
186 .B _BSD_SOURCE
187 or
188 .B _SVID_SOURCE
189 is defined.
190 If none of the aforementioned macros are defined,
191 then the nanosecond values are exposed with names of the form
192 .IR .st_atimensec .
193 .SH NOTES
194 The following header also provides this type:
195 .IR <ftw.h> .
196 .SH SEE ALSO
197 .BR stat (2),
198 .BR inode (7)