unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

stat(2)                          System Calls                          stat(2)



NAME
       stat, lstat, fstat, fstatat - get file status

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

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

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

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

       int fstatat(int fildes, const char *path, struct stat *buf, int flag);

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

       The lstat() function obtains file attributes similar to stat(),  except
       when  the  named  file is a symbolic link; in that case lstat() returns
       information about the link, while stat() returns information about  the
       file the link references.

       The  fstat()  function  obtains information about an open file known by
       the  file  descriptor  fildes,  obtained  from  a  successful  open(2),
       creat(2), dup(2), fcntl(2), or pipe(2) function. If fildes references a
       shared memory object, the system updates in the stat structure  pointed
       to  by  the  buf argument only the st_uid, st_gid, st_size, and st_mode
       fields, and only the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP,  S_IROTH,  and
       S_IWOTH file permission bits need be valid. The system can update other
       fields and flags. The fstat() function updates any pending time-related
       fields before writing to the stat structure.

       The  fstatat()  function obtains file attributes similar to the stat(),
       lstat(), and fstat() functions.  If the path  argument  is  a  relative
       path,  it  is  resolved relative to the fildes argument rather than the
       current working directory.  If path is absolute, the fildes argument is
       unused.   If  the fildes argument has the special value AT_FDCWD, rela-
       tive paths are resolved from the current  working  directory.   If  the
       flag  argument is AT_SYMLNK_NOFOLLOW, the function behaves like lstat()
       and does not automatically follow symbolic links. See fsattr(5).

       The buf argument is a pointer to a stat structure into  which  informa-
       tion  is placed concerning the file. A stat structure includes the fol-
       lowing members:

       mode_t   st_mode;                /* File mode (see mknod(2)) */
       ino_t    st_ino;                 /* Inode number */
       dev_t    st_dev;                 /* ID of device containing */
                                        /* a directory entry for this file */
       dev_t    st_rdev;                /* ID of device */
                                        /* This entry is defined only for */
                                        /* char special or block special files */
       nlink_t  st_nlink;               /* Number of links */
       uid_t    st_uid;                 /* User ID of the file's owner */
       gid_t    st_gid;                 /* Group ID of the file's group */
       off_t    st_size;                /* File size 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 */
                                        /* Times measured in seconds since */
                                        /* 00:00:00 UTC, Jan. 1, 1970 */
       long     st_blksize;             /* Preferred I/O block size */
       blkcnt_t st_blocks;              /* Number of 512 byte blocks allocated*/
       char     st_fstype[_ST_FSTYPSZ]; /* Null-terminated type of filesystem */


       Descriptions of structure members are as follows:

       st_mode         The mode of the file as described for the mknod() func-
                       tion.  In  addition  to  the  modes  described  on  the
                       mknod(2) manual page, the mode of a file  can  also  be
                       S_IFSOCK  if the file is a socket, S_IFDOOR if the file
                       is a door, S_IFPORT if the file is an  event  port,  or
                       S_IFLNK  if the file is a symbolic link. S_IFLNK can be
                       returned either by  lstat()  or  by  fstat()  when  the
                       AT_SYMLNK_NOFOLLOW flag is set.



       st_ino          This field uniquely identifies the file in a given file
                       system. The pair  st_ino and  st_dev  uniquely  identi-
                       fies regular files.



       st_dev          This  field  uniquely  identifies  the file system that
                       contains the file. Its value may be used  as  input  to
                       the  ustat()  function  to  determine  more information
                       about this file system. No other meaning is  associated
                       with this value.



       st_rdev         This  field  should be used only by administrative com-
                       mands. It is valid only for block special or  character
                       special  files and only has meaning on the system where
                       the file was configured.



       st_nlink        This field should be used only by  administrative  com-
                       mands.



       st_uid          The user ID of the file's owner.



       st_gid          The group ID of the file's group.



       st_size         For  regular  files,  this is the address of the end of
                       the file. For block special or character special,  this
                       is not defined. See also pipe(2).



       st_atime        Time  when  file data was last accessed. Changed by the
                       following   functions:   creat(),   mknod(),    pipe(),
                       utime(2), and read(2).



       st_mtime        Time  when  data was last modified. Changed by the fol-
                       lowing functions: creat(),  mknod(),  pipe(),  utime(),
                       and write(2).



       st_ctime        Time  when file status was last changed. Changed by the
                       following   functions:   chmod(),   chown(),   creat(),
                       link(2),   mknod(),  pipe(),  unlink(2),  utime(),  and
                       write().



       st_blksize      A hint as to the "best" unit size for  I/O  operations.
                       This  field is not defined for block special or charac-
                       ter special files.



       st_blocks       The total number of physical blocks of size  512  bytes
                       actually  allocated  on disk. This field is not defined
                       for block special or character special files.



       st_fstype       A null-teminated string that  uniquely  identifies  the
                       type of the filesystem that contains the file.



RETURN VALUES
       Upon  successful  completion,  0 is returned. Otherwise, -1 is returned
       and errno is set to indicate the error.

ERRORS
       The stat(), fstat(), lstat(), and fstatat() functions will fail if:

       EIO             An error occurred while reading from the file system.



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



       The stat(), lstat(), and fstatat() functions will fail if:

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



       EFAULT          The  buf or path argument points to an illegal address.



       EINTR           A signal was caught during the execution of the  stat()
                       or lstat() function.



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



       ENAMETOOLONG    The length of the path argument exceeds {PATH_MAX},  or
                       the length of a path component exceeds {NAME_MAX} while
                       _POSIX_NO_TRUNC is in effect.



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



       ENOLINK         The  path  argument  points to a remote machine and the
                       link to that machine is no longer active.



       ENOTDIR         A component of the path prefix is not a  directory,  or
                       the fildes argument does not refer to a valid directory
                       when given a non-null relative path.



       The fstat() and fstatat() functions will fail if:

       EBADF           The fildes argument is not a valid open  file  descrip-
                       tor. The fildes argument to fstatat() can also have the
                       valid value of AT_FDCWD.



       EFAULT          The buf argument points to an illegal address.



       EINTR           A signal was caught during the execution of the fstat()
                       function.



       ENOLINK         The  fildes argument points to a remote machine and the
                       link to that machine is no longer active.



       The stat(), fstat(), and lstat() functions may fail if:

       EOVERFLOW       One of the members is too large to store  in  the  stat
                       structure pointed to by buf.



       The stat() and lstat() functions may fail if:

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



       ENAMETOOLONG    As a result of encountering a symbolic link in  resolu-
                       tion of thepath argument, the length of the substituted
                       pathname strings exceeds {PATH_MAX}.



EXAMPLES
       Example 1: Use stat() to obtain 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);


       Example 2: Use stat() to get 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 owners 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's 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);
        }


       Example 3: Use fstat() to obtain 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. The /home/cnd/mod1 file is opened  with  read/write
       privileges and is passed to the open file descriptor fildes.

       #include <sys/types.h>
       #include <sys/stat.h>
       #include <fcntl.h>
       struct stat buffer;
       int         status;
       ...
       fildes = open("/home/cnd/mod1", O_RDWR);
       status = fstat(fildes, &buffer);


       Example 4: Use lstat() to obtain symbolic link status information.

       The following example shows how to obtain status information for a sym-
       bolic link named  /modules/pass1.  The  structure  variable  buffer  is
       defined  for  the  stat  structure.  If the path argument specified the
       filename for the file pointed to by the symbolic link (/home/cnd/mod1),
       the results of calling the function would be the same as those returned
       by a call to the stat() function.

       #include <sys/stat.h>
       struct stat buffer;
       int         status;
       ...
       status = lstat("/modules/pass1", &buffer);


USAGE
       If chmod(2) or fchmod(2) is used to change the file group owner permis-
       sions on a file with ACL entries, both the file group owner permissions
       and the ACL mask are changed to the new permissions. The new  ACL  mask
       permissions might change the effective permissions for additional users
       and groups who have ACL entries on the file.

       The stat(), fstat(), and lstat() functions have transitional interfaces
       for 64-bit file offsets.  See lf64(5).

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE  TYPEATTRIBUTE  VALUE  Interface  StabilityT{
       fstatat()  is  Evolving; others are Standard.  T} MT-LevelAsync-Signal-
       Safe


SEE ALSO
       access(2), chmod(2), chown(2), creat(2),  link(2),  mknod(2),  pipe(2),
       read(2),   time(2),   unlink(2),   utime(2),   write(2),   fattach(3C),
       stat.h(3HEAD), attributes(5), fsattr(5), lf64(5), standards(5)



SunOS 5.10                        29 Jan 2004                          stat(2)