2.9BSD/usr/man/man2/qstat.2

.TH QSTAT 2 
.UC
.SH NAME
qstat, qfstat \- get extended file status
.SH SYNOPSIS
.B #include <sys/types.h>
.br
.B #include <sys/qstat.h>
.PP
.B qstat(name, buf)
.br
.B char *name;
.br
.B struct qstat *buf;
.PP
.B qfstat(fildes, buf)
.br
.B struct qstat *buf;
.SH DESCRIPTION
.I Qstat
obtains detailed information about a named file.
.I Qfstat
obtains the same information about an open file
known by the file descriptor from a successful
.I open, creat, dup
or
.IR pipe (2)
call.
.PP
.I Name
points to a null-terminated string naming
a file;
.I buf
is the address of a buffer
into which information is placed concerning the file.
It is unnecessary to have any
permissions at all with respect to the file, but all directories
leading to the file must be searchable.
The layout of the structure pointed to by buf
as defined in
.I <qstat.h>
is given below.
.PP
.nf
struct qstat
{
	char		qs_flag;
	char		qs_count;		/* reference count */
	dev_t	qs_dev;		/* device where inode resides */
	ino_t	qs_number;	/* i number, 1-to-1 with device address */
	u_short	qs_mode;
	short	qs_nlink;		/* directory entries */
	short	qs_uid;		/* owner */
	short	qs_gid;		/* group of owner */
	off_t	qs_size;		/* size of file */
	union {
		struct {
			daddr_t	qs_addr[NADDR];	/* if normal file/directory */
			daddr_t	qs_lastr;			/* last logical block read  */
		};
		struct {
			daddr_t	qs_rdev;			/* qs_addr[0] */
#ifdef	MPX_FILS
			struct group qs_group;		/* multiplexer group file */
#endif
		};
		struct {
			daddr_t	qs_qused;
			daddr_t	qs_qmax;
		};
	} qs_un;
	time_t	qs_atime;	/* access time */
	time_t	qs_mtime;	/* modification time */
	time_t	qs_ctime;	/* creation time */
};
.fi
.I Qs\_mode 
is encoded according to the `#define' statements in <sys/stat.h>.
The mode bits 0000070 and 0000007 encode group and
others permissions (see
.IR chmod (2)).
.PP
The defined types,
.I
daddr\_t, ino\_t, off\_t,
and
.I time\_t
name various width values;
.I dev\_t
encodes major and minor device numbers.
Their exact definitions are in
the include file <sys/types.h>
(see
.IR types (5)).
.PP
When
.I fildes
is associated with a pipe,
.I qfstat
reports an ordinary file
with restricted permissions.
The size is the number of bytes queued in the pipe.
.PP
.I Qs\_atime
is the time the file was last read.
For reasons of efficiency, it is not set when a directory
is searched, although this would be more logical.
.I Qs\_mtime
is the time the file was last written or created.
It is not set by changes of owner, group, link count, or mode.
.I Qs\_ctime
is set both both by writing and changing the i-node.
.SH ERRORS
.I Qstat
will fail if:
.TP 20
[EINVAL]
The path name contains a non-ASCII byte.
.TP 20
[ENOTDIR]
A component of the path prefix is not a directory.
.TP 20
[EACCES]
A component of the path prefix denies search permission.
.TP 20
[EFAULT]
.IR Buf " or " name
points outside the process's allocated address space.
.TP 20
[ELOOP]
Too many symbolic links were encountered in translating the path name.
.PP
.I Qstatf
will fail if:
.TP 20
[EBADF]
.I Fildes
is not a valid open descriptor.
.TP 20
[EFAULT]
.I Buf
points outside the process's allocated address space.
.SH "SEE ALSO"
file(1), ls(1), pq(1), quota(2), stat(2), filsys(5), setquota(8)
.SH ASSEMBLER
.nf
(local = 58., qfstat = 11.)
.B sys local; 9f
\&. . .
.B \&.data
.B 9: sys qfstat; fildes; buf
.sp
(local = 58. qfstat = 12.)
.B sys local; 9f
\&. . .
.B \&.data
.B 9: sys qstat; name; buf
.fi