.\" 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.
-.\" 4. Neither the name of the University nor the names of its contributors
+.\" 3. 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.
.\"
.\" @(#)fopen.3 8.1 (Berkeley) 6/4/93
-.\" $FreeBSD: src/lib/libc/stdio/fopen.3,v 1.21 2009/09/09 19:38:19 ed Exp $
+.\" $FreeBSD$
.\"
-.Dd January 26, 2003
+.Dd January 30, 2013
.Dt FOPEN 3
.Os
.Sh NAME
-.Nm fdopen ,
.Nm fopen ,
-.Nm freopen
+.Nm fdopen ,
+.Nm freopen ,
+.Nm fmemopen
.Nd stream open functions
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In stdio.h
.Ft FILE *
-.Fo fdopen
-.Fa "int fildes"
-.Fa "const char *mode"
-.Fc
+.Fn fopen "const char * restrict path" "const char * restrict mode"
.Ft FILE *
-.Fo fopen
-.Fa "const char *restrict filename"
-.Fa "const char *restrict mode"
-.Fc
+.Fn fdopen "int fildes" "const char *mode"
.Ft FILE *
-.Fo freopen
-.Fa "const char *restrict filename"
-.Fa "const char *restrict mode"
-.Fa "FILE *restrict stream"
-.Fc
+.Fn freopen "const char *path" "const char *mode" "FILE *stream"
+.Ft FILE *
+.Fn fmemopen "void *restrict *buf" "size_t size" "const char * restrict mode"
.Sh DESCRIPTION
The
.Fn fopen
function
opens the file whose name is the string pointed to by
-.Fa filename
+.Fa path
and associates a stream with it.
.Pp
The argument
.Fa mode
-points to a string beginning with one of the following
-sequences (Additional characters may follow these sequences.):
+points to a string beginning with one of the following letters:
.Bl -tag -width indent
.It Dq Li r
-Open text file for reading.
-The stream is positioned at the beginning of the file.
-.It Dq Li r+
-Open for reading and writing.
+Open for reading.
The stream is positioned at the beginning of the file.
+Fail if the file does not exist.
.It Dq Li w
-Truncate to zero length or create text file for writing.
-The stream is positioned at the beginning of the file.
-.It Dq Li w+
-Open for reading and writing.
-The file is created if it does not exist, otherwise it is truncated.
+Open for writing.
The stream is positioned at the beginning of the file.
+Create the file if it does not exist.
.It Dq Li a
Open for writing.
-The file is created if it does not exist.
-The stream is positioned at the end of the file.
-Subsequent writes to the file will always end up at the then current
-end of file, irrespective of any intervening
-.Xr fseek 3
-or similar.
-.It Dq Li a+
-Open for reading and writing.
-The file is created if it does not exist.
The stream is positioned at the end of the file.
Subsequent writes to the file will always end up at the then current
end of file, irrespective of any intervening
.Xr fseek 3
or similar.
+Create the file if it does not exist.
.El
.Pp
+An optional
+.Dq Li +
+following
+.Dq Li r ,
+.Dq Li w ,
+or
+.Dq Li a
+opens the file for both reading and writing.
+An optional
+.Dq Li x
+following
+.Dq Li w
+or
+.Dq Li w+
+causes the
+.Fn fopen
+call to fail if the file already exists.
+An optional
+.Dq Li e
+following the above
+causes the
+.Fn fopen
+call to set the
+.Dv FD_CLOEXEC
+flag on the underlying file descriptor.
+.Pp
The
.Fa mode
-string can also include the letter ``b'' either as last character or
-as a character between the characters in any of the two-character strings
-described above.
+string can also include the letter
+.Dq Li b
+after either the
+.Dq Li +
+or the first letter.
This is strictly for compatibility with
.St -isoC
-and has no effect; the ``b'' is ignored.
-.Pp
-Finally, as an extension to the standards (and thus may not be portable),
-.Fa mode
-string may end with the letter ``x'', which insists on creating a new file
-when used with ``w'' or ``a''.
-If
-.Fa path
-exists, then an error is returned (this is the equivalent of specifying
-.Dv O_EXCL
-with
-.Xr open 2 ) .
+and has effect only for
+.Fn fmemopen
+; otherwise
+.Dq Li b
+is ignored.
.Pp
Any created files will have mode
-.Pf \\*q Dv S_IRUSR
+.Do Dv S_IRUSR
\&|
.Dv S_IWUSR
\&|
\&|
.Dv S_IROTH
\&|
-.Dv S_IWOTH Ns \\*q
+.Dv S_IWOTH Dc
.Pq Li 0666 ,
as modified by the process'
umask value (see
.Xr umask 2 ) .
.Pp
-Reads and writes may be intermixed on read/write streams in any order,
-and do not require an intermediate seek as in previous versions of
-.Em stdio .
-This is not portable to other systems, however;
-.Tn ANSI C
-requires that
-a file positioning function intervene between output and input, unless
-an input operation encounters end-of-file.
+Reads and writes may be intermixed on read/write streams in any order; however,
+a file positioning function must be called when switching between output and
+input, unless an input operation encounters end-of-file.
.Pp
The
.Fn fdopen
.Fa fildes .
The mode
of the stream must be compatible with the mode of the file descriptor.
+The
+.Dq Li x
+mode option is ignored.
+If the
+.Dq Li e
+mode option is present, the
+.Dv FD_CLOEXEC
+flag is set, otherwise it remains unchanged.
When the stream is closed via
.Xr fclose 3 ,
.Fa fildes
.Fn freopen
function
opens the file whose name is the string pointed to by
-.Fa filename
+.Fa path
and associates the stream pointed to by
.Fa stream
with it.
function.
.Pp
If the
-.Fa filename
+.Fa path
argument is
.Dv NULL ,
.Fn freopen
with a new mode.
The new mode must be compatible with the mode that the stream was originally
opened with:
-.Bl -bullet -offset indent
-.It
-Streams originally opened with mode
-.Dq Li r
-can only be reopened with that same mode.
-.It
-Streams originally opened with mode
-.Dq Li a
-can be reopened with the same mode, or mode
-.Dq Li w .
-.It
-Streams originally opened with mode
-.Dq Li w
-can be reopened with the same mode, or mode
-.Dq Li a .
-.It
-Streams originally opened with mode
-.Dq Li r+ ,
-.Dq Li w+ ,
-or
-.Dq Li a+
-can be reopened with any mode.
-.El
+Streams open for reading can only be re-opened for reading,
+streams open for writing can only be re-opened for writing,
+and streams open for reading and writing can be re-opened in any mode.
+The
+.Dq Li x
+mode option is not meaningful in this context.
.Pp
The primary use of the
.Fn freopen
.Dv ( stderr , stdin ,
or
.Dv stdout ) .
+.Pp
+The
+.Fn fmemopen
+function
+associates the buffer given by the
+.Fa buf
+and
+.Fa size
+arguments with a stream.
+The
+.Fa buf
+argument is either a null pointer or a pointer to a buffer that
+is at least
+.Fa size
+bytes long.
+If a null pointer is specified as the
+.Fa buf
+argument,
+.Fn fmemopen
+allocates
+.Fa size
+bytes of memory, and this allocation is automatically freed when the stream is
+closed.
+If a non-null pointer is specified, the caller retains ownership of
+the buffer and is responsible for disposing of it after the stream has been
+closed.
+Buffers can be opened in text-mode (default) or binary-mode
+(if
+.Dq Li b
+is present in the second or third position of the
+.Fa mode
+argument). Buffers opened in text-mode make sure that writes are terminated with
+a NULL byte, if the last write hasn't filled up the whole buffer. Buffers
+opened in binary-mode never append a NULL byte.
+.Pp
+Input and output against the opened stream will be fully buffered, unless
+it refers to an interactive terminal device, or a different kind of buffering
+is specified in the environment.
+See
+.Xr setvbuf 3
+for additional details.
.Sh RETURN VALUES
Upon successful completion
.Fn fopen ,
.Fn fdopen ,
-and
.Fn freopen
+and
+.Fn fmemopen
return a
.Tn FILE
pointer.
to
.Fn fopen ,
.Fn fdopen ,
+.Fn freopen ,
or
-.Fn freopen
+.Fn fmemopen
was invalid.
.El
.Pp
The
.Fn fopen ,
-.Fn fdopen
-and
+.Fn fdopen ,
.Fn freopen
+and
+.Fn fmemopen
functions
may also fail and set
.Va errno
.Xr fclose 3
and
.Xr fflush 3 .
+.Pp
+The
+.Fn fmemopen
+function
+may also fail and set
+.Va errno
+if the
+.Fa size
+argument is 0.
.Sh SEE ALSO
.Xr open 2 ,
.Xr fclose 3 ,
.Fn freopen
functions
conform to
-.St -isoC .
+.St -isoC ,
+with the exception of the
+.Dq Li x
+mode option which conforms to
+.St -isoC-2011 .
The
.Fn fdopen
function
conforms to
.St -p1003.1-88 .
+The
+.Dq Li e
+mode option does not conform to any standard
+but is also supported by glibc.
+The
+.Fn fmemopen
+function
+conforms to
+.St -p1003.1-2008 .
+The
+.Dq Li b
+mode does not conform to any standard
+but is also supported by glibc.
projects / apple / libc.git / blobdiff