Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
STAT(2)			    BSD	System Calls Manual		       STAT(2)

     stat, lstat, fstat	-- get file status

     Standard C	Library	(libc, -lc)

     #include <sys/types.h>
     #include <sys/stat.h>

     stat(const	char *path, struct stat	*sb);

     lstat(const char *path, struct stat *sb);

     fstat(int fd, struct stat *sb);

     The stat()	function obtains information about the file pointed to by
     path.  Read, write	or execute permission of the named file	is not re-
     quired, but all directories listed	in the path name leading to the	file
     must be searchable.

     The lstat() function is like stat() except	in the case where the named
     file is a symbolic	link, in which case lstat() returns information	about
     the link, while stat() returns information	about the file the link	refer-

     The fstat() function obtains the same information about an	open file
     known by the file descriptor fd.

     The sb argument is	a pointer to a stat structure as defined by
     <sys/stat.h> (shown below)	and into which information is placed concern-
     ing the file.

     struct stat {
	 dev_t	   st_dev;		 /* inode's device */
	 ino_t	   st_ino;		 /* inode's number */
	 mode_t	   st_mode;		 /* inode protection mode */
	 nlink_t   st_nlink;		 /* number of hard links */
	 uid_t	   st_uid;		 /* user ID of the file's owner	*/
	 gid_t	   st_gid;		 /* group ID of	the file's group */
	 dev_t	   st_rdev;		 /* device type	*/
     #ifndef _POSIX_SOURCE
	 struct	timespec st_atimespec;	/* time	of last	access */
	 struct	timespec st_mtimespec;	/* time	of last	data modification */
	 struct	timespec st_ctimespec;	/* time	of last	file status change */
	 time_t	   st_atime;		 /* time of last access	*/
	 long	   st_atimensec;	 /* nsec of last access	*/
	 time_t	   st_mtime;		 /* time of last data modification */
	 long	   st_mtimensec;	 /* nsec of last data modification */
	 time_t	   st_ctime;		 /* time of last file status change */
	 long	   st_ctimensec;	 /* nsec of last file status change */
	 off_t	   st_size;		 /* file size, in bytes	*/
	 int64_t   st_blocks;		 /* blocks allocated for file */
	 u_int32_t st_blksize;		 /* optimal blocksize for I/O */
	 fflags_t  st_flags;		 /* user defined flags for file	*/
	 u_int32_t st_gen;		 /* file generation number */

     The time-related fields of	struct stat are	as follows:

     st_atime	  Time when file data last accessed.  Changed by the mknod(2),
		  utimes(2) and	read(2)	system calls.

     st_mtime	  Time when file data last modified.  Changed by the mknod(2),
		  utimes(2) and	write(2) system	calls.

     st_ctime	  Time when file status	was last changed (inode	data modifica-
		  tion).  Changed by the chmod(2), chown(2), link(2),
		  mknod(2), rename(2), unlink(2), utimes(2) and	write(2) sys-
		  tem calls.

     If	_POSIX_SOURCE is not defined, the time-related fields are defined as:

     #ifndef _POSIX_SOURCE
     #define st_atime st_atimespec.tv_sec
     #define st_mtime st_mtimespec.tv_sec
     #define st_ctime st_ctimespec.tv_sec

     The size-related fields of	the struct stat	are as follows:

     st_blksize	    The	optimal	I/O block size for the file.

     st_blocks	    The	actual number of blocks	allocated for the file in
		    512-byte units.  As	short symbolic links are stored	in the
		    inode, this	number may be zero.

     The status	information word st_mode has the following bits:

     #define S_IFMT   0170000  /* type of file */
     #define S_IFIFO  0010000  /* named	pipe (fifo) */
     #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_IFWHT  0160000  /* whiteout */
     #define S_ISUID  0004000  /* set user id on execution */
     #define S_ISGID  0002000  /* set group id on execution */
     #define S_ISVTX  0001000  /* save swapped text even after use */
     #define S_IRUSR  0000400  /* read permission, owner */
     #define S_IWUSR  0000200  /* write	permission, owner */
     #define S_IXUSR  0000100  /* execute/search permission, owner */

     For a list	of access modes, see <sys/stat.h>, access(2) and chmod(2).

     Upon successful completion, the value 0 is	returned; otherwise the
     value -1 is returned and the global variable errno	is set to indicate the

     Previous versions of the system used different types for the st_dev,
     st_uid, st_gid, st_rdev, st_size, st_blksize and st_blocks	fields.

     The stat()	and lstat() functions will fail	if:

     [EACCES]		Search permission is denied for	a component of the
			path prefix.

     [EFAULT]		sb or name points to an	invalid	address.

     [EIO]		An I/O error occurred while reading from or writing to
			the file system.

     [ELOOP]		Too many symbolic links	were encountered in translat-
			ing the	pathname.

     [ENAMETOOLONG]	A component of a pathname exceeded 255 characters, or
			an entire path name exceeded 1023 characters.

     [ENOENT]		The named file does not	exist.

     [ENOTDIR]		A component of the path	prefix is not a	directory.

     [EOVERFLOW]	The file size in bytes cannot be represented correctly
			in the structure pointed to by sb.

     The fstat() function will fail if:

     [EBADF]		fd is not a valid open file descriptor.

     [EFAULT]		sb points to an	invalid	address.

     [EIO]		An I/O error occurred while reading from or writing to
			the file system.

     [EOVERFLOW]	The file size in bytes cannot be represented correctly
			in the structure pointed to by sb.

     access(2),	chmod(2), chown(2), utimes(2), symlink(7)

     Applying fstat() to a socket (and thus to a pipe) returns a zeroed	buf-
     fer, except for the blocksize field, and a	unique device and inode	num-

     The stat()	and fstat() function calls are expected	to conform to ISO/IEC
     9945-1:1990 ("POSIX.1").

     A stat() and a fstat() function call appeared in Version 7	AT&T UNIX.  A
     lstat() function call appeared in 4.2BSD.

BSD			       February	15, 2002			   BSD


Want to link to this manual page? Use this URL:

home | help