version 1 showing authors affecting page license.
.
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 |
---- |