|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH FDOPEN "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
fdopen
|
|
Packit |
7cfc04 |
\(em associate a stream with a file descriptor
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
#include <stdio.h>
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
FILE *fdopen(int \fIfildes\fP, const char *\fImode\fP);
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIfdopen\fR()
|
|
Packit |
7cfc04 |
function shall associate a stream with a file descriptor.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR mode
|
|
Packit |
7cfc04 |
argument is a character string having one of the following values:
|
|
Packit |
7cfc04 |
.IP "\fIr\fP\ or\ \fIrb\fP" 14
|
|
Packit |
7cfc04 |
Open a file for reading.
|
|
Packit |
7cfc04 |
.IP "\fIw\fP\ or\ \fIwb\fP" 14
|
|
Packit |
7cfc04 |
Open a file for writing.
|
|
Packit |
7cfc04 |
.IP "\fIa\fP\ or\ \fIab\fP" 14
|
|
Packit |
7cfc04 |
Open a file for writing at end-of-file.
|
|
Packit |
7cfc04 |
.IP "\fIr\fP+\ or\ \fIrb\fP+\ or\ \fIr\fP+\fIb\fP" 14
|
|
Packit |
7cfc04 |
Open a file for update (reading and writing).
|
|
Packit |
7cfc04 |
.IP "\fIw\fP+\ or\ \fIwb\fP+\ or\ \fIw\fP+\fIb\fP" 14
|
|
Packit |
7cfc04 |
Open a file for update (reading and writing).
|
|
Packit |
7cfc04 |
.IP "\fIa\fP+\ or\ \fIab\fP+\ or\ \fIa\fP+\fIb\fP" 14
|
|
Packit |
7cfc04 |
Open a file for update (reading and writing) at end-of-file.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The meaning of these flags is exactly as specified in
|
|
Packit |
7cfc04 |
\fIfopen\fR(),
|
|
Packit |
7cfc04 |
except that modes beginning with
|
|
Packit |
7cfc04 |
.IR w
|
|
Packit |
7cfc04 |
shall not cause truncation of the file.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Additional values for the
|
|
Packit |
7cfc04 |
.IR mode
|
|
Packit |
7cfc04 |
argument may be supported by an implementation.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The application shall ensure that the mode of the stream as expressed
|
|
Packit |
7cfc04 |
by the
|
|
Packit |
7cfc04 |
.IR mode
|
|
Packit |
7cfc04 |
argument is allowed by the file access mode of the open file
|
|
Packit |
7cfc04 |
description to which
|
|
Packit |
7cfc04 |
.IR fildes
|
|
Packit |
7cfc04 |
refers. The file position indicator associated with the new stream is
|
|
Packit |
7cfc04 |
set to the position indicated by the file offset associated with the
|
|
Packit |
7cfc04 |
file descriptor.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The error and end-of-file indicators for the stream shall be cleared.
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIfdopen\fR()
|
|
Packit |
7cfc04 |
function may cause the last data access timestamp of the underlying
|
|
Packit |
7cfc04 |
file to be marked for update.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.IR fildes
|
|
Packit |
7cfc04 |
refers to a shared memory object, the result of the
|
|
Packit |
7cfc04 |
\fIfdopen\fR()
|
|
Packit |
7cfc04 |
function is unspecified.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.IR fildes
|
|
Packit |
7cfc04 |
refers to a typed memory object, the result of the
|
|
Packit |
7cfc04 |
\fIfdopen\fR()
|
|
Packit |
7cfc04 |
function is unspecified.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIfdopen\fR()
|
|
Packit |
7cfc04 |
function shall preserve the offset maximum previously set for the
|
|
Packit |
7cfc04 |
open file description corresponding to
|
|
Packit |
7cfc04 |
.IR fildes .
|
|
Packit |
7cfc04 |
.SH "RETURN VALUE"
|
|
Packit |
7cfc04 |
Upon successful completion,
|
|
Packit |
7cfc04 |
\fIfdopen\fR()
|
|
Packit |
7cfc04 |
shall return a pointer to a stream; otherwise, a null pointer shall be
|
|
Packit |
7cfc04 |
returned and
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
set to indicate the error.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIfdopen\fR()
|
|
Packit |
7cfc04 |
function shall fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EMFILE
|
|
Packit |
7cfc04 |
{STREAM_MAX}
|
|
Packit |
7cfc04 |
streams are currently open in the calling process.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIfdopen\fR()
|
|
Packit |
7cfc04 |
function may fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EBADF
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR fildes
|
|
Packit |
7cfc04 |
argument is not a valid file descriptor.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EINVAL
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR mode
|
|
Packit |
7cfc04 |
argument is not a valid mode.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EMFILE
|
|
Packit |
7cfc04 |
{FOPEN_MAX}
|
|
Packit |
7cfc04 |
streams are currently open in the calling process.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENOMEM
|
|
Packit |
7cfc04 |
Insufficient space to allocate a buffer.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH EXAMPLES
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
File descriptors are obtained from calls like
|
|
Packit |
7cfc04 |
\fIopen\fR(),
|
|
Packit |
7cfc04 |
\fIdup\fR(),
|
|
Packit |
7cfc04 |
\fIcreat\fR(),
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
\fIpipe\fR(),
|
|
Packit |
7cfc04 |
which open files but do not return streams.
|
|
Packit |
7cfc04 |
.SH RATIONALE
|
|
Packit |
7cfc04 |
The file descriptor may have been obtained from
|
|
Packit |
7cfc04 |
\fIopen\fR(),
|
|
Packit |
7cfc04 |
\fIcreat\fR(),
|
|
Packit |
7cfc04 |
\fIpipe\fR(),
|
|
Packit |
7cfc04 |
\fIdup\fR(),
|
|
Packit |
7cfc04 |
\fIfcntl\fR(),
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
\fIsocket\fR();
|
|
Packit |
7cfc04 |
inherited through
|
|
Packit |
7cfc04 |
\fIfork\fR(),
|
|
Packit |
7cfc04 |
\fIposix_spawn\fR(),
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.IR exec ;
|
|
Packit |
7cfc04 |
or perhaps obtained by other means.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The meanings of the
|
|
Packit |
7cfc04 |
.IR mode
|
|
Packit |
7cfc04 |
arguments of
|
|
Packit |
7cfc04 |
\fIfdopen\fR()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
\fIfopen\fR()
|
|
Packit |
7cfc04 |
differ. With
|
|
Packit |
7cfc04 |
\fIfdopen\fR(),
|
|
Packit |
7cfc04 |
open for write (\fIw\fP or \fIw+\fP) does not truncate, and append
|
|
Packit |
7cfc04 |
(\fIa\fP or \fIa+\fP) cannot create for writing. The
|
|
Packit |
7cfc04 |
.IR mode
|
|
Packit |
7cfc04 |
argument formats that include a \fIb\fP are allowed for consistency
|
|
Packit |
7cfc04 |
with the ISO\ C standard function
|
|
Packit |
7cfc04 |
\fIfopen\fR().
|
|
Packit |
7cfc04 |
The \fIb\fP has no effect on the resulting stream. Although not
|
|
Packit |
7cfc04 |
explicitly required by this volume of POSIX.1\(hy2008, a good implementation of append (\fIa\fP)
|
|
Packit |
7cfc04 |
mode would cause the O_APPEND flag to be set.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "Section 2.5.1" ", " "Interaction of File Descriptors and Standard I/O Streams",
|
|
Packit |
7cfc04 |
.IR "\fIfclose\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIfmemopen\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIfopen\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIopen\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIopen_memstream\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIposix_spawn\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIsocket\fR\^(\|)"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "\fB<stdio.h>\fP"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|