| @@ -1,247 +1,247 @@ | | | @@ -1,247 +1,247 @@ |
1 | .\" $NetBSD: fseek.3,v 1.28 2017/01/01 12:39:33 abhinav Exp $ | | 1 | .\" $NetBSD: fseek.3,v 1.29 2021/09/11 18:46:22 rillig Exp $ |
2 | .\" | | 2 | .\" |
3 | .\" Copyright (c) 1990, 1991, 1993 | | 3 | .\" Copyright (c) 1990, 1991, 1993 |
4 | .\" The Regents of the University of California. All rights reserved. | | 4 | .\" The Regents of the University of California. All rights reserved. |
5 | .\" | | 5 | .\" |
6 | .\" This code is derived from software contributed to Berkeley by | | 6 | .\" This code is derived from software contributed to Berkeley by |
7 | .\" Chris Torek and the American National Standards Committee X3, | | 7 | .\" Chris Torek and the American National Standards Committee X3, |
8 | .\" on Information Processing Systems. | | 8 | .\" on Information Processing Systems. |
9 | .\" | | 9 | .\" |
10 | .\" Redistribution and use in source and binary forms, with or without | | 10 | .\" Redistribution and use in source and binary forms, with or without |
11 | .\" modification, are permitted provided that the following conditions | | 11 | .\" modification, are permitted provided that the following conditions |
12 | .\" are met: | | 12 | .\" are met: |
13 | .\" 1. Redistributions of source code must retain the above copyright | | 13 | .\" 1. Redistributions of source code must retain the above copyright |
14 | .\" notice, this list of conditions and the following disclaimer. | | 14 | .\" notice, this list of conditions and the following disclaimer. |
15 | .\" 2. Redistributions in binary form must reproduce the above copyright | | 15 | .\" 2. Redistributions in binary form must reproduce the above copyright |
16 | .\" notice, this list of conditions and the following disclaimer in the | | 16 | .\" notice, this list of conditions and the following disclaimer in the |
17 | .\" documentation and/or other materials provided with the distribution. | | 17 | .\" documentation and/or other materials provided with the distribution. |
18 | .\" 3. Neither the name of the University nor the names of its contributors | | 18 | .\" 3. Neither the name of the University nor the names of its contributors |
19 | .\" may be used to endorse or promote products derived from this software | | 19 | .\" may be used to endorse or promote products derived from this software |
20 | .\" without specific prior written permission. | | 20 | .\" without specific prior written permission. |
21 | .\" | | 21 | .\" |
22 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | | 22 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
23 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | | 23 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
24 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | | 24 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
25 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | | 25 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
26 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | | 26 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
27 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | | 27 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
28 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | | 28 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
29 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | | 29 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
30 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | | 30 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
31 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | | 31 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
32 | .\" SUCH DAMAGE. | | 32 | .\" SUCH DAMAGE. |
33 | .\" | | 33 | .\" |
34 | .\" @(#)fseek.3 8.1 (Berkeley) 6/4/93 | | 34 | .\" @(#)fseek.3 8.1 (Berkeley) 6/4/93 |
35 | .\" | | 35 | .\" |
36 | .Dd January 1, 2017 | | 36 | .Dd September 11, 2021 |
37 | .Dt FSEEK 3 | | 37 | .Dt FSEEK 3 |
38 | .Os | | 38 | .Os |
39 | .Sh NAME | | 39 | .Sh NAME |
40 | .Nm fgetpos , | | 40 | .Nm fgetpos , |
41 | .Nm fseek , | | 41 | .Nm fseek , |
42 | .Nm fseeko , | | 42 | .Nm fseeko , |
43 | .Nm fsetpos , | | 43 | .Nm fsetpos , |
44 | .Nm ftell , | | 44 | .Nm ftell , |
45 | .Nm ftello , | | 45 | .Nm ftello , |
46 | .Nm rewind | | 46 | .Nm rewind |
47 | .Nd reposition a stream | | 47 | .Nd reposition a stream |
48 | .Sh LIBRARY | | 48 | .Sh LIBRARY |
49 | .Lb libc | | 49 | .Lb libc |
50 | .Sh SYNOPSIS | | 50 | .Sh SYNOPSIS |
51 | .In stdio.h | | 51 | .In stdio.h |
52 | .Ft int | | 52 | .Ft int |
53 | .Fn fseek "FILE *stream" "long int offset" "int whence" | | 53 | .Fn fseek "FILE *stream" "long int offset" "int whence" |
54 | .Ft int | | 54 | .Ft int |
55 | .Fn fseeko "FILE *stream" "off_t offset" "int whence" | | 55 | .Fn fseeko "FILE *stream" "off_t offset" "int whence" |
56 | .Ft long int | | 56 | .Ft long int |
57 | .Fn ftell "FILE *stream" | | 57 | .Fn ftell "FILE *stream" |
58 | .Ft off_t | | 58 | .Ft off_t |
59 | .Fn ftello "FILE *stream" | | 59 | .Fn ftello "FILE *stream" |
60 | .Ft void | | 60 | .Ft void |
61 | .Fn rewind "FILE *stream" | | 61 | .Fn rewind "FILE *stream" |
62 | .Ft int | | 62 | .Ft int |
63 | .Fn fgetpos "FILE * restrict stream" "fpos_t * restrict pos" | | 63 | .Fn fgetpos "FILE * restrict stream" "fpos_t * restrict pos" |
64 | .Ft int | | 64 | .Ft int |
65 | .Fn fsetpos "FILE * restrict stream" "const fpos_t * restrict pos" | | 65 | .Fn fsetpos "FILE * restrict stream" "const fpos_t * restrict pos" |
66 | .Sh DESCRIPTION | | 66 | .Sh DESCRIPTION |
67 | The | | 67 | The |
68 | .Fn fseek | | 68 | .Fn fseek |
69 | function sets the file position indicator for the stream pointed | | 69 | function sets the file position indicator for the stream pointed |
70 | to by | | 70 | to by |
71 | .Fa stream . | | 71 | .Fa stream . |
72 | The new position, measured in bytes, is obtained by adding | | 72 | The new position, measured in bytes, is obtained by adding |
73 | .Fa offset | | 73 | .Fa offset |
74 | bytes to the position specified by | | 74 | bytes to the position specified by |
75 | .Fa whence . | | 75 | .Fa whence . |
76 | If | | 76 | If |
77 | .Fa whence | | 77 | .Fa whence |
78 | is set to | | 78 | is set to |
79 | .Dv SEEK_SET , | | 79 | .Dv SEEK_SET , |
80 | .Dv SEEK_CUR , | | 80 | .Dv SEEK_CUR , |
81 | or | | 81 | or |
82 | .Dv SEEK_END , | | 82 | .Dv SEEK_END , |
83 | the offset is relative to the | | 83 | the offset is relative to the |
84 | start of the file, the current position indicator, or end-of-file, | | 84 | start of the file, the current position indicator, or end-of-file, |
85 | respectively. | | 85 | respectively. |
86 | A successful call to the | | 86 | A successful call to the |
87 | .Fn fseek | | 87 | .Fn fseek |
88 | function clears the end-of-file indicator for the stream and undoes | | 88 | function clears the end-of-file indicator for the stream and undoes |
89 | any effects of the | | 89 | any effects of the |
90 | .Xr ungetc 3 | | 90 | .Xr ungetc 3 |
91 | function on the same stream. | | 91 | function on the same stream. |
92 | .Pp | | 92 | .Pp |
93 | The | | 93 | The |
94 | .Fn fseeko | | 94 | .Fn fseeko |
95 | function is identical to the | | 95 | function is identical to the |
96 | .Fn fseek | | 96 | .Fn fseek |
97 | function except that the | | 97 | function except that the |
98 | .Fa offset | | 98 | .Fa offset |
99 | argument is of type | | 99 | argument is of type |
100 | .Fa off_t . | | 100 | .Fa off_t . |
101 | .Pp | | 101 | .Pp |
102 | The | | 102 | The |
103 | .Fn ftell | | 103 | .Fn ftell |
104 | function | | 104 | function |
105 | obtains the current value of the file position indicator for the | | 105 | obtains the current value of the file position indicator for the |
106 | stream pointed to by | | 106 | stream pointed to by |
107 | .Fa stream . | | 107 | .Fa stream . |
108 | .Pp | | 108 | .Pp |
109 | The | | 109 | The |
110 | .Fn ftello | | 110 | .Fn ftello |
111 | function is identical to the | | 111 | function is identical to the |
112 | .Fn ftell | | 112 | .Fn ftell |
113 | function except that the return value is of type | | 113 | function except that the return value is of type |
114 | .Fa off_t . | | 114 | .Fa off_t . |
115 | .Pp | | 115 | .Pp |
116 | The | | 116 | The |
117 | .Fn rewind | | 117 | .Fn rewind |
118 | function sets the file position indicator for the stream pointed | | 118 | function sets the file position indicator for the stream pointed |
119 | to by | | 119 | to by |
120 | .Fa stream | | 120 | .Fa stream |
121 | to the beginning of the file. | | 121 | to the beginning of the file. |
122 | It is equivalent to: | | 122 | It is equivalent to: |
123 | .Pp | | 123 | .Pp |
124 | .Dl (void)fseek(stream, 0L, SEEK_SET) | | 124 | .Dl (void)fseek(stream, 0L, SEEK_SET) |
125 | .Pp | | 125 | .Pp |
126 | except that the error indicator for the stream is also cleared | | 126 | except that the error indicator for the stream is also cleared |
127 | (see | | 127 | (see |
128 | .Xr clearerr 3 ) . | | 128 | .Xr clearerr 3 ) . |
129 | .Pp | | 129 | .Pp |
130 | In this implementations, | | 130 | In this implementations, |
131 | .Dq Fa fpos_t | | 131 | .Dq Fa fpos_t |
132 | is a complex object that represents both the position and the parse | | 132 | is a complex object that represents both the position and the parse |
133 | state of the stream, making these routines as the only way to portably | | 133 | state of the stream, making these routines the only way to portably |
134 | reposition a text stream. | | 134 | reposition a text stream. |
135 | The | | 135 | The |
136 | .Ar pos | | 136 | .Ar pos |
137 | argument of | | 137 | argument of |
138 | .Fn fsetpos | | 138 | .Fn fsetpos |
139 | must always be initialized by | | 139 | must always be initialized by |
140 | a call to | | 140 | a call to |
141 | .Fn fgetpos . | | 141 | .Fn fgetpos . |
142 | .Sh RETURN VALUES | | 142 | .Sh RETURN VALUES |
143 | The | | 143 | The |
144 | .Fn rewind | | 144 | .Fn rewind |
145 | function | | 145 | function |
146 | returns no value. | | 146 | returns no value. |
147 | .Pp | | 147 | .Pp |
148 | Upon successful completion, | | 148 | Upon successful completion, |
149 | .Fn fgetpos , | | 149 | .Fn fgetpos , |
150 | .Fn fseek , | | 150 | .Fn fseek , |
151 | .Fn fseeko , | | 151 | .Fn fseeko , |
152 | and | | 152 | and |
153 | .Fn fsetpos | | 153 | .Fn fsetpos |
154 | return 0, | | 154 | return 0, |
155 | whereas the functions | | 155 | whereas the functions |
156 | .Fn ftell | | 156 | .Fn ftell |
157 | and | | 157 | and |
158 | .Fn ftello | | 158 | .Fn ftello |
159 | return the current offset. | | 159 | return the current offset. |
160 | On failure, | | 160 | On failure, |
161 | .Fn fseek , | | 161 | .Fn fseek , |
162 | .Fn fseeko , | | 162 | .Fn fseeko , |
163 | .Fn ftell , | | 163 | .Fn ftell , |
164 | and | | 164 | and |
165 | .Fn ftello | | 165 | .Fn ftello |
166 | return \-1, while | | 166 | return \-1, while |
167 | .Fn fgetpos | | 167 | .Fn fgetpos |
168 | and | | 168 | and |
169 | .Fn fsetpos | | 169 | .Fn fsetpos |
170 | return a nonzero value. | | 170 | return a nonzero value. |
171 | .Pp | | 171 | .Pp |
172 | On error all functions set the global variable | | 172 | On error all functions set the global variable |
173 | .Va errno | | 173 | .Va errno |
174 | to indicate the error. | | 174 | to indicate the error. |
175 | Since the | | 175 | Since the |
176 | .Fn rewind | | 176 | .Fn rewind |
177 | function does not return an error code, applications need to clear | | 177 | function does not return an error code, applications need to clear |
178 | .Va errno | | 178 | .Va errno |
179 | before calling it in order to detect errors. | | 179 | before calling it in order to detect errors. |
180 | .Sh ERRORS | | 180 | .Sh ERRORS |
181 | .Bl -tag -width Er | | 181 | .Bl -tag -width Er |
182 | .It Bq Er EBADF | | 182 | .It Bq Er EBADF |
183 | The | | 183 | The |
184 | .Fa stream | | 184 | .Fa stream |
185 | specified | | 185 | specified |
186 | is not a seekable stream. | | 186 | is not a seekable stream. |
187 | .It Bq Er EINVAL | | 187 | .It Bq Er EINVAL |
188 | The | | 188 | The |
189 | .Fa whence | | 189 | .Fa whence |
190 | argument to | | 190 | argument to |
191 | .Fn fseek | | 191 | .Fn fseek |
192 | was not | | 192 | was not |
193 | .Dv SEEK_SET , | | 193 | .Dv SEEK_SET , |
194 | .Dv SEEK_END , | | 194 | .Dv SEEK_END , |
195 | or | | 195 | or |
196 | .Dv SEEK_CUR . | | 196 | .Dv SEEK_CUR . |
197 | .It Bq Er EOVERFLOW | | 197 | .It Bq Er EOVERFLOW |
198 | For | | 198 | For |
199 | .Fn ftell , | | 199 | .Fn ftell , |
200 | the current file offset cannot be represented correctly in an object of type | | 200 | the current file offset cannot be represented correctly in an object of type |
201 | .Fa long . | | 201 | .Fa long . |
202 | .El | | 202 | .El |
203 | .Pp | | 203 | .Pp |
204 | The function | | 204 | The function |
205 | .Fn fgetpos , | | 205 | .Fn fgetpos , |
206 | .Fn fseek , | | 206 | .Fn fseek , |
207 | .Fn fseeko , | | 207 | .Fn fseeko , |
208 | .Fn fsetpos , | | 208 | .Fn fsetpos , |
209 | .Fn ftell , | | 209 | .Fn ftell , |
210 | .Fn ftello , | | 210 | .Fn ftello , |
211 | and | | 211 | and |
212 | .Fn rewind | | 212 | .Fn rewind |
213 | may also fail and set | | 213 | may also fail and set |
214 | .Va errno | | 214 | .Va errno |
215 | for any of the errors specified for the routines | | 215 | for any of the errors specified for the routines |
216 | .Xr fflush 3 , | | 216 | .Xr fflush 3 , |
217 | .Xr fstat 2 , | | 217 | .Xr fstat 2 , |
218 | .Xr lseek 2 , | | 218 | .Xr lseek 2 , |
219 | and | | 219 | and |
220 | .Xr malloc 3 . | | 220 | .Xr malloc 3 . |
221 | .Sh SEE ALSO | | 221 | .Sh SEE ALSO |
222 | .Xr lseek 2 , | | 222 | .Xr lseek 2 , |
223 | .Xr clearerr 3 , | | 223 | .Xr clearerr 3 , |
224 | .Xr ungetc 3 | | 224 | .Xr ungetc 3 |
225 | .Sh STANDARDS | | 225 | .Sh STANDARDS |
226 | The | | 226 | The |
227 | .Fn fgetpos , | | 227 | .Fn fgetpos , |
228 | .Fn fsetpos , | | 228 | .Fn fsetpos , |
229 | .Fn fseek , | | 229 | .Fn fseek , |
230 | .Fn ftell , | | 230 | .Fn ftell , |
231 | and | | 231 | and |
232 | .Fn rewind | | 232 | .Fn rewind |
233 | functions | | 233 | functions |
234 | conform to | | 234 | conform to |
235 | .St -ansiC . | | 235 | .St -ansiC . |
236 | The | | 236 | The |
237 | .Fn fseeko | | 237 | .Fn fseeko |
238 | and | | 238 | and |
239 | .Fn ftello | | 239 | .Fn ftello |
240 | functions conform to | | 240 | functions conform to |
241 | .St -xsh5 . | | 241 | .St -xsh5 . |
242 | .Sh BUGS | | 242 | .Sh BUGS |
243 | The | | 243 | The |
244 | .Fn fgetpos | | 244 | .Fn fgetpos |
245 | and | | 245 | and |
246 | .Fn fsetpos | | 246 | .Fn fsetpos |
247 | functions don't store/set shift states of the stream in this implementation. | | 247 | functions don't store/set shift states of the stream in this implementation. |