Unix/Linux Go Back    


Linux 2.6 - man page for stat (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


STAT(P) 			    POSIX Programmer's Manual				  STAT(P)

NAME
       stat - get file status

SYNOPSIS
       #include <sys/stat.h>

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

DESCRIPTION
       The stat() function shall obtain information about the named file and write it to the area
       pointed to by the buf argument. The path argument points to  a  pathname  naming  a  file.
       Read,  write,  or  execute permission of the named file is not required. An implementation
       that provides additional or alternate file access control mechanisms may, under	implemen-
       tation-defined  conditions,  cause  stat() to fail. In particular, the system may deny the
       existence of the file specified by path.

       If the named file is a symbolic link, the stat() function shall continue pathname  resolu-
       tion  using  the contents of the symbolic link, and shall return information pertaining to
       the resulting file if the file exists.

       The buf argument is a pointer to a stat structure, as defined in the <sys/stat.h>  header,
       into which information is placed concerning the file.

       The stat() function shall update any time-related fields (as described in the Base Defini-
       tions volume of IEEE Std 1003.1-2001, Section 4.7, File Times Update), before writing into
       the stat structure.

       Unless otherwise specified, the structure members st_mode, st_ino, st_dev, st_uid, st_gid,
       st_atime, st_ctime, and st_mtime shall have meaningful values for all file  types  defined
       in  this  volume of IEEE Std 1003.1-2001. The value of the member st_nlink shall be set to
       the number of links to the file.

RETURN VALUE
       Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno
       set to indicate the error.

ERRORS
       The stat() function shall fail if:

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

       EIO    An error occurred while reading from the file system.

       ELOOP  A loop exists in symbolic links encountered during resolution of the path argument.

       ENAMETOOLONG
	      The  length  of  the  path  argument  exceeds {PATH_MAX} or a pathname component is
	      longer than {NAME_MAX}.

       ENOENT A component of path does not name an existing file or path is an empty string.

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

       EOVERFLOW
	      The file size in bytes or the number of blocks allocated to the file  or	the  file
	      serial number cannot be represented correctly in the structure pointed to by buf.

       The stat() function may fail if:

       ELOOP  More  than  {SYMLOOP_MAX}  symbolic links were encountered during resolution of the
	      path argument.

       ENAMETOOLONG
	      As a result of encountering a symbolic link in resolution of the path argument, the
	      length of the substituted pathname string exceeded {PATH_MAX}.

       EOVERFLOW
	      A value to be stored would overflow one of the members of the stat structure.

       The following sections are informative.

EXAMPLES
   Obtaining File Status Information
       The  following  example	shows  how  to	obtain	file  status information for a file named
       /home/cnd/mod1. The structure variable buffer is defined for the stat structure.

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

	      struct stat buffer;
	      int	  status;
	      ...
	      status = stat("/home/cnd/mod1", &buffer);

   Getting Directory Information
       The following example fragment gets status information for each entry in a directory.  The
       call  to  the  stat() function stores file information in the stat structure pointed to by
       statbuf. The lines that follow the stat() call format the fields in the stat structure for
       presentation to the user of the program.

	      #include <sys/types.h>
	      #include <sys/stat.h>
	      #include <dirent.h>
	      #include <pwd.h>
	      #include <grp.h>
	      #include <time.h>
	      #include <locale.h>
	      #include <langinfo.h>
	      #include <stdio.h>
	      #include <stdint.h>

	      struct dirent  *dp;
	      struct stat     statbuf;
	      struct passwd  *pwd;
	      struct group   *grp;
	      struct tm      *tm;
	      char	      datestring[256];
	      ...
	      /* Loop through directory entries. */
	      while ((dp = readdir(dir)) != NULL) {

		  /* Get entry's information. */
		  if (stat(dp->d_name, &statbuf) == -1)
		      continue;

		  /* Print out type, permissions, and number of links. */
		  printf("%10.10s", sperm (statbuf.st_mode));
		  printf("%4d", statbuf.st_nlink);

		  /* Print out owner's name if it is found using getpwuid(). */
		  if ((pwd = getpwuid(statbuf.st_uid)) != NULL)
		      printf(" %-8.8s", pwd->pw_name);
		  else
		      printf(" %-8d", statbuf.st_uid);

		  /* Print out group name if it is found using getgrgid(). */
		  if ((grp = getgrgid(statbuf.st_gid)) != NULL)
		      printf(" %-8.8s", grp->gr_name);
		  else
		      printf(" %-8d", statbuf.st_gid);

		  /* Print size of file. */
		  printf(" %9jd", (intmax_t)statbuf.st_size);

		  tm = localtime(&statbuf.st_mtime);

		  /* Get localized date string. */
		  strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm);

		  printf(" %s %s\n", datestring, dp->d_name);
	      }

APPLICATION USAGE
       None.

RATIONALE
       The intent of the paragraph describing "additional or alternate file access control mecha-
       nisms" is to allow a secure implementation where a process with a label that does not dom-
       inate  the file's label cannot perform a stat() function. This is not related to read per-
       mission; a process with a label that dominates the file's label does not need read permis-
       sion.  An  implementation  that	supports  write-up operations could fail fstat() function
       calls even though it has a valid file descriptor open for writing.

FUTURE DIRECTIONS
       None.

SEE ALSO
       fstat()	,  lstat()  ,  readlink()  ,  symlink()  ,  the  Base	Definitions   volume   of
       IEEE Std 1003.1-2001, <sys/stat.h>, <sys/types.h>

COPYRIGHT
       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable	Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute of Electrical and Electronics Engineers, Inc and  The  Open  Group.  In  the
       event  of  any  discrepancy  between this version and the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					  STAT(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 07:56 AM.