huschi.net

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

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
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
       implementation-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  con-
       tinue  pathname resolution 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 Definitions 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 mechanisms" is to allow a secure implementation where  a
       process  with  a  label  that does not dominate the file's label cannot
       perform a stat() function. This is not related to  read  permission;  a
       process with a label that dominates the file's label does not need read
       permission. 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 original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                             STAT(3P)