man3p/fstat.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "FSTAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" fstat
   4 .SH NAME
   5 fstat \- get file status
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <sys/stat.h>
   9 .br
  10 .sp
  11 int fstat(int\fP \fIfildes\fP\fB, struct stat *\fP\fIbuf\fP\fB);
  12 .br
  13 \fP
  14 .SH DESCRIPTION
  15 .LP
  16 The \fIfstat\fP() function shall obtain information about an open
  17 file associated with the file descriptor \fIfildes\fP, and
  18 shall write it to the area pointed to by \fIbuf\fP.
  19 .LP
  20 If \fIfildes\fP references a shared memory object, the implementation
  21 shall update in the \fBstat\fP structure pointed to by the
  22 \fIbuf\fP argument only the \fIst_uid\fP, \fIst_gid\fP, \fIst_size\fP,
  23 and \fIst_mode\fP fields, and only the S_IRUSR,
  24 S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits
  25 need be valid. The implementation may update other fields and
  26 flags.
  27 .LP
  28 If \fIfildes\fP references a typed memory object, the implementation
  29 shall update in the \fBstat\fP structure pointed to by the
  30 \fIbuf\fP argument only the \fIst_uid\fP, \fIst_gid\fP, \fIst_size\fP,
  31 and \fIst_mode\fP fields, and only the S_IRUSR,
  32 S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits
  33 need be valid. The implementation may update other fields and
  34 flags.
  35 .LP
  36 The \fIbuf\fP argument is a pointer to a \fBstat\fP structure, as
  37 defined in \fI<sys/stat.h>\fP, into which information is placed concerning
  38 the file.
  39 .LP
  40 The structure members \fIst_mode\fP, \fIst_ino\fP, \fIst_dev\fP, \fIst_uid\fP,
  41 \fIst_gid\fP, \fIst_atime\fP,
  42 \fIst_ctime\fP, and \fIst_mtime\fP shall have meaningful values for
  43 all other file types defined in this volume of
  44 IEEE\ Std\ 1003.1-2001. The value of the member \fIst_nlink\fP shall
  45 be set to the number of links to the file.
  46 .LP
  47 An implementation that provides additional or alternative file access
  48 control mechanisms may, under implementation-defined
  49 conditions, cause \fIfstat\fP() to fail.
  50 .LP
  51 The \fIfstat\fP() function shall update any time-related fields as
  52 described in the Base Definitions volume of
  53 IEEE\ Std\ 1003.1-2001, Section 4.7, File Times Update, before writing
  54 into the \fBstat\fP structure.
  55 .SH RETURN VALUE
  56 .LP
  57 Upon successful completion, 0 shall be returned. Otherwise, -1 shall
  58 be returned and \fIerrno\fP set to indicate the error.
  59 .SH ERRORS
  60 .LP
  61 The \fIfstat\fP() function shall fail if:
  62 .TP 7
  63 .B EBADF
  64 The \fIfildes\fP argument is not a valid file descriptor.
  65 .TP 7
  66 .B EIO
  67 An I/O error occurred while reading from the file system.
  68 .TP 7
  69 .B EOVERFLOW
  70 The file size in bytes or the number of blocks allocated to the file
  71 or the file serial number cannot be represented correctly
  72 in the structure pointed to by \fIbuf\fP.
  73 .sp
  74 .LP
  75 The \fIfstat\fP() function may fail if:
  76 .TP 7
  77 .B EOVERFLOW
  78 One of the values is too large to store into the structure pointed
  79 to by the \fIbuf\fP argument.
  80 .sp
  81 .LP
  82 \fIThe following sections are informative.\fP
  83 .SH EXAMPLES
  84 .SS Obtaining File Status Information
  85 .LP
  86 The following example shows how to obtain file status information
  87 for a file named \fB/home/cnd/mod1\fP. The structure variable
  88 \fIbuffer\fP is defined for the \fBstat\fP structure. The \fB/home/cnd/mod1\fP
  89 file is opened with read/write privileges and is
  90 passed to the open file descriptor \fIfildes\fP.
  91 .sp
  92 .RS
  93 .nf
  94
  95 \fB#include <sys/types.h>
  96 #include <sys/stat.h>
  97 #include <fcntl.h>
  98 .sp
  99
 100 struct stat buffer;
 101 int         status;
 102 \&...
 103 fildes = open("/home/cnd/mod1", O_RDWR);
 104 status = fstat(fildes, &buffer);
 105 \fP
 106 .fi
 107 .RE
 108 .SH APPLICATION USAGE
 109 .LP
 110 None.
 111 .SH RATIONALE
 112 .LP
 113 None.
 114 .SH FUTURE DIRECTIONS
 115 .LP
 116 None.
 117 .SH SEE ALSO
 118 .LP
 119 \fIlstat\fP() , \fIstat\fP() , the Base Definitions volume of
 120 IEEE\ Std\ 1003.1-2001, \fI<sys/stat.h>\fP, \fI<sys/types.h>\fP
 121 .SH COPYRIGHT
 122 Portions of this text are reprinted and reproduced in electronic form
 123 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 124 -- Portable Operating System Interface (POSIX), The Open Group Base
 125 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 126 Electrical and Electronics Engineers, Inc and The Open Group. In the
 127 event of any discrepancy between this version and the original IEEE and
 128 The Open Group Standard, the original IEEE and The Open Group Standard
 129 is the referee document. The original Standard can be obtained online at
 130 http://www.opengroup.org/unix/online.html .