.TH stat() "" "" " "System Call (libc)"
.PC "Find file attributes"
.B "#include <sys/stat.h>"
\fBint stat(\fIfile, statptr\^\fB)\fR
\fBchar *\fIfile\^\fB; struct stat *\fIstatptr\^\fB;\fR
.PP
.B stat()
returns a structure that contains
the attributes of a file, including
protection information, file type,
and file size.
.PP
.I file
points to the path name of file.
.I statptr
points to a structure of the type
.BR stat ,
as defined in the header file
.BR stat.h .
For information on
.BR stat ,
see the Lexicon entry for
.BR stat.h .
.SH Example
The following example uses
.B stat()
to print a file's status.
.DM
#include <sys/stat.h>
main()
{
	struct stat sbuf;
	int status;
.DE
.DM
	if (status = stat("/usr/include", &sbuf)) {
		printf("Can't find\en");
		exit(EXIT_FAILURE);
	}
.DE
.DM
	printf("uid = %d gid = %d\en", sbuf.st_uid, sbuf.st_gid);
}
.DE
.SH "See Also"
.Xr "chmod()," chmod.s
.Xr "chown()," chown.s
.Xr "libc," libc
.Xr "ls," ls
.Xr "open()," open
.Xr "stat.h" stat.h
.br
\*(PX Standard, \(sc5.6.2
.SH Diagnostics
.B stat()
returns \-1 if an error occurs, e.g., the file cannot be found.
Otherwise, it returns zero.
.SH Notes
.B stat()
differs from the related function
.B fstat()
mainly in that
.B fstat()
accesses the file through its descriptor, which was
returned by a successful call to
.BR open() ,
whereas
.B stat()
takes the file's path name and opens it before checking its status.
.PP
The call
.DM
	stat("", &s)
.DE
.PP
is identical to
.DM
	stat(".", &s)
.DE
.PP
Both calls succeed.
The \*(PX forbids the former call \(em in fact, the \*(PX forbids
the NULL string as a path name under any circumstances;
therefore you should never use the former call.
