mirror of https://github.com/GnoConsortium/gno.git
239 lines
7.2 KiB
Groff
239 lines
7.2 KiB
Groff
.\" Copyright (c) 1980, 1991, 1993, 1994
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)stat.2 8.3 (Berkeley) 4/19/94
|
|
.\"
|
|
.TH STAT 2 "19 January 1997" GNO "System Calls"
|
|
.SH NAME
|
|
.BR stat ,
|
|
.BR lstat ,
|
|
.BR fstat
|
|
\- get file status
|
|
.SH SYNOPSIS
|
|
#include <sys/types.h>
|
|
.br
|
|
#include <sys/stat.h>
|
|
.sp 1
|
|
int
|
|
\fBstat\fR (const char *\fIpath\fR, struct stat *\fIsb\fR);
|
|
.br
|
|
int
|
|
\fBlstat\fR (const char *\fIpath\fR, struct stat *\fIsb\fR);
|
|
.br
|
|
int
|
|
\fBfstat\fR (int \fIfd\fR, struct stat *\fIsb\fR);
|
|
.SH DESCRIPTION
|
|
These calls are used to retrieve status information about files.
|
|
They do much the same think as the GS/OS call
|
|
.BR GetFileInfoGS ,
|
|
except that they return the information in a format compatible with
|
|
Unix's
|
|
.BR stat
|
|
calls, and also provide information about sockets and GNO character
|
|
devices.
|
|
.LP
|
|
The
|
|
.BR stat
|
|
function obtains information about the file pointed to by
|
|
.IR path .
|
|
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.
|
|
.LP
|
|
.BR lstat
|
|
is like
|
|
.BR stat
|
|
except in the case where the named file is a symbolic link,
|
|
in which case
|
|
.BR lstat
|
|
returns information about the link,
|
|
while
|
|
.BR stat
|
|
returns information about the file the link references.
|
|
Unlike other filesystem objects,
|
|
symbolic links do not have an owner, group, access mode, times, etc.
|
|
Instead, these attributes are taken from the directory that
|
|
contains the link.
|
|
The only attributes returned from an
|
|
.BR lstat
|
|
that refer to the symbolic link itself are the file type (S_IFLNK),
|
|
size, blocks, and link count (always 1).
|
|
.LP
|
|
The
|
|
.BR fstat
|
|
obtains the same information about an open file
|
|
known by the file descriptor
|
|
.IR fd .
|
|
.LP
|
|
The
|
|
.I sb
|
|
argument is a pointer to a
|
|
.BR stat
|
|
structure
|
|
as defined by <sys/stat.h>
|
|
(shown below)
|
|
and into which information is placed concerning the file.
|
|
.nf
|
|
struct stat {
|
|
dev_t st_dev; /* device inode resides on */
|
|
ino_t st_ino; /* inode's number */
|
|
mode_t st_mode; /* inode protection mode */
|
|
nlink_t st_nlink; /* number or hard links to the file */
|
|
uid_t st_uid; /* user-id of owner */
|
|
gid_t st_gid; /* group-id of owner */
|
|
dev_t st_rdev; /* device type, for special file inode */
|
|
off_t st_size; /* file size, in bytes */
|
|
time_t st_atime; /* time of last access (GNO: same as st_mtime) */
|
|
int st_spare1; /* reserved */
|
|
time_t st_mtime; /* time of last data modification */
|
|
int st_spare2; /* reserved */
|
|
time_t st_ctime; /* time of last file status change */
|
|
int st_spare3; /* reserved */
|
|
long st_blksize;/* size in bytes of blocks on filesystem */
|
|
long st_blocks; /* blocks allocated for file */
|
|
long st_spare4[2]; /* reserved */
|
|
}
|
|
.fi
|
|
.LP
|
|
The items marked 'reserved' are not currently used but are reserved
|
|
for future expansion; do not use these fields for any reason.
|
|
.BR st_dev
|
|
is the number of the device on which the file resides. This number
|
|
is the same as the GS/OS device ID number.
|
|
.BR st_rdev
|
|
is not currently used, but may in the future designate a device type
|
|
code.
|
|
.LP
|
|
As short symbolic links are stored in the inode,
|
|
.IR st_blocks
|
|
may be zero.
|
|
.LP
|
|
The status information word
|
|
.I st_mode
|
|
has the following bits:
|
|
.nf
|
|
#define S_IFCHR 0020000 /* character special */
|
|
#define S_IFDIR 0040000 /* directory */
|
|
#define S_IFBLK 0060000 /* block special */
|
|
#define S_IFREG 0100000 /* regular */
|
|
#define S_IFLNK 0120000 /* symbolic link */
|
|
#define S_IFSOCK 0140000 /* socket */
|
|
#define S_IRUSR 0000400 /* read permission, owner */
|
|
#define S_IWUSR 0000200 /* write permission, owner */
|
|
#define S_IXUSR 0000100 /* execute/search permission, owner */
|
|
.fi
|
|
.LP
|
|
For a list of access modes, see <sys/stat.h>,
|
|
.BR access (2)
|
|
and
|
|
.BR chmod (2).
|
|
.SH RETURN VALUES
|
|
Upon successful completion a value of 0 is returned.
|
|
Otherwise, a value of -1 is returned and
|
|
.IR errno
|
|
is set to indicate the error.
|
|
.SH COMPATIBILITY
|
|
BSD uses a larger set of defined fields than does GNO. The types
|
|
of the fields also, in general, differ.
|
|
.LP
|
|
The
|
|
.BR stat
|
|
man page for GNO v2.0.4 documented the macros
|
|
.BR S_IREAD ,
|
|
.BR S_IWRITE ,
|
|
and
|
|
.BR S_IEXEC .
|
|
These macros are still available in <sys/stat.h> provided that
|
|
.BR _POSIX_SOURCE
|
|
is not defined.
|
|
.SH ERRORS
|
|
.BR Stat
|
|
and
|
|
.BR lstat
|
|
will fail if:
|
|
.RS
|
|
.IP \fBENOTDIR\fR
|
|
A component of the path prefix is not a directory.
|
|
.IP \fBENOENT\fR
|
|
The named file does not exist.
|
|
.IP \fBEBADF\fR
|
|
.IR fd
|
|
does not refer to an open file.
|
|
.RE
|
|
.LP
|
|
.RS
|
|
.BR Fstat
|
|
will fail if:
|
|
.IP \fBEBADF\fR
|
|
.I fd
|
|
is not a valid open file descriptor.
|
|
.IP \fBEIO\fR
|
|
An I/O error occurred while reading from or writing to the file system.
|
|
.RE
|
|
.SH SEE ALSO
|
|
.BR chmod (2),
|
|
.BR chown (2),
|
|
.BR utimes (2)
|
|
.BR symlink (7)
|
|
.SH BUGS
|
|
GNO does not yet support hard or symbolic file links on the IIgs. Therefore,
|
|
.BR lstat
|
|
operates exactly like
|
|
.BR stat .
|
|
If there's a case where
|
|
.BR lstat
|
|
might be more appropriate at a time when links are supported, then use
|
|
.BR lstat
|
|
instead and be ready for the future.
|
|
.LP
|
|
.BR fstat
|
|
doesn't do anything clever with all the unused fields when its argument is
|
|
a pipe or terminal.
|
|
.SH STANDARDS
|
|
The
|
|
.BR stat
|
|
and
|
|
.BR fstat
|
|
function calls are close, but do not conform, to IEEE Std 1003.1-1988 (POSIX).
|
|
In particular,
|
|
.RS
|
|
.LP
|
|
\- this implementation does not make the distinction of file ownership;
|
|
.LP
|
|
\- not all the required error return codes are implemented; and
|
|
.LP
|
|
\- file access time mirrors modification time.
|
|
.RE
|
|
.SH HISTORY
|
|
An
|
|
.BR lstat
|
|
function call appeared in 4.2BSD.
|