[unix-history] / usr / src / lib / libc / stdio / fseek.3

.\" Copyright (c) 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek.
.\"
.\" %sccs.include.redist.man%
.\"
.\"	@(#)fseek.3	6.8 (Berkeley) %G%
.\"
.TH FSEEK 3 ""
.UC 7
.SH NAME
fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream
.SH SYNOPSIS
.nf
.ft B
#include <stdio.h>

int
fseek(FILE *stream, long offset, int whence);

long
ftell(FILE *stream);

void
rewind(FILE *stream);

int
fgetpos(FILE *stream, fpos_t *pos);

int
fsetpos(FILE *stream, fpos_t *pos);
.ft R
.fi
.SH DESCRIPTION
.I Fseek
sets the position of the next input or output
operation on the given
.IR stream .
The new position is at the signed distance
.I offset
bytes from a specified point in the file depending on the
value of 
.IR whence .
If 
.I whence
is set to SEEK_SET, SEEK_CUR, or SEEK_END, the offset is from the
beginning, the current position, or the end of the file, respectively.
.I Fseek
undoes any effects of
.IR ungetc .
.PP
.I Ftell
returns the current value of the offset relative to the beginning
of the file associated with the named
.IR stream .
.PP
.IR Rewind
is equivalent to ``fseek(stream, 0L, SEEK_SET)'', except the error
indicator for the stream is cleared as well (see
.IR clearerr (3)).
.PP
.I Fgetpos
and
.I fsetpos
are alternate interfaces equivalent to
.I ftell
and
.I fseek
(with whence set to SEEK_SET), setting and storing the current value of
the file offset into or from the object referenced by 
.IR pos .
On some (non-UNIX) systems an ``fpos_t'' object may be a complex object
and these routines may be the only way to portably reposition a text stream.
.SH "SEE ALSO"
lseek(2)
.SH "RETURN VALUE"
.I Rewind
returns no value.
Upon successful completion,
.IR fgetpos ,
.IR fseek ,
and
.I fsetpos
return 0,
and
.I ftell
returns the current offset.
Otherwise, \-1 is returned and the global variable errno is set to
indicate the error.
.SH ERRORS
.TP 15
[EBADF]
.I Stream
is not a seekable stream.
.TP
[EINVAL]
The
.I whence
argument to 
.I fseek
was not SEEK_SET, SEEK_END, or SEEK_CUR.
.PP
.IR Fgetpos ,
.IR fseek ,
.IR fsetpos ,
and 
.I ftell
may also fail and set
.I errno
for any of the errors specified for the routines
.IR fflush (3),
.IR fstat (2),
.IR lseek (2),
and 
.IR malloc (3).
.SH STANDARDS
.IR Fgetpos ,
.IR fsetpos ,
.IR fseek ,
.IR ftell ,
and
.IR rewind
conform to ANSI X3.159-1989 (``ANSI C'').
Commit	Line	Data
411867e7 KB	1	.\" Copyright (c) 1990 The Regents of the University of California.
411867e7 KB	2	.\" All rights reserved.
4f278f49	3	.\"
411867e7 KB	4	.\" This code is derived from software contributed to Berkeley by
	5	.\" Chris Torek.
	6	.\"
	7	.\" %sccs.include.redist.man%
	8	.\"
36e9970b	9	.\" @(#)fseek.3 6.8 (Berkeley) %G%
411867e7 KB	10	.\"
	11	.TH FSEEK 3 ""
	12	.UC 7
4f278f49	13	.SH NAME
411867e7	14	fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream
4f278f49	15	.SH SYNOPSIS
411867e7 KB	16	.nf
	17	.ft B
	18	#include <stdio.h>
	19
	20	int
	21	fseek(FILE *stream, long offset, int whence);
	22
	23	long
	24	ftell(FILE *stream);
	25
	26	void
	27	rewind(FILE *stream);
	28
	29	int
	30	fgetpos(FILE stream, fpos_t pos);
	31
	32	int
	33	fsetpos(FILE stream, fpos_t pos);
	34	.ft R
	35	.fi
4f278f49 KM	36	.SH DESCRIPTION
	37	.I Fseek
	38	sets the position of the next input or output
411867e7	39	operation on the given
4f278f49 KM	40	.IR stream .
	41	The new position is at the signed distance
	42	.I offset
411867e7 KB	43	bytes from a specified point in the file depending on the
	44	value of
	45	.IR whence .
	46	If
	47	.I whence
1382c0b2 KB	48	is set to SEEK_SET, SEEK_CUR, or SEEK_END, the offset is from the
1382c0b2 KB	49	beginning, the current position, or the end of the file, respectively.
4f278f49 KM	50	.I Fseek
4f278f49 KM	51	undoes any effects of
411867e7	52	.IR ungetc .
4f278f49 KM	53	.PP
	54	.I Ftell
	55	returns the current value of the offset relative to the beginning
	56	of the file associated with the named
	57	.IR stream .
4f278f49	58	.PP
411867e7 KB	59	.IR Rewind
	60	is equivalent to ``fseek(stream, 0L, SEEK_SET)'', except the error
	61	indicator for the stream is cleared as well (see
	62	.IR clearerr (3)).
	63	.PP
	64	.I Fgetpos
	65	and
	66	.I fsetpos
	67	are alternate interfaces equivalent to
	68	.I ftell
	69	and
	70	.I fseek
	71	(with whence set to SEEK_SET), setting and storing the current value of
	72	the file offset into or from the object referenced by
	73	.IR pos .
	74	On some (non-UNIX) systems an ``fpos_t'' object may be a complex object
	75	and these routines may be the only way to portably reposition a text stream.
4f278f49	76	.SH "SEE ALSO"
411867e7 KB	77	lseek(2)
	78	.SH "RETURN VALUE"
	79	.I Rewind
	80	returns no value.
	81	Upon successful completion,
	82	.IR fgetpos ,
	83	.IR fseek ,
411867e7	84	and
36e9970b KB	85	.I fsetpos
	86	return 0,
	87	and
	88	.I ftell
	89	returns the current offset.
411867e7 KB	90	Otherwise, \-1 is returned and the global variable errno is set to
	91	indicate the error.
	92	.SH ERRORS
	93	.TP 15
	94	[EBADF]
	95	.I Stream
	96	is not a seekable stream.
	97	.TP
	98	[EINVAL]
	99	The
	100	.I whence
	101	argument to
	102	.I fseek
	103	was not SEEK_SET, SEEK_END, or SEEK_CUR.
	104	.PP
	105	.IR Fgetpos ,
	106	.IR fseek ,
	107	.IR fsetpos ,
	108	and
	109	.I ftell
	110	may also fail and set
	111	.I errno
	112	for any of the errors specified for the routines
	113	.IR fflush (3),
	114	.IR fstat (2),
	115	.IR lseek (2),
	116	and
	117	.IR malloc (3).
	118	.SH STANDARDS
	119	.IR Fgetpos ,
	120	.IR fsetpos ,
	121	.IR fseek ,
	122	.IR ftell ,
	123	and
	124	.IR rewind
	125	conform to ANSI X3.159-1989 (``ANSI C'').