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

fseek.3p (7011B)


  1. '\" et
  2. .TH FSEEK "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. fseek,
  12. fseeko
  13. \(em reposition a file-position indicator in a stream
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <stdio.h>
  18. .P
  19. int fseek(FILE *\fIstream\fP, long \fIoffset\fP, int \fIwhence\fP);
  20. int fseeko(FILE *\fIstream\fP, off_t \fIoffset\fP, int \fIwhence\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The functionality described on this reference page is aligned with the
  24. ISO\ C standard. Any conflict between the requirements described here and the
  25. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  26. .P
  27. The
  28. \fIfseek\fR()
  29. function shall set the file-position indicator for the stream pointed
  30. to by
  31. .IR stream .
  32. If a read or write error occurs, the error indicator for the stream
  33. shall be set and
  34. \fIfseek\fR()
  35. fails.
  36. .P
  37. The new position, measured in bytes from the beginning of the file,
  38. shall be obtained by adding
  39. .IR offset
  40. to the position specified by
  41. .IR whence .
  42. The specified point is the beginning of the file for SEEK_SET, the
  43. current value of the file-position indicator for SEEK_CUR, or
  44. end-of-file for SEEK_END.
  45. .P
  46. If the stream is to be used with wide-character input/output functions,
  47. the application shall ensure that
  48. .IR offset
  49. is either 0 or a value returned by an earlier call to
  50. \fIftell\fR()
  51. on the same stream and
  52. .IR whence
  53. is SEEK_SET.
  54. .P
  55. A successful call to
  56. \fIfseek\fR()
  57. shall clear the end-of-file indicator for the stream and undo any
  58. effects of
  59. \fIungetc\fR()
  60. and
  61. \fIungetwc\fR()
  62. on the same stream. After an
  63. \fIfseek\fR()
  64. call, the next operation on an update stream may be either input or
  65. output.
  66. .P
  67. If the most recent operation, other than
  68. \fIftell\fR(),
  69. on a given stream is
  70. \fIfflush\fR(),
  71. the file offset in the underlying open file description shall be
  72. adjusted to reflect the location specified by
  73. \fIfseek\fR().
  74. .P
  75. The
  76. \fIfseek\fR()
  77. function shall allow the file-position indicator to be set beyond the
  78. end of existing data in the file. If data is later written at this
  79. point, subsequent reads of data in the gap shall return bytes with the
  80. value 0 until data is actually written into the gap.
  81. .P
  82. The behavior of
  83. \fIfseek\fR()
  84. on devices which are incapable of seeking is implementation-defined.
  85. The value of the file offset associated with such a device is
  86. undefined.
  87. .P
  88. If the stream is writable and buffered data had not been written to the
  89. underlying file,
  90. \fIfseek\fR()
  91. shall cause the unwritten data to be written to the file and shall mark
  92. the last data modification and last file status change timestamps
  93. of the file for update.
  94. .P
  95. In a locale with state-dependent encoding, whether
  96. \fIfseek\fR()
  97. restores the stream's shift state is implementation-defined.
  98. .P
  99. The
  100. \fIfseeko\fR()
  101. function shall be equivalent to the
  102. \fIfseek\fR()
  103. function except that the
  104. .IR offset
  105. argument is of type
  106. .BR off_t .
  107. .SH "RETURN VALUE"
  108. The
  109. \fIfseek\fR()
  110. and
  111. \fIfseeko\fR()
  112. functions shall return 0 if they succeed.
  113. .P
  114. Otherwise, they shall return \-1 and set
  115. .IR errno
  116. to indicate the error.
  117. .SH ERRORS
  118. The
  119. \fIfseek\fR()
  120. and
  121. \fIfseeko\fR()
  122. functions shall fail if,
  123. either the
  124. .IR stream
  125. is unbuffered or the
  126. .IR stream 's
  127. buffer needed to be flushed, and the call to
  128. \fIfseek\fR()
  129. or
  130. \fIfseeko\fR()
  131. causes an underlying
  132. \fIlseek\fR()
  133. or
  134. \fIwrite\fR()
  135. to be invoked, and:
  136. .TP
  137. .BR EAGAIN
  138. The O_NONBLOCK flag is set for the file descriptor and the thread
  139. would be delayed in the write operation.
  140. .TP
  141. .BR EBADF
  142. The file descriptor underlying the stream file is not open for writing
  143. or the stream's buffer needed to be flushed and the file is not open.
  144. .TP
  145. .BR EFBIG
  146. An attempt was made to write a file that exceeds the maximum file size.
  147. .TP
  148. .BR EFBIG
  149. An attempt was made to write a file that exceeds the file size
  150. limit of the process.
  151. .TP
  152. .BR EFBIG
  153. The file is a regular file and an attempt was made to write at or
  154. beyond the offset maximum associated with the corresponding stream.
  155. .TP
  156. .BR EINTR
  157. The write operation was terminated due to the receipt of a signal,
  158. and no data was transferred.
  159. .TP
  160. .BR EINVAL
  161. The
  162. .IR whence
  163. argument is invalid. The resulting file-position indicator would be
  164. set to a negative value.
  165. .TP
  166. .BR EIO
  167. A physical I/O error has occurred, or the process is a member of a
  168. background process group attempting to perform a
  169. \fIwrite\fR()
  170. to its controlling terminal, TOSTOP is set, the calling thread is not
  171. blocking SIGTTOU, the process is not ignoring SIGTTOU, and the process
  172. group of the process is orphaned.
  173. This error may also be returned under implementation-defined conditions.
  174. .TP
  175. .BR ENOSPC
  176. There was no free space remaining on the device containing the file.
  177. .TP
  178. .BR EOVERFLOW
  179. For
  180. \fIfseek\fR(),
  181. the resulting file offset would be a value which cannot be represented
  182. correctly in an object of type
  183. .BR long .
  184. .TP
  185. .BR EOVERFLOW
  186. For
  187. \fIfseeko\fR(),
  188. the resulting file offset would be a value which cannot be represented
  189. correctly in an object of type
  190. .BR off_t .
  191. .TP
  192. .BR EPIPE
  193. An attempt was made to write to a pipe or FIFO that is not open for
  194. reading by any process; a SIGPIPE
  195. signal shall also be sent to the thread.
  196. .TP
  197. .BR ESPIPE
  198. The file descriptor underlying
  199. .IR stream
  200. is associated with a pipe, FIFO, or socket.
  201. .P
  202. The
  203. \fIfseek\fR()
  204. and
  205. \fIfseeko\fR()
  206. functions may fail if:
  207. .TP
  208. .BR ENXIO
  209. A request was made of a nonexistent device, or the request was outside
  210. the capabilities of the device.
  211. .LP
  212. .IR "The following sections are informative."
  213. .SH EXAMPLES
  214. None.
  215. .SH "APPLICATION USAGE"
  216. None.
  217. .SH RATIONALE
  218. None.
  219. .SH "FUTURE DIRECTIONS"
  220. None.
  221. .SH "SEE ALSO"
  222. .IR "Section 2.5" ", " "Standard I/O Streams",
  223. .IR "\fIfopen\fR\^(\|)",
  224. .IR "\fIfsetpos\fR\^(\|)",
  225. .IR "\fIftell\fR\^(\|)",
  226. .IR "\fIgetrlimit\fR\^(\|)",
  227. .IR "\fIlseek\fR\^(\|)",
  228. .IR "\fIrewind\fR\^(\|)",
  229. .IR "\fIulimit\fR\^(\|)",
  230. .IR "\fIungetc\fR\^(\|)",
  231. .IR "\fIwrite\fR\^(\|)"
  232. .P
  233. The Base Definitions volume of POSIX.1\(hy2017,
  234. .IR "\fB<stdio.h>\fP"
  235. .\"
  236. .SH COPYRIGHT
  237. Portions of this text are reprinted and reproduced in electronic form
  238. from IEEE Std 1003.1-2017, Standard for Information Technology
  239. -- Portable Operating System Interface (POSIX), The Open Group Base
  240. Specifications Issue 7, 2018 Edition,
  241. Copyright (C) 2018 by the Institute of
  242. Electrical and Electronics Engineers, Inc and The Open Group.
  243. In the event of any discrepancy between this version and the original IEEE and
  244. The Open Group Standard, the original IEEE and The Open Group Standard
  245. is the referee document. The original Standard can be obtained online at
  246. http://www.opengroup.org/unix/online.html .
  247. .PP
  248. Any typographical or formatting errors that appear
  249. in this page are most likely
  250. to have been introduced during the conversion of the source files to
  251. man page format. To report such errors, see
  252. https://www.kernel.org/doc/man-pages/reporting_bugs.html .