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