usr/src/man/man3c/fseek.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T.
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  45 .\" Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\"
  47 .TH FSEEK 3C "May 13, 2017"
  48 .SH NAME
  49 fseek, fseeko \- reposition a file-position indicator in a stream
  50 .SH SYNOPSIS
  51 .LP
  52 .nf
  53 #include <stdio.h>
  54
  55 \fBint\fR \fBfseek\fR(\fBFILE *\fR\fIstream\fR, \fBlong\fR \fIoffset\fR, \fBint\fR \fIwhence\fR);
  56 .fi
  57
  58 .LP
  59 .nf
  60 \fBint\fR \fBfseeko\fR(\fBFILE *\fR\fIstream\fR, \fBoff_t\fR \fIoffset\fR, \fBint\fR \fIwhence\fR);
  61 .fi
  62
  63 .SH DESCRIPTION
  64 .LP
  65 The \fBfseek()\fR function sets the file-position indicator for the stream
  66 pointed to by \fIstream\fR. The \fBfseeko()\fR function is identical to
  67 \fBfseek()\fR except for the type of \fIoffset\fR.
  68 .sp
  69 .LP
  70 The new position, measured in bytes from the beginning of the file, is obtained
  71 by adding \fIoffset\fR to the position specified by \fIwhence\fR, whose values
  72 are defined in <\fBstdio.h\fR> as follows:
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fBSEEK_SET\fR\fR
  77 .ad
  78 .RS 12n
  79 Set position equal to \fIoffset\fR bytes.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBSEEK_CUR\fR\fR
  86 .ad
  87 .RS 12n
  88 Set position to current location plus \fIoffset\fR.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fBSEEK_END\fR\fR
  95 .ad
  96 .RS 12n
  97 Set position to \fBEOF\fR plus \fIoffset\fR.
  98 .RE
  99
 100 .sp
 101 .LP
 102 If the stream is to be used with wide character input/output functions,
 103 \fIoffset\fR must either be 0 or a value returned by an earlier call to
 104 \fBftell\fR(3C) on the same stream and \fIwhence\fR must be \fBSEEK_SET\fR.
 105 .sp
 106 .LP
 107 A successful call to \fBfseek()\fR clears the end-of-file indicator for the
 108 stream and undoes any effects of \fBungetc\fR(3C) and \fBungetwc\fR(3C) on the
 109 same stream.  After an \fBfseek()\fR call, the next operation on an update
 110 stream may be either input or output.
 111 .sp
 112 .LP
 113 If the most recent operation, other than \fBftell\fR(3C), on a given stream is
 114 \fBfflush\fR(3C), the file offset in the underlying open file description will
 115 be adjusted to reflect the location specified by \fBfseek()\fR.
 116 .sp
 117 .LP
 118 The \fBfseek()\fR function allows the file-position indicator to be set beyond
 119 the end of existing data in the file. If data is later written at this point,
 120 subsequent reads of data in the gap will return bytes with the value 0 until
 121 data is actually written into the gap.
 122 .sp
 123 .LP
 124 The value of the file offset returned by \fBfseek()\fR on devices which are
 125 incapable of seeking is undefined.
 126 .sp
 127 .LP
 128 If the stream is writable and buffered data had not been written to the
 129 underlying file, \fBfseek()\fR will cause the unwritten data to be written to
 130 the file and mark the \fBst_ctime\fR and \fBst_mtime\fR fields of the file for
 131 update.
 132 .SH RETURN VALUES
 133 .LP
 134 The \fBfseek()\fR and \fBfseeko()\fR functions return \fB0\fR on success;
 135 otherwise, they returned \fB\(mi1\fR and set \fBerrno\fR to indicate the error.
 136 .SH ERRORS
 137 .LP
 138 The \fBfseek()\fR and \fBfseeko()\fR functions will fail if, either the
 139 \fIstream\fR is unbuffered or the \fIstream\fR's buffer needed to be flushed,
 140 and the call to \fBfseek()\fR or \fBfseeko()\fR causes an underlying
 141 \fBlseek\fR(2) or \fBwrite\fR(2) to be invoked:
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fBEAGAIN\fR\fR
 146 .ad
 147 .RS 10n
 148 The \fBO_NONBLOCK\fR flag is set for the file descriptor and the process would
 149 be delayed in the write operation.
 150 .RE
 151
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fBEBADF\fR\fR
 156 .ad
 157 .RS 10n
 158 The file descriptor underlying the stream file is not open for writing or the
 159 stream's buffer needed to be flushed and the file is not open.
 160 .RE
 161
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fBEFBIG\fR\fR
 166 .ad
 167 .RS 10n
 168 An attempt was made to write a file that exceeds the maximum file size or the
 169 process's file size limit, or the file is a regular file and an attempt was
 170 made to write at or beyond the offset maximum associated with the corresponding
 171 stream.
 172 .RE
 173
 174 .sp
 175 .ne 2
 176 .na
 177 \fB\fBEINTR\fR\fR
 178 .ad
 179 .RS 10n
 180 The write operation was terminated due to the receipt of a signal, and no data
 181 was transferred.
 182 .RE
 183
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fBEINVAL\fR\fR
 188 .ad
 189 .RS 10n
 190 The \fIwhence\fR argument is invalid. The resulting file-position indicator
 191 would be set to a negative value.
 192 .RE
 193
 194 .sp
 195 .ne 2
 196 .na
 197 \fB\fBEIO\fR\fR
 198 .ad
 199 .RS 10n
 200 A physical I/O error has occurred; or the process is a member of a background
 201 process group attempting to perform a \fBwrite\fR(2) operation to its
 202 controlling terminal, \fBTOSTOP\fR is set, the process is neither ignoring nor
 203 blocking \fBSIGTTOU\fR, and the process group of the process is orphaned.
 204 .RE
 205
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fBENOSPC\fR\fR
 210 .ad
 211 .RS 10n
 212 There was no free space remaining on the device containing the file.
 213 .RE
 214
 215 .sp
 216 .ne 2
 217 .na
 218 \fB\fBENXIO\fR\fR
 219 .ad
 220 .RS 10n
 221 A request was made of a non-existent device, or the request was outside the
 222 capabilities of the device.
 223 .RE
 224
 225 .sp
 226 .ne 2
 227 .na
 228 \fB\fBEPIPE\fR\fR
 229 .ad
 230 .RS 10n
 231 The file descriptor underlying \fIstream\fR is associated with a pipe or FIFO.
 232 .RE
 233
 234 .sp
 235 .ne 2
 236 .na
 237 \fB\fBEPIPE\fR\fR
 238 .ad
 239 .RS 10n
 240 An attempt was made to write to a pipe or \fBFIFO\fR that is not open for
 241 reading by any process. A \fBSIGPIPE\fR signal will also be sent to the calling
 242 thread.
 243 .RE
 244
 245 .sp
 246 .LP
 247 The \fBfseek()\fR function will fail if:
 248 .sp
 249 .ne 2
 250 .na
 251 \fB\fBEOVERFLOW\fR\fR
 252 .ad
 253 .RS 13n
 254 The resulting file offset would be a value which cannot be represented
 255 correctly in an object of type \fBlong\fR.
 256 .RE
 257
 258 .sp
 259 .LP
 260 The \fBfseeko()\fR function will fail if:
 261 .sp
 262 .ne 2
 263 .na
 264 \fB\fBEOVERFLOW\fR\fR
 265 .ad
 266 .RS 13n
 267 The resulting file offset would be a value which cannot be represented
 268 correctly in an object of type \fBoff_t\fR.
 269 .RE
 270
 271 .SH USAGE
 272 .LP
 273 Although on the UNIX system an offset returned by \fBftell()\fR or
 274 \fBftello()\fR (see \fBftell\fR(3C)) is measured in bytes, and it is
 275 permissible to seek to positions relative to that offset, portability to
 276 non-UNIX systems requires that an offset be used by \fBfseek()\fR directly.
 277 Arithmetic may not meaningfully be performed on such an offset, which is not
 278 necessarily measured in bytes.
 279 .sp
 280 .LP
 281 The \fBfseeko()\fR function has a transitional interface for 64-bit file
 282 offsets.  See \fBlf64\fR(5).
 283 .SH ATTRIBUTES
 284 .LP
 285 See \fBattributes\fR(5) for descriptions of the following attributes:
 286 .sp
 287
 288 .sp
 289 .TS
 290 box;
 291 c | c
 292 l | l .
 293 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 294 _
 295 Interface Stability     Standard
 296 _
 297 MT-Level        MT-Safe
 298 .TE
 299
 300 .SH SEE ALSO
 301 .LP
 302 \fBgetrlimit\fR(2), \fBulimit\fR(2), \fBftell\fR(3C),
 303 \fBrewind\fR(3C), \fBungetc\fR(3C), \fBungetwc\fR(3C), \fBattributes\fR(5),
 304 \fBlf64\fR(5), \fBstandards\fR(5)