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/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 function lstat() 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-
     ences.  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> and into which information is	placed concerning the file.

   The Standard	Structure
     The following standards-compliant fields are defined in the structure:

	   Type	       Entry	    Description
	   dev_t       st_dev	    device ID containing the file
	   ino_t       st_ino	    serial number of the file
	   mode_t      st_mode	    mode of the	file
	   nlink_t     st_nlink	    number of hard links to the	file
	   uid_t       st_uid	    user ID of the owner
	   gid_t       st_gid	    group ID of	the owner
	   dev_t       st_rdev	    device type	(character or block special)
	   off_t       st_size	    size of the	file in	bytes
	   time_t      st_atime	    time of last access
	   time_t      st_mtime	    time of last data modification
	   time_t      st_ctime	    time of last file status change
	   blksize_t   st_blksize   preferred I/O block	size (fs-specific)
	   blkcnt_t    st_blocks    blocks allocated for the file

     These are specified in the	IEEE Std 1003.1-2004 ("POSIX.1") standard.
     The st_ino	and st_dev fields taken	together uniquely identify the file
     within the	system.	 Most of the types are defined in types(3).

     The time-related fields are:

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

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

	   st_ctime    Time when file status was last changed (file metadata
		       modification).  Changed by the chflags(2), chmod(2),
		       chown(2), link(2), mknod(2), rename(2), unlink(2),
		       utimes(2), and write(2) system calls.

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

	   st_size     The size	of the file in bytes.  The meaning of the size
		       reported	for a directory	is file	system dependent.
		       Some file systems (e.g. FFS) return the total size used
		       for the directory metadata, possibly including free
		       slots; others (notably ZFS) return the number of	en-
		       tries in	the directory.	Some may also return other
		       things or always	report zero.

	   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 contains bits that define the access
     mode (see chmod(2)) and the type (see dirent(3)) of the file.  The	fol-
     lowing macros can be used to test whether a file is of the	specified
     type.  The	value m	supplied to the	macros is the value of st_mode.

	   S_ISBLK(m)	Test for a block special file.

	   S_ISCHR(m)	Test for a character special file.

	   S_ISDIR(m)	Test for a directory.

	   S_ISFIFO(m)	Test for a pipe	or FIFO	special	file.

	   S_ISREG(m)	Test for a regular file.

	   S_ISLNK(m)	Test for a symbolic link.

	   S_ISSOCK(m)	Test for a socket.

     The macros	evaluate to a non-zero value if	the test is true or to the
     value 0 if	the test is false.

   NetBSD Extensions
     The following additional NetBSD specific fields are present:

	   Type	       Entry		   Description
	   long	       st_atimensec	   last	access (nanoseconds)
	   long	       st_mtimensec	   last	modification (nanoseconds)
	   long	       st_ctimensec	   last	status change (nanoseconds)
	   time_t      st_birthtime	   time	of inode creation
	   long	       st_birthtimensec	   inode creation (nanoseconds)
	   uint32_t    st_flags		   user	defined	flags for the file
	   uint32_t    st_gen		   file	generation number
	   uint32_t    st_spare[2]	   implementation detail

     However, if _NETBSD_SOURCE	is furthermore defined,	instead	of the above,
     the following are present in the structure:

	   Type		       Entry		   Description
	   struct timespec     st_atimespec	   time	of last	access
	   struct timespec     st_mtimespec	   time	of last	modification
	   struct timespec     st_birthtimespec	   time	of creation
	   uint32_t	       st_flags		   user	defined	flags
	   uint32_t	       st_gen		   file	generation number
	   uint32_t	       st_spare[2]	   implementation detail

     In	this case the following	macros are provided for	convenience:

	   #if defined(_NETBSD_SOURCE)
	     #define st_atime		     st_atimespec.tv_sec
	     #define st_atimensec	     st_atimespec.tv_nsec
	     #define st_mtime		     st_mtimespec.tv_sec
	     #define st_mtimensec	     st_mtimespec.tv_nsec
	     #define st_ctime		     st_ctimespec.tv_sec
	     #define st_ctimensec	     st_ctimespec.tv_nsec
	     #define st_birthtime	     st_birthtimespec.tv_sec
	     #define st_birthtimensec	     st_birthtimespec.tv_nsec

     The status	information word st_flags has the following bits:

	   Constant	       Description
	   UF_NODUMP	       do not dump a file
	   UF_IMMUTABLE	       file may	not be changed
	   UF_APPEND	       writes to file may only append
	   UF_OPAQUE	       directory is opaque wrt.	union
	   SF_ARCHIVED	       file is archived
	   SF_IMMUTABLE	       file may	not be changed
	   SF_APPEND	       writes to file may only append

     For a description of the flags, see chflags(2).

     Upon successful completion	a value	of 0 is	returned.  Otherwise, a	value
     of	-1 is returned and errno is set	to indicate the	error.

     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.

     stat() and	lstat()	will fail if:

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

     [EBADF]		A badly	formed vnode was encountered.  This can	happen
			if a file system information node is incorrect.

     [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 {NAME_MAX} charac-
			ters, or an entire path	name exceeded {PATH_MAX} char-

     [ENOENT]		The named file does not	exist.

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

     [ENXIO]		The named file is a character special or block special
			file, and the device associated	with this special file
			does not exist.

     fstat() 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.

     chflags(2), chmod(2), chown(2), utimes(2),	dirent(3), types(3),

     The described functions conform to	IEEE Std 1003.1-2004 ("POSIX.1").

     A stat() function call appeared in	Version	2 AT&T UNIX.  A	lstat()	func-
     tion call appeared	in 4.2BSD.

     Applying fstat() to a socket (and thus to a pipe) returns a zero'd	buf-
     fer, except for the blocksize field, and a	unique device and file serial

BSD			      September	14, 2011			   BSD


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

home | help