Penguin
Recent Changes
Annotated edit history of stat(2) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 STAT
2 !!!STAT
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 ERRORS
8 CONFORMING TO
9 OTHER SYSTEMS
10 SEE ALSO
11 ----
12 !!NAME
13
14
15 stat, fstat, lstat - get file status
16 !!SYNOPSIS
17
18
19 __#include __
20 #include __
21 #include __
22
23
24 __int stat(const char *__''file_name''__, struct stat
25 *__''buf''__);
26 int fstat(int__ ''filedes''__, struct stat
27 *__''buf''__);
28 int lstat(const char *__''file_name''__, struct stat
29 *__''buf''__);__
30 !!DESCRIPTION
31
32
33 These functions return information about the specified file.
34 You do not need any access rights to the file to get this
35 information but you need search rights to all directories
36 named in the path leading to the file.
37
38
39 __stat__ stats the file pointed to by ''file_name''
40 and fills in ''buf''.
41
42
43 __lstat__ is identical to __stat__, except in the case
44 of a symbolic link, where the link itself is stat-ed, not
45 the file that it refers to.
46
47
48 __fstat__ is identical to stat, only the open file
49 pointed to by ''filedes'' (as returned by open(2))
50 is statted in place of ''file_name''.
51
52
53 They all return a ''stat'' structure, which contains the
54 following fields:
55
56
57 struct stat {
58 dev_t st_dev; /* device */
59 ino_t st_ino; /* inode */
60 mode_t st_mode; /* protection */
61 nlink_t st_nlink; /* number of hard links */
62 uid_t st_uid; /* user ID of owner */
63 gid_t st_gid; /* group ID of owner */
64 dev_t st_rdev; /* device type (if inode device) */
65 off_t st_size; /* total size, in bytes */
66 unsigned long st_blksize; /* blocksize for filesystem I/O */
67 unsigned long st_blocks; /* number of blocks allocated */
68 time_t st_atime; /* time of last access */
69 time_t st_mtime; /* time of last modification */
70 time_t st_ctime; /* time of last change */
71 };
72
73
74 The value ''st_size'' gives the size of the file (if it
75 is a regular file or a symlink) in bytes. The size of a
76 symlink is the length of the pathname it contains, without
77 trailing NUL.
78
79
80 The value ''st_blocks'' gives the size of the file in
81 512-byte blocks. (This may be smaller than
82 ''st_size''/512 e.g. when the file has holes.) The value
83 ''st_blksize'' gives the
84 ''
85
86
87 Not all of the Linux filesystems implement all of the time
88 fields. Some file system types allow mounting in such a way
89 that file accesses do not cause an update of the
90 ''st_atime'' field. (See `noatime' in
91 mount(8).)
92
93
94 The field ''st_atime'' is changed by file accesses, e.g.
95 by exec(2), mknod(2), pipe(2),
96 utime(2) and read(2) (of more than zero
97 bytes). Other routines, like mmap(2), may or may not
98 update ''st_atime''.
99
100
101 The field ''st_mtime'' is changed by file modifications,
102 e.g. by mknod(2), truncate(2), utime(2)
103 and write(2) (of more than zero bytes). Moreover,
104 ''st_mtime'' of a directory is changed by the creation or
105 deletion of files in that directory. The ''st_mtime''
106 field is ''not'' changed for changes in owner, group,
107 hard link count, or mode.
108
109
110 The field ''st_ctime'' is changed by writing or by
111 setting inode information (i.e., owner, group, link count,
112 mode, etc.).
113
114
115 The following POSIX macros are defined to check the file
116 type:
117
118
119 S_ISREG(m)
120
121
122 is it a regular file?
123
124
125 S_ISDIR(m)
126
127
128 directory?
129
130
131 S_ISCHR(m)
132
133
134 character device?
135
136
137 S_ISBLK(m)
138
139
140 block device?
141
142
143 S_ISFIFO(m)
144
145
146 fifo?
147
148
149 S_ISLNK(m)
150
151
152 symbolic link? (Not in POSIX.1-1996.)
153
154
155 S_ISSOCK(m)
156
157
158 socket? (Not in POSIX.1-1996.)
159
160
161 The following flags are defined for the ''st_mode''
162 field:
163
164
165 The set GID bit (S_ISGID) has several special uses: For a directory it indicates that BSD semantics is to be used for that directory: files created there inherit their group ID from the directory, not from the effective gid of the creating process, and directories created there will also get the S_ISGID bit set. For a file that does not have the group execution bit (S_IXGRP) set, it indicates mandatory file/record locking.
166
167
168 The `sticky' bit (S_ISVTX) on a directory means that a file
169 in that directory can be renamed or deleted only by the
170 owner of the file, by the owner of the directory, and by
171 root.
172 !!RETURN VALUE
173
174
175 On success, zero is returned. On error, -1 is returned, and
176 ''errno'' is set appropriately.
177 !!ERRORS
178
179
180 __EBADF__
181
182
183 ''filedes'' is bad.
184
185
186 __ENOENT__
187
188
189 A component of the path ''file_name'' does not exist, or
190 the path is an empty string.
191
192
193 __ENOTDIR__
194
195
196 A component of the path is not a directory.
197
198
199 __ELOOP__
200
201
202 Too many symbolic links encountered while traversing the
203 path.
204
205
206 __EFAULT__
207
208
209 Bad address.
210
211
212 __EACCES__
213
214
215 Permission denied.
216
217
218 __ENOMEM__
219
220
221 Out of memory (i.e. kernel memory).
222
223
224 __ENAMETOOLONG__
225
226
227 File name too long.
228 !!CONFORMING TO
229
230
231 The __stat__ and __fstat__ calls conform to SVr4,
232 SVID, POSIX, X/OPEN, BSD 4.3. The __lstat__ call conforms
233 to 4.3BSD and SVr4. SVr4 documents additional __fstat__
234 error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4
235 documents additional __stat__ and __lstat__ error
236 conditions EACCES, EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW.
237 Use of the ''st_blocks'' and ''st_blksize'' fields may
238 be less portable. (They were introduced in BSD. Are not
239 specified by POSIX. The interpretation differs between
240 systems, and possibly on a single system when NFS mounts are
241 involved.)
242
243
244 POSIX does not describe the S_IFMT, S_IFSOCK, S_IFLNK,
245 S_IFREG, S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX bits,
246 but instead demands the use of the macros S_ISDIR(), etc.
247 The S_ISLNK and S_ISSOCK macros are not in POSIX.1-1996, but
248 both will be in the next POSIX standard; the former is from
249 SVID 4v2, the latter from SUSv2.
250
251
252 Unix V7 (and later systems) had S_IREAD, S_IWRITE, S_IEXEC,
253 where POSIX prescribes the synonyms S_IRUSR, S_IWUSR,
254 S_IXUSR.
255 !!OTHER SYSTEMS
256
257
258 Values that have been (or are) in use on various
259 systems:
260
261
262 A sticky command appeared in Version 32V AT
263 !!SEE ALSO
264
265
266 chmod(2), chown(2), readlink(2),
267 utime(2)
268 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.