.\" Chris Torek and the American National Standards Committee X3,
.\" on Information Processing Systems.
.\"
+.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
+.\" %%%LICENSE_END
.\"
.\" @(#)fopen.3 6.8 (Berkeley) 6/29/91
.\"
.\" Modified, aeb, 960421, 970806
.\" Modified, joey, aeb, 2002-01-03
.\"
-.TH FOPEN 3 2009-02-23 "GNU" "Linux Programmer's Manual"
+.TH FOPEN 3 2012-04-22 "GNU" "Linux Programmer's Manual"
.SH NAME
fopen, fdopen, freopen \- stream open functions
.SH SYNOPSIS
The argument
.I mode
points to a string beginning with one of the following sequences
-(Additional characters may follow these sequences.):
+(possibly followed by additional characters, as described below):
.TP
.B r
Open text file for reading.
conforming systems, including Linux.
(Other systems may treat text files and binary files differently,
and adding the \(aqb\(aq may be a good idea if you do I/O to a binary
-file and expect that your program may be ported to non-Unix
+file and expect that your program may be ported to non-UNIX
environments.)
.PP
See NOTES below for details of glibc extensions for
operation between write and read operations on such a stream.
This operation may be an apparent no-op
(as in \fIfseek(..., 0L, SEEK_CUR)\fP
-called for its synchronizing side effect.
+called for its synchronizing side effect).
.PP
Opening a file in append mode (\fBa\fP as the first character of
.IR mode )
causes all subsequent write operations to this stream to occur
-at end-of-file, as if preceded by an
+at end-of-file, as if preceded the call:
.nf
- fseek(stream,0,SEEK_END);
+ fseek(stream, 0, SEEK_END);
.fi
.PP
-call.
-.PP
The
.BR fdopen ()
function associates a stream with the existing file descriptor,
.BR freopen ()
function is to change the file associated with a standard text stream
.RI ( stderr ", " stdin ", or " stdout ).
-.SH "RETURN VALUE"
+.SH RETURN VALUE
Upon successful completion
.BR fopen (),
.BR fdopen ()
.I errno
for any of the errors specified for the routines
.BR open (2),
-.BR fclose (3)
+.BR fclose (3),
and
.BR fflush (3).
-.SH "CONFORMING TO"
+.SH CONFORMING TO
The
.BR fopen ()
and
.BR fdopen ()
function conforms to POSIX.1-1990.
.SH NOTES
-.SS Glibc Notes
+.SS Glibc notes
The GNU C library allows the following extensions for the string specified in
.IR mode :
.TP
Do not make the open operation,
or subsequent read and write operations,
thread cancellation points.
+This flag is ignored for
+.BR fdopen ().
.TP
.BR e " (since glibc 2.7)"
Open the file with the
See
.BR open (2)
for more information.
+This flag is ignored for
+.BR fdopen ().
.TP
.BR m " (since glibc 2.3)"
Attempt to access the file using
.\" As at glibc 2.4:
use of
.BR mmap (2)
-is only attempted for a file opened for reading.
+is attempted only for a file opened for reading.
.TP
.B x
.\" Since glibc 2.0?
+.\" FIXME . C11 specifies this flag
Open the file exclusively
(like the
.B O_EXCL
.BR EEXIST .
This flag is ignored for
.BR fdopen ().
-.\" FIXME document /,ccs= charset/
-.SH "SEE ALSO"
+.PP
+In addition to the above characters,
+.BR fopen ()
+and
+.BR freopen ()
+support the following syntax
+in
+.IR mode :
+
+.BI " ,ccs=" string
+
+The given
+.I string
+is taken as the name of a coded character set and
+the stream is marked as wide-oriented.
+Thereafter, internal conversion functions convert I/O
+to and from the character set
+.IR string .
+If the
+.BI ,ccs= string
+syntax is not specified,
+then the wide-orientation of the stream is
+determined by the first file operation.
+If that operation is a wide-character operation,
+the stream is marked wide-oriented,
+and functions to convert to the coded character set are loaded.
+.SH BUGS
+When parsing for individual flag characters in
+.IR mode
+(i.e., the characters preceding the "ccs" specification),
+the glibc implementation of
+.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12685
+.BR fopen ()
+and
+.BR freopen ()
+limits the number of characters examined in
+.I mode
+to 7 (or, in glibc versions before 2.14, to 6,
+which was not enough to include possible specifications such as "rb+cmxe").
+The current implementation of
+.BR fdopen ()
+parses at most 5 characters in
+.IR mode .
+.SH SEE ALSO
.BR open (2),
.BR fclose (3),
.BR fileno (3),
.BR fmemopen (3),
.BR fopencookie (3)
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.