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

FreeBSD Manual Pages


home | help
stat(2)								       stat(2)

       stat, lstat, fstat - get	file status

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

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

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

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

       The  system call	obtains	information about the file path.  Read,	write,
       or execute permission of	the named file is not required,	but all	direc-
       tories specified	in the path name that leads to the file	must be	reach-

       The system call is like except when a named file	is  a  symbolic	 link.
       In  this	instance, returns information about the	link; returns informa-
       tion about the file that	is referenced by the link.

       The system call and the system call obtain the same  information	 about
       an open file referenced by the argument descriptor.

       The  buf	 is  a	pointer	 to  a structure.  Information about a file is
       placed in the structure.	 The contents of the structure pointed	to  by
       buf includes the	following: struct stat {
	 dev_t	 st_dev;    /* device inode resides on */
	 ino_t	 st_ino;    /* this inode's number */
	 u_short st_mode;   /* protection */
	 short	 st_nlink;  /* number or hard links to the file	*/
	 short	 st_uid;    /* user-id of owner	*/
	 short	 st_gid;    /* group-id	of owner */
	 dev_t	 st_rdev;   /* the device type,	for inode that is device */
	 off_t	 st_size;   /* total size of file */
	 time_t	 st_atime;  /* file last access	time */
	 int	 st_spare1;
	 time_t	 st_mtime;   /*	file last modify time */
	 int	 st_spare2;
	 time_t	 st_ctime;   /*	file last status change	time */
	 int	 st_spare3;
	 long st_blksize; /* optimal blocksize for file	system i/o ops */
	 long st_blocks;  /* actual number of blocks allocated */
	 long st_spare4;
	 u_long	st_gennum; /* file generation number */

       st_atime	   The time when file data was last accessed.  This is changed
		   by the system calls and For efficiency, st_atime is not set
		   when	a directory is searched.

       st_mtime	   The	time  when  data  was last modified.  It is not	set by
		   changes of owner,  group,  link  count,  or	mode.	It  is
		   changed by the system calls and

       st_ctime	   The	time  when file	status was last	changed.  It is	set by
		   writing and changing	the i-node. It can be changed  by  the
		   following system calls: and

       The  status  information	 word  st_mode has the following bits: #define
       S_IFMT	0170000	/* type	of file	*/ #define S_IFDIR  0040000 /*	direc-
       tory  */	 #define  S_IFCHR   0020000  /*	 character  special */ #define
       S_IFBLK	0060000	/* block special */ #define S_IFREG  0100000 /*	 regu-
       lar  */	#define	 S_IFLNK  0120000 /* symbolic link */ #define S_IFSOCK
       0140000 /* socket */ #define S_IFIFO  0010000 /*	FIFO - named  pipe  */
       #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_IREAD  0000400 /* read
       permission, owner */ #define  S_IWRITE  0000200	/*  write  permission,
       owner  */  #define S_IEXEC  0000100 /* execute/search permission, owner
       */ The mode bits	0000070	and 0000007 encode group  and  others  permis-
       sions.  For further information,	see

       When  fd	 is associated with a pipe, returns a buffer with only st_blk-
       size set.


       Unlike the System V definition, ELOOP is	a possible error condition.

       Applying	to a socket returns a zeroed buffer and	[EOPNOTSUPP].

       The fields in the  stat	structure  marked  st_spare1,  st_spare2,  and
       st_spare3  are  used  when  inode time stamps expand to 64 bits.	 This,
       however,	can break certain programs that	 depend	 on  the  time	stamps
       being contiguous	in calls to

Return Values
       Upon  successful	 completion,  a	value of zero (0) is returned.	Other-
       wise, a value of	-1 is returned and errno is set	to indicate the	error.

       The and system calls fail if any	of the following is true:

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

       [EFAULT]	      The buf 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 translating
		      the pathname.

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

       [ENOENT]	      The named	file does not exist or path points to an empty
		      string and the environment  defined  is  POSIX  or  SYS-

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

       The system call fails if	one or more of the following are true:

       [EBADF]	      The fildes is not	a valid	open file descriptor.

       [EFAULT]	      The buf points to	an invalid address.

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

       [EOPNOTSUPP]   The file descriptor points to a socket.

       [ETIMEDOUT]    A	 connect  request  or  remote  file  operation	failed
		      because  the  connected  party  did  not respond after a
		      period of	time determined	by the	communications	proto-

See Also
       chmod(2),  chown(2),  link(2), mknod(2),	read(2), unlink(2), utimes(2),


Name | Syntax | Description | Environment | Restrictions | Return Values | Diagnostics | See Also

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

home | help