Commit | Line | Data |
---|---|---|
ae59e04c | 1 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
411867e7 | 2 | .\" All rights reserved. |
4f278f49 | 3 | .\" |
411867e7 | 4 | .\" This code is derived from software contributed to Berkeley by |
043368e6 KB |
5 | .\" Chris Torek and the American National Standards Committee X3, |
6 | .\" on Information Processing Systems. | |
7 | .\" | |
411867e7 KB |
8 | .\" %sccs.include.redist.man% |
9 | .\" | |
043368e6 | 10 | .\" @(#)fseek.3 6.11 (Berkeley) %G% |
411867e7 | 11 | .\" |
ae59e04c CL |
12 | .Dd |
13 | .Dt FSEEK 3 | |
14 | .Os | |
15 | .Sh NAME | |
16 | .Nm fgetpos , | |
17 | .Nm fseek , | |
18 | .Nm fsetpos , | |
19 | .Nm ftell , | |
20 | .Nm rewind | |
21 | .Nd reposition a stream | |
22 | .Sh SYNOPSIS | |
23 | .Fd #include <stdio.h> | |
24 | .Ft int | |
25 | .Fn fseek "FILE *stream" "long offset" "int whence" | |
26 | .Ft long | |
27 | .Fn ftell "FILE *stream" | |
28 | .Ft void | |
29 | .Fn rewind "FILE *stream" | |
30 | .Ft int | |
31 | .Fn fgetpos "FILE *stream" "fpos_t *pos" | |
32 | .Ft int | |
33 | .Fn fsetpos "FILE *stream" "fpos_t *pos" | |
34 | .Sh DESCRIPTION | |
35 | The | |
36 | .Fn fseek | |
37 | function sets the file position indicator for the stream pointed | |
38 | to by | |
39 | .Fa stream . | |
40 | The new position, measured in bytes, is obtained by adding | |
41 | .Fa offset | |
42 | bytes to the position specified by | |
43 | .Fa whence . | |
411867e7 | 44 | If |
ae59e04c CL |
45 | .Fa whence |
46 | is set to | |
47 | .Dv SEEK_SET , | |
48 | .Dv SEEK_CUR , | |
49 | or | |
50 | .Dv SEEK_END , | |
51 | the offset is relative to the | |
52 | start of the file, the current position indicator, or end-of-file, | |
53 | respectively. | |
54 | A successful call to the | |
55 | .Fn fseek | |
56 | function clears the end-of-file indicator for the stream and undoes | |
57 | any effects of the | |
58 | .Xr ungetc 3 | |
59 | function on the same stream. | |
60 | .Pp | |
61 | The | |
62 | .Fn ftell | |
63 | function | |
64 | obtains the current value of the file position indicator for the | |
65 | stream pointed to by | |
66 | .Fa stream . | |
67 | .Pp | |
68 | The | |
69 | .Fn rewind | |
70 | function sets the file position indicator for the stream pointed | |
71 | to by | |
72 | .Fa stream | |
73 | to the beginning of the file. | |
74 | It is equivalent to: | |
75 | .Pp | |
76 | .Dl (void)fseek(stream, 0L, SEEK_SET) | |
77 | .Pp | |
78 | except that the error indicator for the stream is also cleared | |
79 | (see | |
80 | .Xr clearerr 3 ) . | |
81 | .Pp | |
82 | The | |
83 | .Fn fgetpos | |
411867e7 | 84 | and |
ae59e04c CL |
85 | .Fn fsetpos |
86 | functions | |
411867e7 | 87 | are alternate interfaces equivalent to |
ae59e04c | 88 | .Fn ftell |
411867e7 | 89 | and |
ae59e04c CL |
90 | .Fn fseek |
91 | (with whence set to | |
92 | .Dv SEEK_SET | |
93 | ), setting and storing the current value of | |
411867e7 | 94 | the file offset into or from the object referenced by |
ae59e04c CL |
95 | .Fa pos . |
96 | On some | |
d5001484 | 97 | .Pq non- Ns Tn UNIX |
ae59e04c CL |
98 | systems an |
99 | .Dq Fa fpos_t | |
100 | object may be a complex object | |
411867e7 | 101 | and these routines may be the only way to portably reposition a text stream. |
ae59e04c CL |
102 | .Sh RETURN VALUES |
103 | The | |
104 | .Fn rewind | |
105 | function | |
411867e7 KB |
106 | returns no value. |
107 | Upon successful completion, | |
ae59e04c CL |
108 | .Fn fgetpos , |
109 | .Fn fseek , | |
d5001484 CL |
110 | .Fn fsetpos |
111 | return 0, | |
36e9970b | 112 | and |
ae59e04c | 113 | .Fn ftell |
d5001484 | 114 | returns the current offset. |
411867e7 KB |
115 | Otherwise, \-1 is returned and the global variable errno is set to |
116 | indicate the error. | |
ae59e04c CL |
117 | .Sh ERRORS |
118 | .Bl -tag -width [EINVAL] | |
119 | .It Bq Er EBADF | |
120 | The | |
121 | .Fa stream | |
122 | specified | |
411867e7 | 123 | is not a seekable stream. |
ae59e04c | 124 | .It Bq Er EINVAL |
411867e7 | 125 | The |
ae59e04c | 126 | .Fa whence |
411867e7 | 127 | argument to |
ae59e04c CL |
128 | .Fn fseek |
129 | was not | |
130 | .Dv SEEK_SET , | |
131 | .Dv SEEK_END , | |
132 | or | |
133 | .Dv SEEK_CUR . | |
134 | .El | |
135 | .Pp | |
136 | The function | |
137 | .Fn fgetpos , | |
138 | .Fn fseek , | |
139 | .Fn fsetpos , | |
411867e7 | 140 | and |
ae59e04c | 141 | .Fn ftell |
411867e7 | 142 | may also fail and set |
ae59e04c | 143 | .Va errno |
411867e7 | 144 | for any of the errors specified for the routines |
ae59e04c CL |
145 | .Xr fflush 3 , |
146 | .Xr fstat 2 , | |
147 | .Xr lseek 2 , | |
411867e7 | 148 | and |
ae59e04c CL |
149 | .Xr malloc 3 . |
150 | .Sh SEE ALSO | |
151 | .Xr lseek 2 | |
152 | .Sh STANDARDS | |
153 | The | |
154 | .Fn fgetpos , | |
155 | .Fn fsetpos , | |
156 | .Fn fseek , | |
157 | .Fn ftell , | |
411867e7 | 158 | and |
ae59e04c CL |
159 | .Fn rewind |
160 | functions | |
161 | conform to | |
162 | .St -ansiC . |