402 lines
10 KiB
Groff
402 lines
10 KiB
Groff
.if n .pH 2/gen/stat @(#)stat 43.8 of 8/4/92
|
|
.\" Copyright 1992, 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1990, 1989 AT&T
|
|
.TH stat 2
|
|
.SH NAME
|
|
stat, lstat, fstat \- get file status
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
\f4#include <sys/types.h>\f1
|
|
.br
|
|
\f4#include <sys/stat.h>\f1
|
|
.PP
|
|
\f4int stat(const char \(**\f2path\fP, struct stat \(**\f2buf\fP);
|
|
.PP
|
|
\f4int lstat(const char \(**\f2path\fP, struct stat \(**\f2buf\fP);
|
|
.PP
|
|
\f4int fstat(int \f2fildes\fP, struct stat \(**\f2buf\fP);\f1
|
|
.Op
|
|
.Op f
|
|
.SH FORTRAN SYNOPSIS
|
|
\f4integer function stat (path, statb)\f1
|
|
.br
|
|
\f4character \(**(\(**) path\f1
|
|
.br
|
|
\f4integer statb (12)\f1
|
|
.PP
|
|
\f4integer function lstat (path, statb)\f1
|
|
.br
|
|
\f4character \(**(\(**) path\f1
|
|
.br
|
|
\f4integer statb (12)\f1
|
|
.PP
|
|
\f4integer function fstat (lunit, statb)\f1
|
|
.br
|
|
\f4integer lunit, statb (12)\f1
|
|
.Op
|
|
.SH DESCRIPTION
|
|
The only difference between the \f4*stat\fP and the \f4*stat64\fP calls
|
|
is that the \f4*stat64\fP calls return a \f4stat64\fP structure, with three
|
|
fields increased in size to allow for larger files and filesystems:
|
|
\f4st_ino\fP, \f4st_size\fP, and \f4st_blocks\fP are all 64-bit values.
|
|
.PP
|
|
NOTE: All programs compiled either -n32 or -64 get the \f4stat64\fP versions
|
|
of the stat system call, even when calling \f4stat\fP. Only programs
|
|
compiled -o32 get the version with the smaller field sizes, for binary
|
|
compatibibility
|
|
.PP
|
|
.I path\^
|
|
points to a
|
|
path name
|
|
naming a file.
|
|
Read, write, or execute permission of the named file is not required,
|
|
but all directories
|
|
listed in the
|
|
path name
|
|
leading to the file must be searchable.
|
|
\f4stat\fP
|
|
obtains information about the named file.
|
|
.PP
|
|
\f4lstat\fP obtains file attributes similar to \f4stat\fP,
|
|
except when the named file is a symbolic link; in that case
|
|
\f4lstat\fP returns information about the link,
|
|
while \f4stat\fP returns information about the
|
|
file the link references.
|
|
.PP
|
|
\f4fstat\fP
|
|
obtains information about an open file
|
|
known by the
|
|
.Op c p a
|
|
file descriptor
|
|
.IR fildes ,
|
|
obtained from a successful
|
|
\f4creat\fP,
|
|
\f4open\fP,
|
|
\f4dup\fP,
|
|
\f4fcntl\fP,
|
|
\f4pipe\fP,
|
|
or
|
|
\f4ioctl\fP
|
|
system call.
|
|
.Op
|
|
.Op f
|
|
logical unit
|
|
.IR lunit .
|
|
.Op
|
|
.PP
|
|
.Op c p a
|
|
.I buf\^
|
|
is a pointer to a
|
|
\f4stat\fP
|
|
structure into which information
|
|
is placed concerning the file.
|
|
.PP
|
|
The contents of the structure pointed to by
|
|
.I buf\^
|
|
include the following members:
|
|
.P
|
|
.RS 3
|
|
.nf
|
|
.ft 4
|
|
.ta 15n 28n
|
|
mode_t st_mode; /\(** File mode \(**/
|
|
ino_t st_ino; /\(** Inode number \(**/
|
|
dev_t st_dev; /\(** ID of device containing \(**/
|
|
/\(** a directory entry for this file \(**/
|
|
dev_t st_rdev; /\(** ID of device \(**/
|
|
/\(** This entry is defined only for \(**/
|
|
/\(** char special, block special, \(**/
|
|
/\(** and lofs files \(**/
|
|
nlink_t st_nlink; /\(** Number of links \(**/
|
|
uid_t st_uid; /\(** User ID of the file's owner \(**/
|
|
gid_t st_gid; /\(** Group ID of the file's group \(**/
|
|
off_t st_size; /\(** File size in bytes \(**/
|
|
timespec_t st_atim; /\(** Time of last access \(**/
|
|
timespec_t st_mtim; /\(** Time of last data modification \(**/
|
|
timespec_t st_ctim; /\(** Time of last file status change \(**/
|
|
/\(** Times measured in seconds and nanoseconds \(**/
|
|
/\(** since 00:00:00 UTC, Jan. 1, 1970 \(**/
|
|
long st_blksize; /\(** Preferred I/O block size \(**/
|
|
blkcnt_t st_blocks; /\(** Number 512 byte blocks allocated \(**/
|
|
.ft 1
|
|
.fi
|
|
.Op
|
|
.Op f
|
|
.RE
|
|
.PP
|
|
For FORTRAN programs,
|
|
.I statb\^
|
|
is a pointer to a 12 element array into which information
|
|
is placed concerning the file.
|
|
.PP
|
|
The contents of the array
|
|
are as follows:
|
|
.P
|
|
.RS 3
|
|
.nf
|
|
.ft 4
|
|
.ta 14n 24n
|
|
statb(1) st_dev ID of device containing
|
|
a directory entry for this file
|
|
statb(2) st_ino Inode number
|
|
statb(3) st_mode File mode
|
|
statb(4) st_nlink Number of links
|
|
statb(5) st_uid User ID of the file's owner
|
|
statb(6) st_gid Group ID of the file's group
|
|
statb(7) st_rdev ID of device
|
|
This entry is defined only for
|
|
char special or block special files
|
|
statb(8) st_size File size in bytes
|
|
statb(9) st_atime Time of last access
|
|
statb(10) st_mtime Time of last data modification
|
|
statb(11) st_ctime Time of last file status change
|
|
Times measured in seconds since
|
|
00:00:00 UTC, Jan. 1, 1970
|
|
statb(12) st_blksize Preferred I/O block size
|
|
.ft 1
|
|
.fi
|
|
.Op
|
|
.RE
|
|
.DT
|
|
.PP
|
|
.RS 0
|
|
The fields have the following meanings:
|
|
.TP 1i
|
|
\f4st_mode\f1
|
|
The mode of the file as described in
|
|
\f4mknod\fP(2).
|
|
In addition to the modes described in \f4mknod\fP(2),
|
|
the mode of a file may also be S_IFLNK if the file
|
|
is a symbolic link.
|
|
(Note that S_IFLNK may only be returned by \f4lstat\fP.)
|
|
The various macros in \f4sys/stat.h\fP should be used to
|
|
determine if there is a type match, since the types are not
|
|
a bit field. For example, you should use \f4S_ISDIR(st.st_mode)\fP
|
|
rather than \f4(st.st_mode&S_IFDIR)\fP.
|
|
.TP
|
|
\f4st_ino\f1
|
|
Except for lofs file systems this field uniquely identifies
|
|
the file in a given file system and the pair \f4st_ino\fP and \f4st_dev\fP
|
|
uniquely identify regular files and directories. For regular files and
|
|
directories accessed via an "lofs" file system, the value of this field
|
|
is obtained from the underlying file system, and the \f4st_rdev\fP
|
|
field must also be used to identify uniqueness.
|
|
.TP
|
|
\f4st_dev\f1
|
|
Except for lofs file systems this field uniquely identifies the file system
|
|
that contains the file. Beware that this is still
|
|
true for NFS file systems exported using the -nohide
|
|
option, which may not appear in /etc/mtab. [See \f4exports\fP(4).]
|
|
Its value may be used as input to the
|
|
\f4ustat\fP system call to determine
|
|
more information about this file system.
|
|
No other meaning is associated with this value.
|
|
For regular files and
|
|
directories accessed via an "lofs" file system, the value of this field
|
|
is obtained from the underlying file system, and the \f4st_rdev\fP
|
|
field must also be used to identify uniqueness.
|
|
.TP
|
|
\f4st_rdev\f1
|
|
This field should be used only by administrative commands.
|
|
It is valid only for block special, character special,
|
|
and files and directories accessed via "lofs" file systems.
|
|
It only has meaning on the system where the file was configured.
|
|
.TP
|
|
\f4st_nlink\f1
|
|
This field should be used only by
|
|
administrative commands.
|
|
.TP
|
|
\f4st_uid\f1
|
|
The user
|
|
.SM ID
|
|
of the file's owner.
|
|
.TP
|
|
\f4st_gid\f1
|
|
The group
|
|
.SM ID
|
|
of the file's group.
|
|
.TP
|
|
\f4st_size\f1
|
|
For regular files, this is the address of the end
|
|
of the file.
|
|
If the file's size is larger than will fit in the
|
|
\f4st_size\f1 field (2^31 - 1) then the value (2^31 - 1)
|
|
is returned there instead. See also \f4stat64\fP(2).
|
|
For block special or character special,
|
|
this is not defined.
|
|
See also \f4pipe\fP(2).
|
|
.TP
|
|
\f4st_atim\f1
|
|
Time when file data was last accessed.
|
|
Changed by the following system calls:
|
|
\f4creat\fP,
|
|
\f4mknod\fP,
|
|
\f4pipe\fP,
|
|
\f4utime\fP,
|
|
and
|
|
\f4read\fP.
|
|
The seconds portion of \f4st_atim\f1 is available as \f4st_atime\f1.
|
|
.TP
|
|
\f4st_mtim\f1
|
|
Time when data was last modified.
|
|
Changed by the following system calls:
|
|
\f4creat\fP,
|
|
\f4mknod\fP,
|
|
\f4pipe\fP,
|
|
\f4utime\fP,
|
|
and
|
|
\f4write\fP.
|
|
The seconds portion of \f4st_mtim\f1 is available as \f4st_mtime\f1.
|
|
.TP
|
|
\f4st_ctim\f1
|
|
Time when file status was last changed.
|
|
Changed by the following system calls:
|
|
\f4chmod\fP,
|
|
\f4chown\fP,
|
|
\f4creat\fP,
|
|
\f4link\fP,
|
|
\f4mknod\fP,
|
|
\f4pipe\fP,
|
|
\f4unlink\fP,
|
|
\f4utime\fP,
|
|
and
|
|
\f4write\fP.
|
|
The seconds portion of \f4st_ctim\f1 is available as \f4st_ctime\f1.
|
|
.TP
|
|
\f4st_blksize\fP
|
|
A hint as to the ``best'' unit size for I/O operations.
|
|
If the underlying volume is a stripe volume, then st_blksize is set to
|
|
the stripe width.
|
|
This field is not defined for block-special or character-special files.
|
|
.Op c p a
|
|
.TP
|
|
\f4st_blocks\fP
|
|
The total number of physical blocks of size 512 bytes actually allocated on
|
|
disk.
|
|
This field is not defined for block-special or character-special
|
|
files.
|
|
Holes in files (blocks never allocated) are not counted in this value;
|
|
indirect blocks (those used to store pointers to blocks in the file)
|
|
are counted.
|
|
.Op
|
|
.RE
|
|
.PP
|
|
\f4stat\fP
|
|
and \f4lstat\fP fail if one or more of the following are true:
|
|
.RS 0
|
|
.TP 1i
|
|
\f4EACCES\fP
|
|
Search permission is denied for a component of the
|
|
path prefix.
|
|
.TP
|
|
\f4EACCES\fP
|
|
Read permission is denied on the named file.
|
|
.TP
|
|
\f4EFAULT\fP
|
|
.I buf\^
|
|
or
|
|
.I path\^
|
|
points to an invalid address.
|
|
.TP
|
|
\f4EINTR\fP
|
|
A signal was caught during the \f4stat\fP or \f4lstat\fP system call.
|
|
.TP
|
|
\f4ETIMEDOUT\fP
|
|
The named file
|
|
is located on a remote file system which is not available [see \f4intro\fP(2)].
|
|
.TP
|
|
\f4ELOOP\fP
|
|
Too many symbolic links were encountered in translating \f2path\f1.
|
|
.TP
|
|
\f4EMULTIHOP\fP
|
|
Components of \f2path\f1 require hopping to multiple
|
|
remote machines and the file system does not allow it.
|
|
.TP
|
|
\f4ENAMETOOLONG\fP
|
|
The length of the \f2path\f1 argument exceeds {\f4PATH_MAX\f1}, or the
|
|
length of a \f2path\f1 component exceeds {\f4NAME_MAX\f1} while
|
|
\f4_POSIX_NO_TRUNC\f1 is in effect.
|
|
.TP
|
|
\f4ENOENT\fP
|
|
The named file does not exist or is the null pathname.
|
|
.TP
|
|
\f4ENOTDIR\fP
|
|
A component of the path prefix is not a directory.
|
|
.TP
|
|
\f4ENOLINK\fP
|
|
\f2path\f1 points to a remote machine and the link
|
|
to that machine is no longer active.
|
|
.TP
|
|
\f4EOVERFLOW\fP
|
|
A component is too large to store in the structure pointed to by \f2buf\f1.
|
|
.PP
|
|
\f4fstat\fP
|
|
fails if one or more of the following are true:
|
|
.RE
|
|
.RS 0
|
|
.TP 1i
|
|
\f4EBADF\fP
|
|
.Op c p a
|
|
.I fildes\^
|
|
is not a valid open file descriptor.
|
|
.Op
|
|
.Op f
|
|
.I lunit\^
|
|
is not a valid logical unit number.
|
|
.Op
|
|
.Op c p a
|
|
.TP 1i
|
|
\f4EFAULT\fP
|
|
\f2buf\fP points to an invalid address.
|
|
.Op
|
|
.TP 1i
|
|
\f4EINTR\fP
|
|
A signal was caught during the \f4fstat\fP system call.
|
|
.TP 1i
|
|
\f4ETIMEDOUT\fP
|
|
.Op c p a
|
|
.I fildes\^
|
|
.Op
|
|
.Op f
|
|
.I lunit\^
|
|
.Op
|
|
refers to a file
|
|
on a remote file system which is not available [see \f4intro\fP(2)].
|
|
.TP 1i
|
|
\f4ENOLINK\fP
|
|
.Op c p a
|
|
\f2fildes\f1
|
|
.Op
|
|
.Op f
|
|
\f2lunit\f1
|
|
.Op
|
|
refers to a file on a remote machine and the link
|
|
to that machine is no longer active.
|
|
.TP 1i
|
|
\f4EOVERFLOW\fP
|
|
A component is too large to store in the structure pointed to by \f2buf\f1.
|
|
.RE
|
|
.SH "SEE ALSO"
|
|
\f4chmod\fP(2),
|
|
\f4chown\fP(2),
|
|
\f4creat\fP(2),
|
|
\f4exports\fP(4),
|
|
\f4fattach\fP(3C),
|
|
\f4link\fP(2),
|
|
\f4mknod\fP(2),
|
|
\f4pipe\fP(2),
|
|
\f4read\fP(2),
|
|
\f4stat64\fP(2),
|
|
\f4realpath\fP(3C),
|
|
\f4stat\fP(5),
|
|
\f4stat64\fP(5),
|
|
\f4time\fP(2),
|
|
\f4unlink\fP(2),
|
|
\f4utime\fP(2),
|
|
\f4write\fP(2)
|
|
.SH "DIAGNOSTICS"
|
|
Upon successful completion a value of 0 is returned.
|
|
Otherwise, a value of \-1 is returned and
|
|
\f4errno\fP
|
|
is set to indicate the error.
|