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

sys_stat.h.0p (12467B)


  1. '\" et
  2. .TH sys_stat.h "0P" 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. sys/stat.h
  12. \(em data returned by the stat(\|) function
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/stat.h>
  17. .fi
  18. .SH DESCRIPTION
  19. The
  20. .IR <sys/stat.h>
  21. header shall define the structure of the data returned by the
  22. \fIfstat\fR(),
  23. \fIlstat\fR(),
  24. and
  25. \fIstat\fR()
  26. functions.
  27. .P
  28. The
  29. .IR <sys/stat.h>
  30. header shall define the
  31. .BR stat
  32. structure, which shall include at least the following members:
  33. .sp
  34. .RS 4
  35. .nf
  36. dev_t st_dev \fRDevice ID of device containing file.\fR
  37. ino_t st_ino \fRFile serial number.\fR
  38. mode_t st_mode \fRMode of file (see below).\fR
  39. nlink_t st_nlink \fRNumber of hard links to the file.\fR
  40. uid_t st_uid \fRUser ID of file.\fR
  41. gid_t st_gid \fRGroup ID of file.\fR
  42. dev_t st_rdev \fRDevice ID (if file is character or block special).\fR
  43. off_t st_size \fRFor regular files, the file size in bytes.\fR
  44. \fRFor symbolic links, the length in bytes of the\fR
  45. \fRpathname contained in the symbolic link.\fR
  46. \fRFor a shared memory object, the length in bytes.\fR
  47. \fRFor a typed memory object, the length in bytes.\fR
  48. \fRFor other file types, the use of this field is\fR
  49. \fRunspecified.\fR
  50. struct timespec st_atim \fRLast data access timestamp.\fR
  51. struct timespec st_mtim \fRLast data modification timestamp.\fR
  52. struct timespec st_ctim \fRLast file status change timestamp.\fR
  53. blksize_t st_blksize \fRA file system-specific preferred I/O block size\fR
  54. \fRfor this object. In some file system types, this\fR
  55. \fRmay vary from file to file.\fR
  56. blkcnt_t st_blocks \fRNumber of blocks allocated for this object.\fR
  57. .fi
  58. .P
  59. .RE
  60. .P
  61. The
  62. .IR st_ino
  63. and
  64. .IR st_dev
  65. fields taken together uniquely identify the file within the system.
  66. .P
  67. The
  68. .IR <sys/stat.h>
  69. header shall define the
  70. .BR blkcnt_t ,
  71. .BR blksize_t ,
  72. .BR dev_t ,
  73. .BR ino_t ,
  74. .BR mode_t ,
  75. .BR nlink_t ,
  76. .BR uid_t ,
  77. .BR gid_t ,
  78. .BR off_t ,
  79. and
  80. .BR time_t
  81. types as described in
  82. .IR <sys/types.h> .
  83. .P
  84. The
  85. .IR <sys/stat.h>
  86. header shall define the
  87. .BR timespec
  88. structure as described in
  89. .IR <time.h> .
  90. Times shall be given in seconds since the Epoch.
  91. .P
  92. Which structure members have meaningful values depends on the
  93. type of file. For further information, see the descriptions of
  94. \fIfstat\fR(),
  95. \fIlstat\fR(),
  96. and
  97. \fIstat\fR()
  98. in the System Interfaces volume of POSIX.1\(hy2017.
  99. .P
  100. For compatibility with earlier versions of this standard, the
  101. .IR st_atime
  102. macro shall be defined with the value
  103. .IR st_atim.tv_sec .
  104. Similarly,
  105. .IR st_ctime
  106. and
  107. .IR st_mtime
  108. shall be defined as macros with the values
  109. .IR st_ctim.tv_sec
  110. and
  111. .IR st_mtim.tv_sec ,
  112. respectively.
  113. .br
  114. .P
  115. The
  116. .IR <sys/stat.h>
  117. header shall define the following symbolic constants for the
  118. file types encoded in type
  119. .BR mode_t .
  120. The values shall be suitable for use in
  121. .BR #if
  122. preprocessing directives:
  123. .IP S_IFMT 12
  124. Type of file.
  125. .RS 12
  126. .IP S_IFBLK 12
  127. Block special.
  128. .IP S_IFCHR 12
  129. Character special.
  130. .IP S_IFIFO 12
  131. FIFO special.
  132. .IP S_IFREG 12
  133. Regular.
  134. .IP S_IFDIR 12
  135. Directory.
  136. .IP S_IFLNK 12
  137. Symbolic link.
  138. .IP S_IFSOCK 12
  139. Socket.
  140. .RE
  141. .P
  142. The
  143. .IR <sys/stat.h>
  144. header shall define the following symbolic constants for the file mode
  145. bits encoded in type
  146. .BR mode_t ,
  147. with the indicated numeric values. These macros shall expand to an
  148. expression which has a type that allows them to be used, either singly
  149. or OR'ed together, as the third argument to
  150. \fIopen\fR()
  151. without the need for a
  152. .BR mode_t
  153. cast. The values shall be suitable for use in
  154. .BR #if
  155. preprocessing directives.
  156. .TS
  157. center box tab(@);
  158. cB | cB | cB
  159. l | n | l.
  160. Name@Numeric Value@Description
  161. _
  162. S_IRWXU@0700@Read, write, execute/search by owner.
  163. S_IRUSR@0400@Read permission, owner.
  164. S_IWUSR@0200@Write permission, owner.
  165. S_IXUSR@0100@Execute/search permission, owner.
  166. _
  167. S_IRWXG@070@Read, write, execute/search by group.
  168. S_IRGRP@040@Read permission, group.
  169. S_IWGRP@020@Write permission, group.
  170. S_IXGRP@010@Execute/search permission, group.
  171. _
  172. S_IRWXO@07@Read, write, execute/search by others.
  173. S_IROTH@04@Read permission, others.
  174. S_IWOTH@02@Write permission, others.
  175. S_IXOTH@01@Execute/search permission, others.
  176. _
  177. S_ISUID@04000@Set-user-ID on execution.
  178. S_ISGID@02000@Set-group-ID on execution.
  179. \*!S_ISVTX@01000@On directories, restricted deletion flag.\0\0\0\*?
  180. .TE
  181. .P
  182. The following macros shall be provided to test whether a file is of the
  183. specified type. The value
  184. .IR m
  185. supplied to the macros is the value of
  186. .IR st_mode
  187. from a
  188. .BR stat
  189. structure. The macro shall evaluate to a non-zero value if the test is
  190. true; 0 if the test is false.
  191. .IP "S_ISBLK(\fIm\fP)" 14
  192. Test for a block special file.
  193. .IP "S_ISCHR(\fIm\fP)" 14
  194. Test for a character special file.
  195. .IP "S_ISDIR(\fIm\fP)" 14
  196. Test for a directory.
  197. .IP "S_ISFIFO(\fIm\fP)" 14
  198. Test for a pipe or FIFO special file.
  199. .IP "S_ISREG(\fIm\fP)" 14
  200. Test for a regular file.
  201. .IP "S_ISLNK(\fIm\fP)" 14
  202. Test for a symbolic link.
  203. .IP "S_ISSOCK(\fIm\fP)" 14
  204. Test for a socket.
  205. .P
  206. The implementation may implement message queues, semaphores, or shared
  207. memory objects as distinct file types. The following macros shall be
  208. provided to test whether a file is of the specified type. The value of
  209. the
  210. .IR buf
  211. argument supplied to the macros is a pointer to a
  212. .BR stat
  213. structure. The macro shall evaluate to a non-zero value if the
  214. specified object is implemented as a distinct file type and the
  215. specified file type is contained in the
  216. .BR stat
  217. structure referenced by
  218. .IR buf .
  219. Otherwise, the macro shall evaluate to zero.
  220. .IP "S_TYPEISMQ(\fIbuf\fP)" 14
  221. Test for a message queue.
  222. .IP "S_TYPEISSEM(\fIbuf\fP)" 14
  223. Test for a semaphore.
  224. .IP "S_TYPEISSHM(\fIbuf\fP)" 14
  225. Test for a shared memory object.
  226. .P
  227. The implementation may implement typed memory objects as distinct
  228. file types, and the following macro shall test whether a file is of the
  229. specified type. The value of the
  230. .IR buf
  231. argument supplied to the macros is a pointer to a
  232. .BR stat
  233. structure. The macro shall evaluate to a non-zero value if the
  234. specified object is implemented as a distinct file type and the
  235. specified file type is contained in the
  236. .BR stat
  237. structure referenced by
  238. .IR buf .
  239. Otherwise, the macro shall evaluate to zero.
  240. .IP "S_TYPEISTMO(\fIbuf\fP)" 14
  241. Test macro for a typed memory object.
  242. .P
  243. The
  244. .IR <sys/stat.h>
  245. header shall define the following symbolic constants as distinct
  246. integer values outside of the range [0,999\|999\|999],
  247. for use with the
  248. \fIfutimens\fR()
  249. and
  250. \fIutimensat\fR()
  251. functions:
  252. UTIME_NOW
  253. UTIME_OMIT
  254. .P
  255. The following shall be declared as functions and may also be defined
  256. as macros. Function prototypes shall be provided.
  257. .sp
  258. .RS 4
  259. .nf
  260. int chmod(const char *, mode_t);
  261. int fchmod(int, mode_t);
  262. int fchmodat(int, const char *, mode_t, int);
  263. int fstat(int, struct stat *);
  264. int fstatat(int, const char *restrict, struct stat *restrict, int);
  265. int futimens(int, const struct timespec [2]);
  266. int lstat(const char *restrict, struct stat *restrict);
  267. int mkdir(const char *, mode_t);
  268. int mkdirat(int, const char *, mode_t);
  269. int mkfifo(const char *, mode_t);
  270. int mkfifoat(int, const char *, mode_t);
  271. int mknod(const char *, mode_t, dev_t);
  272. int mknodat(int, const char *, mode_t, dev_t);
  273. int stat(const char *restrict, struct stat *restrict);
  274. mode_t umask(mode_t);
  275. int utimensat(int, const char *, const struct timespec [2], int);
  276. .fi
  277. .P
  278. .RE
  279. .P
  280. Inclusion of the
  281. .IR <sys/stat.h>
  282. header may make visible all symbols from the
  283. .IR <time.h>
  284. header.
  285. .LP
  286. .IR "The following sections are informative."
  287. .SH "APPLICATION USAGE"
  288. Use of the macros is recommended for determining the type of a file.
  289. .SH RATIONALE
  290. A conforming C-language application must include
  291. .IR <sys/stat.h>
  292. for functions that have arguments or return values of type
  293. .BR mode_t ,
  294. so that symbolic values for that type can be used. An alternative
  295. would be to require that these constants are also defined by including
  296. .IR <sys/types.h> .
  297. .P
  298. The S_ISUID and S_ISGID
  299. bits may be cleared on any write, not just on
  300. \fIopen\fR(),
  301. as some historical implementations do.
  302. .P
  303. System calls that update the time entry fields in the
  304. .BR stat
  305. structure must be documented by the implementors. POSIX-conforming
  306. systems should not update the time entry fields for functions listed in
  307. the System Interfaces volume of POSIX.1\(hy2017 unless the standard requires that they do, except in the case
  308. of documented extensions to the standard.
  309. .P
  310. Upon assignment, file timestamps are immediately converted to the
  311. resolution of the file system by truncation (i.e., the recorded time
  312. can be older than the actual time). For example, if the file system
  313. resolution is 1 microsecond, then a conforming
  314. \fIstat\fR()
  315. must always return an
  316. .IR st_mtim.tv_nsec
  317. that is a multiple of 1000. Some older implementations returned
  318. higher-resolution timestamps while the
  319. .IR inode
  320. information was cached, and then spontaneously truncated the
  321. .IR tv_nsec
  322. fields when they were stored to and retrieved from disk, but this behavior
  323. does not conform.
  324. .P
  325. Note that
  326. .IR st_dev
  327. must be unique within a Local Area Network (LAN) in a ``system'' made
  328. up of multiple computers' file systems connected by a LAN.
  329. .P
  330. Networked implementations of a POSIX-conforming system must guarantee
  331. that all files visible within the file tree (including parts of the
  332. tree that may be remotely mounted from other machines on the network)
  333. on each individual processor are uniquely identified by the combination
  334. of the
  335. .IR st_ino
  336. and
  337. .IR st_dev
  338. fields.
  339. .P
  340. The unit for the
  341. .IR st_blocks
  342. member of the
  343. .BR stat
  344. structure is not defined within POSIX.1\(hy2008. In some implementations
  345. it is 512 bytes. It may differ on a file system basis. There is no
  346. correlation between values of the
  347. .IR st_blocks
  348. and
  349. .IR st_blksize ,
  350. and the
  351. .IR f_bsize
  352. (from
  353. .IR <sys/statvfs.h> )
  354. structure members.
  355. .P
  356. Traditionally, some implementations defined the multiplier for
  357. .IR st_blocks
  358. in
  359. .IR <sys/param.h>
  360. as the symbol DEV_BSIZE.
  361. .P
  362. Some earlier versions of this standard did not specify values for the
  363. file mode bit macros. The expectation was that some implementors might
  364. choose to use a different encoding for these bits than the traditional
  365. one, and that new applications would use symbolic file modes instead of
  366. numeric. This version of the standard specifies the traditional encoding,
  367. in recognition that nearly 20 years after the first publication of this
  368. standard numeric file modes are still in widespread use by application
  369. developers, and that all conforming implementations still use the
  370. traditional encoding.
  371. .SH "FUTURE DIRECTIONS"
  372. No new S_IFMT symbolic names for the file type values of
  373. .BR mode_t
  374. will be defined by POSIX.1\(hy2008; if new file types are required, they will
  375. only be testable through
  376. .IR S_ISxx (\|)
  377. or
  378. .IR S_TYPEISxxx (\|)
  379. macros instead.
  380. .SH "SEE ALSO"
  381. .IR "\fB<sys_statvfs.h>\fP",
  382. .IR "\fB<sys_types.h>\fP",
  383. .IR "\fB<time.h>\fP"
  384. .P
  385. The System Interfaces volume of POSIX.1\(hy2017,
  386. .IR "\fIchmod\fR\^(\|)",
  387. .IR "\fIfchmod\fR\^(\|)",
  388. .IR "\fIfstat\fR\^(\|)",
  389. .IR "\fIfstatat\fR\^(\|)",
  390. .IR "\fIfutimens\fR\^(\|)",
  391. .IR "\fImkdir\fR\^(\|)",
  392. .IR "\fImkfifo\fR\^(\|)",
  393. .IR "\fImknod\fR\^(\|)",
  394. .IR "\fIumask\fR\^(\|)"
  395. .\"
  396. .SH COPYRIGHT
  397. Portions of this text are reprinted and reproduced in electronic form
  398. from IEEE Std 1003.1-2017, Standard for Information Technology
  399. -- Portable Operating System Interface (POSIX), The Open Group Base
  400. Specifications Issue 7, 2018 Edition,
  401. Copyright (C) 2018 by the Institute of
  402. Electrical and Electronics Engineers, Inc and The Open Group.
  403. In the event of any discrepancy between this version and the original IEEE and
  404. The Open Group Standard, the original IEEE and The Open Group Standard
  405. is the referee document. The original Standard can be obtained online at
  406. http://www.opengroup.org/unix/online.html .
  407. .PP
  408. Any typographical or formatting errors that appear
  409. in this page are most likely
  410. to have been introduced during the conversion of the source files to
  411. man page format. To report such errors, see
  412. https://www.kernel.org/doc/man-pages/reporting_bugs.html .