.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\" must display the following acknowledgement:
-.\" This product includes software developed by the University of
-.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\" SUCH DAMAGE.
.\"
.\" @(#)fseek.3 8.1 (Berkeley) 6/4/93
-.\" $FreeBSD: src/lib/libc/stdio/fseek.3,v 1.24 2002/12/19 09:40:24 ru Exp $
+.\" $FreeBSD: src/lib/libc/stdio/fseek.3,v 1.27 2007/06/18 02:13:04 ache Exp $
.\"
-.Dd October 12, 2002
+.Dd March 19, 2004
.Dt FSEEK 3
.Os
.Sh NAME
.Sh SYNOPSIS
.In stdio.h
.Ft int
-.Fn fseek "FILE *stream" "long offset" "int whence"
-.Ft long
-.Fn ftell "FILE *stream"
-.Ft void
-.Fn rewind "FILE *stream"
+.Fo fgetpos
+.Fa "FILE *restrict stream"
+.Fa "fpos_t *restrict pos"
+.Fc
.Ft int
-.Fn fgetpos "FILE * restrict stream" "fpos_t * restrict pos"
+.Fo fseek
+.Fa "FILE *stream"
+.Fa "long offset"
+.Fa "int whence"
+.Fc
.Ft int
-.Fn fsetpos "FILE *stream" "const fpos_t *pos"
-.In sys/types.h
+.Fo fseeko
+.Fa "FILE *stream"
+.Fa "off_t offset"
+.Fa "int whence"
+.Fc
.Ft int
-.Fn fseeko "FILE *stream" "off_t offset" "int whence"
+.Fo fsetpos
+.Fa "FILE *stream"
+.Fa "const fpos_t *pos"
+.Fc
+.Ft long
+.Fo ftell
+.Fa "FILE *stream"
+.Fc
.Ft off_t
-.Fn ftello "FILE *stream"
+.Fo ftello
+.Fa "FILE *stream"
+.Fc
+.Ft void
+.Fo rewind
+.Fa "FILE *stream"
+.Fc
.Sh DESCRIPTION
The
.Fn fseek
and
.Fn fsetpos
functions
-are alternate interfaces equivalent to
+are alternate interfaces for retrieving and setting the current position in
+the file, similar to
.Fn ftell
and
-.Fn fseek
-(with whence set to
-.Dv SEEK_SET ) ,
-setting and storing the current value of
-the file offset into or from the object referenced by
+.Fn fseek ,
+except that the current position is stored in an opaque object of
+type
+.Vt fpos_t
+pointed to by
.Fa pos .
-On some
-.Pq non- Ns Tn UNIX
-systems an
-.Dq Fa fpos_t
-object may be a complex object
-and these routines may be the only way to portably reposition a text stream.
+These functions provide a portable way to seek to offsets larger than
+those that can be represented by a
+.Vt long int .
+They may also store additional state information in the
+.Vt fpos_t
+object to facilitate seeking within files containing multibyte
+characters with state-dependent encodings.
+Although
+.Vt fpos_t
+has traditionally been an integral type,
+applications cannot assume that it is;
+in particular, they must not perform arithmetic on objects
+of this type.
.Pp
If the stream is a wide character stream (see
.Xr fwide 3 ) ,
.Fn fseeko ,
.Fn fsetpos ,
.Fn ftell ,
+.Fn ftello ,
and
-.Fn ftello
+.Fn rewind
may also fail and set
.Va errno
for any of the errors specified for the routines
.Xr lseek 2 ,
and
.Xr malloc 3 .
+.Sh LEGACY SYNOPSIS
+.Fd #include <stdio.h>
+.Fd #include <sys/types.h>
+.Pp
+.Ft int
+.br
+.Fo fseeko
+.Fa "FILE *stream"
+.Fa "off_t offset"
+.Fa "int whence"
+.Fc ;
+.Pp
+The include file
+.In sys/types.h
+supplies the definition for
+.Vt off_t .
.Sh SEE ALSO
.Xr lseek 2 ,
.Xr clearerr 3 ,
.Xr fwide 3 ,
.Xr ungetc 3 ,
-.Xr ungetwc 3
+.Xr ungetwc 3 ,
+.Xr compat 5
.Sh STANDARDS
The
.Fn fgetpos ,
projects / apple / libc.git / blobdiff