Libc-1353.11.2.tar.gz

[apple/libc.git] / stdio / FreeBSD / fopen.3

diff --git a/stdio/FreeBSD/fopen.3 b/stdio/FreeBSD/fopen.3
index 3bb0c0f8b5755d568ba43a1ff10c8b6406c51978..1edd25eb6fd76c51ce1862ba180d229849441c73 100644 (file)
--- a/stdio/FreeBSD/fopen.3
+++ b/stdio/FreeBSD/fopen.3
@@ -13,7 +13,7 @@
 .\" 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.
 .\" 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.
 .\"
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
 .\"


@@ -30,102 +30,102 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)fopen.3    8.1 (Berkeley) 6/4/93
 .\" 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
 .Dt FOPEN 3
 .Os
 .Sh NAME

-.Nm fdopen ,

 .Nm fopen ,
 .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 *
 .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 *
 .Ft FILE *

-.Fo fopen
-.Fa "const char *restrict filename"
-.Fa "const char *restrict mode"
-.Fc
+.Fn fdopen "int fildes" "const char *mode"

 .Ft FILE *
 .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
 .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
 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
 .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.
 The stream is positioned at the beginning of the file.

+Fail if the file does not exist.

 .It Dq Li w
 .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.
 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.
 .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.
 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
 .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
 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
 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
 .Pp
 Any created files will have mode

-.Pf \\*q Dv S_IRUSR
+.Do Dv S_IRUSR

 \&|
 .Dv S_IWUSR
 \&|
 \&|
 .Dv S_IWUSR
 \&|


@@ -135,20 +135,15 @@ Any created files will have mode
 \&|
 .Dv S_IROTH
 \&|
 \&|
 .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
 .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
 .Pp
 The
 .Fn fdopen


@@ -156,6 +151,14 @@ function associates a stream with the existing file descriptor,
 .Fa fildes .
 The mode
 of the stream must be compatible with the mode of the file descriptor.
 .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
 When the stream is closed via
 .Xr fclose 3 ,
 .Fa fildes


@@ -165,7 +168,7 @@ The
 .Fn freopen
 function
 opens the file whose name is the string pointed to by
 .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.
 and associates the stream pointed to by
 .Fa stream
 with it.


@@ -177,7 +180,7 @@ argument is used just as in the
 function.
 .Pp
 If the
 function.
 .Pp
 If the

-.Fa filename
+.Fa path

 argument is
 .Dv NULL ,
 .Fn freopen
 argument is
 .Dv NULL ,
 .Fn freopen


@@ -186,29 +189,12 @@ attempts to re-open the file associated with
 with a new mode.
 The new mode must be compatible with the mode that the stream was originally
 opened with:
 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
 .Pp
 The primary use of the
 .Fn freopen


@@ -218,12 +204,54 @@ standard text stream
 .Dv ( stderr , stdin ,
 or
 .Dv stdout ) .
 .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 ,
 .Sh RETURN VALUES
 Upon successful completion
 .Fn fopen ,
 .Fn fdopen ,

-and

 .Fn freopen
 .Fn freopen

+and
+.Fn fmemopen

 return a
 .Tn FILE
 pointer.
 return a
 .Tn FILE
 pointer.


@@ -241,16 +269,18 @@ argument
 to
 .Fn fopen ,
 .Fn fdopen ,
 to
 .Fn fopen ,
 .Fn fdopen ,

+.Fn freopen ,

 or
 or

-.Fn freopen
+.Fn fmemopen

 was invalid.
 .El
 .Pp
 The
 .Fn fopen ,
 was invalid.
 .El
 .Pp
 The
 .Fn fopen ,

-.Fn fdopen
-and
+.Fn fdopen ,

 .Fn freopen
 .Fn freopen

+and
+.Fn fmemopen

 functions
 may also fail and set
 .Va errno
 functions
 may also fail and set
 .Va errno


@@ -283,6 +313,15 @@ for any of the errors specified for the routines
 .Xr fclose 3
 and
 .Xr fflush 3 .
 .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 ,
 .Sh SEE ALSO
 .Xr open 2 ,
 .Xr fclose 3 ,


@@ -296,9 +335,26 @@ and
 .Fn freopen
 functions
 conform to
 .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
 .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.