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

FreeBSD Manual Pages

  
 
  

home | help
STAT(2V)							      STAT(2V)

NAME
       stat, lstat, fstat - get	file status

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

       int stat(path, buf)
       char *path;
       struct stat *buf;

       int lstat(path, buf)
       char *path;
       struct stat *buf;

       int fstat(fd, buf)
       int fd;
       struct stat *buf;

DESCRIPTION
       stat()  obtains	information about the file named by path.  Read, write
       or execute permission of	the named file is not required,	but all	direc-
       tories listed in	the path name leading to the file must be searchable.

       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.

       fstat() obtains the same	information about an open file	referenced  by
       the argument descriptor,	such as	would be obtained by an	open(2V) call.

       buf  is	a pointer to a stat structure into which information is	placed
       concerning the file.  A stat structure includes the following members:

	      dev_t	st_dev;	       /* device file resides on */
	      ino_t	st_ino;	       /* the file serial number */
	      mode_t	st_mode;       /* file mode */
	      nlink_t	st_nlink;      /* number of 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;       /* the device identifier	(special files only)*/
	      off_t	st_size;       /* total	size of	file, in bytes */
	      time_t	st_atime;      /* file last access time	*/
	      time_t	st_mtime;      /* file last modify time	*/
	      time_t	st_ctime;      /* file last status change time */
	      long	st_blksize;    /* preferred blocksize for file system I/O*/
	      long	st_blocks;     /* actual number	of blocks allocated */

       st_atime	   Time	when file data was last	accessed.  This	 can  also  be
		   set	explicitly  by utimes(2).  st_atime is not updated for
		   directories searched	during pathname	resolution.

       st_mtime	   Time	when file data was last	modified.  This	 can  also  be
		   set	explicitly  by utimes(2).  It is not set by changes of
		   owner, group, link count, or	mode.

       st_ctime	   Time	when file status was last changed.   It	 is  set  both
		   both	 by  writing and changing the file status information,
		   such	as changes of owner, group, link count,	or mode.

       The following macros test whether a file	is of the specified type.  The
       value  m	 is  the value of st_mode.  Each macro evaluates to a non-zero
       value if	the test is true or to zero if the test	is false.

       S_ISDIR(m)     Test for directory file.

       S_ISCHR(m)     Test for character special file.

       S_ISBLK(m)     Test for block special file.

       S_ISREG(m)     Test for regular file.

       S_ISLNK(m)     Test for a symbolic link.

       S_ISSOCK(m)    Test for a socket.

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

       The status information word st_mode is bit-encoded using	the  following
       masks and bits:

       S_IRWXU	      Read, write, search (if a	directory), or execute (other-
		      wise) permissions	mask for the owner of the file.

		      S_IRUSR	     Read permission bit for the owner of  the
				     file.

		      S_IWUSR	     Write permission bit for the owner	of the
				     file.

		      S_IXUSR	     Search (if	a directory) or	execute	 (oth-
				     erwise)  permission  bit for the owner of
				     the file.

       S_IRWXG	      Read, write, search (if directory), or  execute  (other-
		      wise) permissions	mask for the file group	class.

		      S_IRGRP	     Read  permission  bit  for	the file group
				     class.

		      S_IWGRP	     Write permission bit for the  file	 group
				     class.

		      S_IXGRP	     Search  (if a directory) or execute (oth-
				     erwise) permission	bit for	the file group
				     class.

       S_IRWXO	      Read, write, search (if a	directory), or execute (other-
		      wise) permissions	mask for the file other	class.

		      S_IROTH	     Read permission bit for  the  file	 other
				     class.

		      S_IWOTH	     Write  permission	bit for	the file other
				     class.

		      S_IXOTH	     Search (if	a directory) or	execute	 (oth-
				     erwise) permission	bit for	the file other
				     class.

       S_ISUID	      Set user ID on execution.	 The process's effective  user
		      ID is set	to that	of the owner of	the file when the file
		      is run as	a program  (see	 execve(2V)).	On  a  regular
		      file, this bit should be cleared on any write.

       S_ISGID	      Set  group  ID  on  execution.   The process's effective
		      group ID is set to that of the file when the file	is run
		      as  a program (see execve(2V)).  On a regular file, this
		      bit should be cleared on any write.

       In addition, the	following bits and masks are made available for	 back-
       ward compatibility:
	      #define	 S_IFMT		0170000	 /* type of file */
	      #define	 S_IFIFO	0010000	 /* FIFO special */
	      #define	 S_IFCHR	0020000	 /* character special */
	      #define	 S_IFDIR	0040000	 /* directory */
	      #define	 S_IFBLK	0060000	 /* block special */
	      #define	 S_IFREG	0100000	 /* regular file */
	      #define	 S_IFLNK	0120000	 /* symbolic link */
	      #define	 S_IFSOCK	0140000	 /* socket */
	      #define	 S_ISVTX	0001000	 /* save swapped text even after use */
	      #define	 S_IREAD	0000400	 /* read permission, owner */
	      #define	 S_IWRITE	0000200	 /* write permission, owner */
	      #define	 S_IEXEC	0000100	 /* execute/search permission, owner */

       For more	information on st_mode bits see	chmod(2V).

RETURN VALUES
       stat(), lstat() and fstat() return:

       0      on success.

       -1     on failure and set errno to indicate the error.

ERRORS
       stat() and lstat() will fail if one or more of the following are	true:

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

       EFAULT		   buf or path 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	trans-
			   lating path.

       ENAMETOOLONG	   The	 length	  of   the   path   argument   exceeds
			   {PATH_MAX}.n

			   A  pathname	component  is  longer  than {NAME_MAX}
			   while {_POSIX_NO_TRUNC} is  in  effect  (see	 path-
			   conf(2V)).

       ENOENT		   The file referred to	by path	does not exist.

       ENOTDIR		   A component of the path prefix of path is not a di-
			   rectory.

       fstat() will fail if one	or more	of the following are true:

       EBADF		   fd is not a valid open file descriptor.

       EFAULT		   buf points to an invalid address.

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

SYSTEM V ERRORS
       In addition to the above, the following may also	occur:

       ENOENT		   path	points to an empty string.

WARNINGS
       The  st_atime  and  st_mtime  fields  of	the stat() are not contiguous.
       Programs	that depend on them being contiguous (in calls to utimes(2) or
       utime(3V)) will not work.

SEE ALSO
       chmod(2V),  chown(2V),  link(2V),  open(2V), read(2V), readlink(2), re-
       name(2V), truncate(2), unlink(2V), utimes(2), write(2V)

				21 January 1990			      STAT(2V)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SYSTEM V ERRORS | WARNINGS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=stat&sektion=2v&manpath=SunOS+4.1.3>

home | help