logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

fstat.3p (4713B)

    

  1. '\" et
  2. .TH FSTAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. fstat
  12. \(em get file status
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/stat.h>
  17. .P
  18. int fstat(int \fIfildes\fP, struct stat *\fIbuf\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIfstat\fR()
  23. function shall obtain information about an open file associated with
  24. the file descriptor
  25. .IR fildes ,
  26. and shall write it to the area pointed to by
  27. .IR buf .
  28. .P
  29. If
  30. .IR fildes
  31. references a shared memory object, the implementation shall update in
  32. the
  33. .BR stat
  34. structure pointed to by the
  35. .IR buf
  36. argument the
  37. .IR st_uid ,
  38. .IR st_gid ,
  39. .IR st_size ,
  40. and
  41. .IR st_mode
  42. fields, and only the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and
  43. S_IWOTH file permission bits need be valid.
  44. The implementation may update other fields and flags.
  45. .P
  46. If
  47. .IR fildes
  48. references a typed memory object, the implementation shall update in
  49. the
  50. .BR stat
  51. structure pointed to by the
  52. .IR buf
  53. argument the
  54. .IR st_uid ,
  55. .IR st_gid ,
  56. .IR st_size ,
  57. and
  58. .IR st_mode
  59. fields, and only the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and
  60. S_IWOTH file permission bits need be valid. The implementation
  61. may update other fields and flags.
  62. .P
  63. The
  64. .IR buf
  65. argument is a pointer to a
  66. .BR stat
  67. structure, as defined in
  68. .IR <sys/stat.h> ,
  69. into which information is placed concerning the file.
  70. .P
  71. For all other file types defined in this volume of POSIX.1\(hy2017, the structure members
  72. .IR st_mode ,
  73. .IR st_ino ,
  74. .IR st_dev ,
  75. .IR st_uid ,
  76. .IR st_gid ,
  77. .IR st_atim ,
  78. .IR st_ctim ,
  79. and
  80. .IR st_mtim
  81. shall have meaningful values and the value of the
  82. .IR st_nlink
  83. member shall be set to the number of links to the file.
  84. .P
  85. An implementation that provides additional or alternative file access
  86. control mechanisms may, under implementation-defined conditions,
  87. cause
  88. \fIfstat\fR()
  89. to fail.
  90. .P
  91. The
  92. \fIfstat\fR()
  93. function shall update any time-related fields (as described in the Base Definitions volume of POSIX.1\(hy2017,
  94. .IR "Section 4.9" ", " "File Times Update"),
  95. before writing into the
  96. .BR stat
  97. structure.
  98. .SH "RETURN VALUE"
  99. Upon successful completion, 0 shall be returned. Otherwise, \-1 shall be
  100. returned and
  101. .IR errno
  102. set to indicate the error.
  103. .SH ERRORS
  104. The
  105. \fIfstat\fR()
  106. function shall fail if:
  107. .TP
  108. .BR EBADF
  109. The
  110. .IR fildes
  111. argument is not a valid file descriptor.
  112. .TP
  113. .BR EIO
  114. An I/O error occurred while reading from the file system.
  115. .TP
  116. .BR EOVERFLOW
  117. The file size in bytes or the number of blocks allocated to the file or
  118. the file serial number cannot be represented correctly in the structure
  119. pointed to by
  120. .IR buf .
  121. .P
  122. The
  123. \fIfstat\fR()
  124. function may fail if:
  125. .TP
  126. .BR EOVERFLOW
  127. One of the values is too large to store into the structure pointed to
  128. by the
  129. .IR buf
  130. argument.
  131. .LP
  132. .IR "The following sections are informative."
  133. .SH EXAMPLES
  134. .SS "Obtaining File Status Information "
  135. .P
  136. The following example shows how to obtain file status information for a
  137. file named
  138. .BR /home/cnd/mod1 .
  139. The structure variable
  140. .IR buffer
  141. is defined for the
  142. .BR stat
  143. structure. The
  144. .BR /home/cnd/mod1
  145. file is opened with read/write privileges and is passed to the open
  146. file descriptor
  147. .IR fildes .
  148. .sp
  149. .RS 4
  150. .nf
  152. #include <sys/types.h>
  153. #include <sys/stat.h>
  154. #include <fcntl.h>
  155. .P
  156. struct stat buffer;
  157. int         status;
  158. \&...
  159. fildes = open("/home/cnd/mod1", O_RDWR);
  160. status = fstat(fildes, &buffer);
  161. .fi
  162. .P
  163. .RE
  164. .SH "APPLICATION USAGE"
  165. None.
  166. .SH RATIONALE
  167. None.
  168. .SH "FUTURE DIRECTIONS"
  169. None.
  170. .SH "SEE ALSO"
  171. .IR "\fIfstatat\fR\^(\|)"
  172. .P
  173. The Base Definitions volume of POSIX.1\(hy2017,
  174. .IR "Section 4.9" ", " "File Times Update",
  175. .IR "\fB<sys_stat.h>\fP",
  176. .IR "\fB<sys_types.h>\fP"
  177. .\"
  178. .SH COPYRIGHT
  179. Portions of this text are reprinted and reproduced in electronic form
  180. from IEEE Std 1003.1-2017, Standard for Information Technology
  181. -- Portable Operating System Interface (POSIX), The Open Group Base
  182. Specifications Issue 7, 2018 Edition,
  183. Copyright (C) 2018 by the Institute of
  184. Electrical and Electronics Engineers, Inc and The Open Group.
  185. In the event of any discrepancy between this version and the original IEEE and
  186. The Open Group Standard, the original IEEE and The Open Group Standard
  187. is the referee document. The original Standard can be obtained online at
  188. http://www.opengroup.org/unix/online.html .
  189. .PP
  190. Any typographical or formatting errors that appear
  191. in this page are most likely
  192. to have been introduced during the conversion of the source files to
  193. man page format. To report such errors, see
  194. https://www.kernel.org/doc/man-pages/reporting_bugs.html .