unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 stat(2)							     stat(2)




 NAME
      stat - get file status

 SYNOPSIS
      #include <&lt&lt&lt;sys/types.h>&gt&gt&gt;
      #include <&lt&lt&lt;sys/stat.h>&gt&gt&gt;

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

 DESCRIPTION
      The stat() function obtains information about the named file and
      writes 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, but all directories
      listed in the pathname leading to the file must be searchable. An
      implementation that provides additional or alternate file access
      control mechanisms may, under implementation-dependent conditions,
      cause stat() to fail. In particular, the system may deny the existence
      of the file specified by path.

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

      The stat() function updates any time-related  fields (as described in
      the definition of File Times Update in the XBD specification), before
      writing into the stat structure.

      The structure members st_mode, st_ino, st_dev, st_uid, st_gid,
      st_atime, st_ctime, and st_mtime will have meaningful values for all
      file types defined in this document. The value of the member st_nlink
      will be set to the number of links to the file.

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

 ERRORS
      The stat() function will 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]		    Too many symbolic links were encountered
				    in resolving path.

	   [ENAMETOOLONG]	    The length of the path argument exceeds
				    {PATH_MAX} or a pathname component is



 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 stat(2)							     stat(2)




				    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.

      The stat() function may fail if:

	   [ENAMETOOLONG]	    Pathname resolution of a symbolic link
				    produced an intermediate result whose
				    length exceeds {PATH_MAX}.

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

 SEE ALSO
      fstat(2), lstat(2), <sys/stat.h>, <sys/types.h>.

 CHANGE HISTORY
      First released in Issue 1.

      Derived from Issue 1 of the SVID.

 Issue 4
      The following changes are incorporated for alignment with the ISO
      POSIX-1 standard:

	   +  The type of argument path is changed from char * to const char
	      *.

	   +  In the DESCRIPTION section, (a) statements indicating the
	      purpose of this interface and a paragraph defining the
	      contents of stat structure members are added, and (b) the
	      words "extended security controls" are replaced by "additional
	      or alternate file access control mechanisms."

      The following change is incorporated for alignment with the FIPS
      requirements:

	   +  In the ERRORS section, the condition whereby [ENAMETOOLONG]
	      will be returned if a pathname component is larger that
	      {NAME_MAX} is now defined as mandatory and marked as an
	      extension.

      Another change is incorporated as follows:

	   +  The header <&lt&lt&lt;sys/types.h>&gt&gt&gt; is now marked as optional (OH); this
	      header need not be included on XSI-conformant systems.



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 stat(2)							     stat(2)




 Issue 4, Version 2
      The ERRORS section is updated for X/OPEN	UNIX conformance as follows:

	   +  In the mandatory section, EIO is added to indicate that a
	      physical I/O error has occurred, and ELOOP to indicate that
	      too many symbolic links were encountered during pathname
	      resolution.

	   +  In the optional section, a second ENAMETOOLONG condition is
	      defined that may report excessive length of an intermediate
	      result of pathname resolution of a symbolic link.

	   +  In the optional section, EOVERFLOW is added to indicate that a
	      value to be stored in a member of the stat structure would
	      cause overflow.







































				    - 3 -	  Formatted:  August 2, 2006






 stat(2)							     stat(2)




				 HP-UX EXTENSIONS



 DESCRIPTION
      If the chosen path name or file descriptor refers to a Multi-Level
      Directory (MLD), and the process does not have the multilevel
      effective privilege, the i-node number returned in st_ino is the
      i-node of the MLD itself.

      The parameters for the stat() function are as follows:

	   path		  is a pointer to a path name of any file within the
			  mounted file system.	 (All directories listed in
			  the path name must be searchable.)

	   buf		  is a pointer to a stat structure, which is where
			  the file status information is stored.

      The stat structure contains the following members:

	   dev_t    st_dev;	  /* ID of device containing a */
				  /* directory entry for this file */
	   ino_t    st_ino;	  /* Inode number */
	   ushort   st_fstype;	  /* Type of filesystem this file  */
				  /* is in; see sysfs(2) */
	   ushort   st_mode;	  /* File type, attributes, and */
				  /* access control summary */
	   ushort   st_basemode	  /* Permission bits (see chmod(1)) */
	   ushort   st_nlink;	  /* Number of links */
	   uid_t    st_uid;	  /* User ID of file owner */
	   gid_t    st_gid;	  /* Group ID of file group */
	   dev_t    st_rdev;	  /* Device ID; this entry defined */
				  /* only for char or blk spec files */
	   off_t    st_size;	  /* File size (bytes) */
	   time_t   st_atime;	  /* Time of last access */
	   time_t   st_mtime;	  /* Last modification time */
	   time_t   st_ctime;	  /* Last file status change time */
				  /* Measured in secs since */
				  /* 00:00:00 GMT, Jan 1, 1970 */
	   long	    st_blksize;	  /* File system block size */
	   uint	    st_acl:1;	  /* Set if the file has optional */
				  /* access control list entries */
				  /* HFS File Systems only */
	   uint	    st_aclv:1;	  /* Set if the file has optional */
				  /* access control list entries */
				  /* JFS File Systems only */

      (Note that the position of items in this list does not necessarily
      reflect the order of the members in the structure.)




 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 stat(2)							     stat(2)




 ERRORS
	   [EFAULT]	  buf or path points to an invalid address.  The
			  reliable detection of this error is implementation
			  dependent.

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

 NFS
      The st_basemode, st_acl and st_aclv fields are zero on files accessed
      remotely.	 The st_acl field is applicable to HFS File Systems only.
      The st_aclv field is applicable to JFS File Systems only.

 WARNINGS
    Access Control Lists - HFS and JFS File Systems only
      Access control list descriptions in this entry apply only to HFS and
      JFS file systems on standard HP-UX operating systems.

 DEPENDENCIES
    CD-ROM
      The st_uid and st_gid fields are set to -1 if they are not specified
      on the disk for a given file.

 AUTHOR
      stat() and fstat() were developed by AT&T.  lstat() was developed by
      the University of California, Berkeley.

 SEE ALSO
      touch(1), acl(2), chmod(2), chown(2), creat(2), link(2), mknod(2),
      pipe(2), read(2), rename(2), setacl(2), stat64(2), sysfs(2), time(2),
      truncate(2), unlink(2), utime(2), write(2), acl(5), aclv(5), stat(5).

 STANDARDS CONFORMANCE
      stat(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1



















 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000