fseek(3c) - osol9

1fseek(3C)                Standard C Library Functions                fseek(3C)
2
3
4

NAME

6       fseek, fseeko - reposition a file-position indicator in a stream
7

SYNOPSIS

9       #include <stdio.h>
10
11       int fseek(FILE *stream, long offset, int whence);
12
13
14       int fseeko(FILE *stream, off_t offset, int whence);
15
16

DESCRIPTION

18       The  fseek()  function  sets the file-position indicator for the stream
19       pointed to by stream. The fseeko() function  is  identical  to  fseek()
20       except for the type of offset.
21
22
23       The  new position, measured in bytes from the beginning of the file, is
24       obtained by adding offset to the position specified  by  whence,  whose
25       values are defined in <stdio.h> as follows:
26
27       SEEK_SET    Set position equal to offset bytes.
28
29
30       SEEK_CUR    Set position to current location plus offset.
31
32
33       SEEK_END    Set position to EOF plus offset.
34
35
36
37       If the stream is to be used with wide character input/output functions,
38       offset must either be 0 or a value  returned  by  an  earlier  call  to
39       ftell(3C) on the same stream and whence must be SEEK_SET.
40
41
42       A  successful  call to fseek() clears the end-of-file indicator for the
43       stream and undoes any effects of ungetc(3C) and ungetwc(3C) on the same
44       stream.   After an fseek() call, the next operation on an update stream
45       may be either input or output.
46
47
48       If the most recent operation, other than ftell(3C), on a  given  stream
49       is  fflush(3C), the file offset in the underlying open file description
50       will be adjusted to reflect the location specified by fseek().
51
52
53       The fseek() function allows  the  file-position  indicator  to  be  set
54       beyond  the  end of existing data in the file. If data is later written
55       at this point, subsequent reads of data in the gap  will  return  bytes
56       with the value 0 until data is actually written into the gap.
57
58
59       The  value  of the file offset returned by fseek() on devices which are
60       incapable of seeking is undefined.
61
62
63       If the stream is writable and buffered data had not been written to the
64       underlying file, fseek() will cause the unwritten data to be written to
65       the file and mark the st_ctime and st_mtime  fields  of  the  file  for
66       update.
67

RETURN VALUES

69       The fseek() and fseeko() functions return 0 on success; otherwise, they
70       returned −1 and set errno to indicate the error.
71

ERRORS

73       The fseek() and fseeko() functions will fail if, either the  stream  is
74       unbuffered or the stream's buffer needed to be flushed, and the call to
75       fseek() or fseeko() causes an underlying lseek(2)  or  write(2)  to  be
76       invoked:
77
78       EAGAIN    The  O_NONBLOCK  flag  is set for the file descriptor and the
79                 process would be delayed in the write operation.
80
81
82       EBADF     The file descriptor underlying the stream file  is  not  open
83                 for  writing  or the stream's buffer needed to be flushed and
84                 the file is not open.
85
86
87       EFBIG     An attempt was made to write a file that exceeds the  maximum
88                 file  size or the process's file size limit, or the file is a
89                 regular file and an attempt was made to write  at  or  beyond
90                 the offset maximum associated with the corresponding stream.
91
92
93       EINTR     The  write  operation  was terminated due to the receipt of a
94                 signal, and no data was transferred.
95
96
97       EINVAL    The whence argument is invalid. The  resulting  file-position
98                 indicator would be set to a negative value.
99
100
101       EIO       A physical I/O error has occurred; or the process is a member
102                 of  a  background  process  group  attempting  to  perform  a
103                 write(2)  operation  to  its  controlling terminal, TOSTOP is
104                 set, the process is neither ignoring  nor  blocking  SIGTTOU,
105                 and the process group of the process is orphaned.
106
107
108       ENOSPC    There  was  no  free space remaining on the device containing
109                 the file.
110
111
112       ENXIO     A request was made of a non-existent device, or  the  request
113                 was outside the capabilities of the device.
114
115
116       EPIPE     The  file  descriptor  underlying stream is associated with a
117                 pipe or FIFO.
118
119
120       EPIPE     An attempt was made to write to a pipe or FIFO  that  is  not
121                 open  for  reading by any process. A SIGPIPE signal will also
122                 be sent to the calling thread.
123
124
125
126       The fseek() function will fail if:
127
128       EOVERFLOW    The resulting file offset would be a value which cannot be
129                    represented correctly in an object of type long.
130
131
132
133       The fseeko() function will fail if:
134
135       EOVERFLOW    The resulting file offset would be a value which cannot be
136                    represented correctly in an object of type off_t.
137
138

USAGE

140       Although on the UNIX system an offset returned by ftell()  or  ftello()
141       (see  ftell(3C)) is measured in bytes, and it is permissible to seek to
142       positions relative to that  offset,  portability  to  non-UNIX  systems
143       requires  that  an  offset be used by fseek() directly.  Arithmetic may
144       not meaningfully be performed on such an offset, which is not necessar‐
145       ily measured in bytes.
146
147
148       The fseeko() function has a transitional interface for 64-bit file off‐
149       sets.  See lf64(5).
150

ATTRIBUTES

152       See attributes(5) for descriptions of the following attributes:
153
154
155
156
157       ┌─────────────────────────────┬─────────────────────────────┐
158       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
159       ├─────────────────────────────┼─────────────────────────────┤
160       │Interface Stability          │Standard                     │
161       ├─────────────────────────────┼─────────────────────────────┤
162       │MT-Level                     │MT-Safe                      │
163       └─────────────────────────────┴─────────────────────────────┘
164