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

.\" Copyright (c) 1980 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)fopen.3	6.3 (Berkeley) %G%
.\"
.TH FOPEN 3S  ""
.UC 4
.SH NAME
fopen, freopen, fdopen \- open a stream
.SH SYNOPSIS
.B #include <stdio.h>
.PP
.SM
.B FILE
.B *fopen(filename, type)
.br
.B char *filename, *type;
.PP
.SM
.B FILE
.B *freopen(filename, type, stream)
.br
.B char *filename, *type;
.br
.SM
.B FILE
.B *stream;
.PP
.SM
.B FILE
.B *fdopen(fildes, type)
.br
.B char *type;
.SH DESCRIPTION
.I Fopen
opens the file named by
.I filename
and associates a stream with it.
.I Fopen
returns a pointer to be used to identify the stream in subsequent operations.
.PP
.I Type
is a character string having one of the following values:
.TP 5
"r"
open for reading
.ns
.TP 5
"w"
create for writing
.ns
.TP 5
"a"
append: open for writing at end of file, or create for writing
.PP
In addition, each
.I type
may be followed by a "+" to have the file opened for reading and writing.
"r+" positions the stream at the beginning of the file, "w+" creates
or truncates it, and "a+" positions it at the end.  Both reads and writes
may be used on read/write streams, with the limitation that an
.I fseek, rewind,
or reading an end-of-file must be used between a read and a write or vice-versa.
.PP
.I Freopen
substitutes the named file in place of the open
.IR stream .
It returns the original value of
.IR stream .
The original stream is closed.
.PP
.I Freopen
is typically used to attach the preopened constant names,
.B stdin, stdout, stderr,
to specified files.
.PP
.I Fdopen
associates a stream with a file descriptor obtained from
.I open, dup, creat,
or
.IR pipe (2).
The
.I type
of the stream must agree with the mode of the open file.
.SH "SEE ALSO"
open(2),
fclose(3)
.SH DIAGNOSTICS
.I Fopen
and 
.I freopen
return the pointer
.SM
.B NULL
if
.I filename
cannot be accessed,
if too many files are already open,
or if other resources needed cannot be allocated.
.SH BUGS
.I Fdopen
is not portable to systems other than UNIX.
.PP
The read/write 
.I types
do not exist on all systems.  Those systems without
read/write modes will probably treat the 
.I type
as if the "+" was not present.  These are unreliable in any event.
.PP
In order to support the same number of open files as does the system,
.I fopen
must allocate additional memory for data structures using
.I calloc
after 20 files have been opened.
This confuses some programs which use their own memory allocators.
An undocumented routine,
.IR f_prealloc ,
may be called to force immediate allocation of all internal memory
except for buffers.
Commit	Line	Data
251f9c2d KM	1	.\" Copyright (c) 1980 Regents of the University of California.
	2	.\" All rights reserved. The Berkeley software License Agreement
	3	.\" specifies the terms and conditions for redistribution.
	4	.\"
17eb345e	5	.\" @(#)fopen.3 6.3 (Berkeley) %G%
251f9c2d	6	.\"
cf0272dc	7	.TH FOPEN 3S ""
251f9c2d KM	8	.UC 4
	9	.SH NAME
	10	fopen, freopen, fdopen \- open a stream
	11	.SH SYNOPSIS
	12	.B #include <stdio.h>
	13	.PP
	14	.SM
	15	.B FILE
	16	.B *fopen(filename, type)
	17	.br
	18	.B char filename, type;
	19	.PP
	20	.SM
	21	.B FILE
	22	.B *freopen(filename, type, stream)
	23	.br
	24	.B char filename, type;
	25	.br
	26	.SM
	27	.B FILE
	28	.B *stream;
	29	.PP
	30	.SM
	31	.B FILE
	32	.B *fdopen(fildes, type)
	33	.br
	34	.B char *type;
	35	.SH DESCRIPTION
	36	.I Fopen
	37	opens the file named by
	38	.I filename
	39	and associates a stream with it.
	40	.I Fopen
e2703397	41	returns a pointer to be used to identify the stream in subsequent operations.
251f9c2d KM	42	.PP
	43	.I Type
	44	is a character string having one of the following values:
	45	.TP 5
	46	"r"
	47	open for reading
	48	.ns
	49	.TP 5
	50	"w"
	51	create for writing
	52	.ns
	53	.TP 5
	54	"a"
e2703397	55	append: open for writing at end of file, or create for writing
251f9c2d KM	56	.PP
	57	In addition, each
	58	.I type
17eb345e	59	may be followed by a "+" to have the file opened for reading and writing.
e2703397	60	"r+" positions the stream at the beginning of the file, "w+" creates
251f9c2d KM	61	or truncates it, and "a+" positions it at the end. Both reads and writes
	62	may be used on read/write streams, with the limitation that an
	63	.I fseek, rewind,
e2703397	64	or reading an end-of-file must be used between a read and a write or vice-versa.
251f9c2d KM	65	.PP
251f9c2d KM	66	.I Freopen
e2703397	67	substitutes the named file in place of the open
251f9c2d KM	68	.IR stream .
	69	It returns the original value of
	70	.IR stream .
	71	The original stream is closed.
	72	.PP
	73	.I Freopen
e2703397	74	is typically used to attach the preopened constant names,
251f9c2d KM	75	.B stdin, stdout, stderr,
	76	to specified files.
	77	.PP
	78	.I Fdopen
	79	associates a stream with a file descriptor obtained from
	80	.I open, dup, creat,
	81	or
	82	.IR pipe (2).
	83	The
	84	.I type
	85	of the stream must agree with the mode of the open file.
	86	.SH "SEE ALSO"
	87	open(2),
	88	fclose(3)
	89	.SH DIAGNOSTICS
	90	.I Fopen
	91	and
	92	.I freopen
	93	return the pointer
	94	.SM
	95	.B NULL
	96	if
	97	.I filename
c719da84 MK	98	cannot be accessed,
	99	if too many files are already open,
	100	or if other resources needed cannot be allocated.
251f9c2d KM	101	.SH BUGS
	102	.I Fdopen
	103	is not portable to systems other than UNIX.
	104	.PP
	105	The read/write
	106	.I types
	107	do not exist on all systems. Those systems without
	108	read/write modes will probably treat the
	109	.I type
17eb345e	110	as if the "+" was not present. These are unreliable in any event.
c719da84 MK	111	.PP
	112	In order to support the same number of open files as does the system,
	113	.I fopen
	114	must allocate additional memory for data structures using
	115	.I calloc
	116	after 20 files have been opened.
	117	This confuses some programs which use their own memory allocators.
	118	An undocumented routine,
	119	.IR f_prealloc ,
	120	may be called to force immediate allocation of all internal memory
	121	except for buffers.