mirror of https://github.com/mkerrisk/man-pages
185 lines
5.4 KiB
Plaintext
185 lines
5.4 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "FREOPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" freopen
|
|
.SH NAME
|
|
freopen \- open a stream
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <stdio.h>
|
|
.br
|
|
.sp
|
|
FILE *freopen(const char *restrict\fP \fIfilename\fP\fB, const char
|
|
*restrict\fP \fImode\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ FILE *restrict\fP \fIstream\fP\fB);
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIfreopen\fP() function shall first attempt to flush the stream
|
|
and close any file descriptor associated with
|
|
\fIstream\fP. Failure to flush or close the file descriptor successfully
|
|
shall be ignored. The error and end-of-file indicators
|
|
for the stream shall be cleared.
|
|
.LP
|
|
The \fIfreopen\fP() function shall open the file whose pathname is
|
|
the string pointed to by \fIfilename\fP and associate the
|
|
stream pointed to by \fIstream\fP with it. The \fImode\fP argument
|
|
shall be used just as in \fIfopen\fP().
|
|
.LP
|
|
The original stream shall be closed regardless of whether the subsequent
|
|
open succeeds.
|
|
.LP
|
|
If \fIfilename\fP is a null pointer, the \fIfreopen\fP() function
|
|
shall attempt to change the mode of the stream to that
|
|
specified by \fImode\fP, as if the name of the file currently associated
|
|
with the stream had been used. It is
|
|
implementation-defined which changes of mode are permitted (if any),
|
|
and under what circumstances.
|
|
.LP
|
|
After a successful call to the \fIfreopen\fP() function, the orientation
|
|
of the stream shall be cleared, \ the encoding
|
|
rule shall be cleared, and the associated \fBmbstate_t\fP object
|
|
shall be set to describe an initial conversion state.
|
|
.LP
|
|
The
|
|
largest value that can be represented correctly in an object of type
|
|
\fBoff_t\fP shall be established as the offset maximum in the
|
|
open file description.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, \fIfreopen\fP() shall return the value
|
|
of \fIstream\fP. Otherwise, a null pointer shall be
|
|
returned, \ and \fIerrno\fP shall be set to indicate the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIfreopen\fP() function shall fail if:
|
|
.TP 7
|
|
.B EACCES
|
|
Search permission is denied on a component of the path prefix, or
|
|
the file exists and the permissions specified by \fImode\fP are
|
|
denied, or the file does not exist and write permission is denied
|
|
for the parent directory of the file to be created.
|
|
.TP 7
|
|
.B EINTR
|
|
A
|
|
signal was caught during \fIfreopen\fP().
|
|
.TP 7
|
|
.B EISDIR
|
|
The named file is a directory and \fImode\fP requires write access.
|
|
.TP 7
|
|
.B ELOOP
|
|
A
|
|
loop exists in symbolic links encountered during resolution of the
|
|
\fIpath\fP argument.
|
|
.TP 7
|
|
.B EMFILE
|
|
{OPEN_MAX} file descriptors are currently open in the calling process.
|
|
.TP 7
|
|
.B ENAMETOOLONG
|
|
.sp
|
|
The length of the \fIfilename\fP argument exceeds {PATH_MAX} or a
|
|
pathname component is longer than {NAME_MAX}.
|
|
.TP 7
|
|
.B ENFILE
|
|
The maximum allowable number of files is currently open in the system.
|
|
.TP 7
|
|
.B ENOENT
|
|
A
|
|
component of \fIfilename\fP does not name an existing file or \fIfilename\fP
|
|
is an empty string.
|
|
.TP 7
|
|
.B ENOSPC
|
|
The directory or file system that would contain the new file cannot
|
|
be expanded, the file does not exist, and it was to be created.
|
|
.TP 7
|
|
.B ENOTDIR
|
|
A
|
|
component of the path prefix is not a directory.
|
|
.TP 7
|
|
.B ENXIO
|
|
The named file is a character special or block special file, and the
|
|
device associated with this special file does not exist.
|
|
.TP 7
|
|
.B EOVERFLOW
|
|
The named file is a regular file and the size of the file cannot be
|
|
represented correctly in an object of type \fBoff_t\fP.
|
|
.TP 7
|
|
.B EROFS
|
|
The named file resides on a read-only file system and \fImode\fP requires
|
|
write access.
|
|
.sp
|
|
.LP
|
|
The \fIfreopen\fP() function may fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
The value of the \fImode\fP argument is not valid.
|
|
.TP 7
|
|
.B ELOOP
|
|
More than {SYMLOOP_MAX} symbolic links were encountered during resolution
|
|
of the \fIpath\fP argument.
|
|
.TP 7
|
|
.B ENAMETOOLONG
|
|
.sp
|
|
Pathname resolution of a symbolic link produced an intermediate result
|
|
whose length exceeds {PATH_MAX}.
|
|
.TP 7
|
|
.B ENOMEM
|
|
Insufficient storage space is available.
|
|
.TP 7
|
|
.B ENXIO
|
|
A
|
|
request was made of a nonexistent device, or the request was outside
|
|
the capabilities of the device.
|
|
.TP 7
|
|
.B ETXTBSY
|
|
The file is a pure procedure (shared text) file that is being executed
|
|
and \fImode\fP requires write access.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.SS Directing Standard Output to a File
|
|
.LP
|
|
The following example logs all standard output to the \fB/tmp/logfile\fP
|
|
file.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <stdio.h>
|
|
\&...
|
|
FILE *fp;
|
|
\&...
|
|
fp = freopen ("/tmp/logfile", "a+", stdout);
|
|
\&...
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
The \fIfreopen\fP() function is typically used to attach the preopened
|
|
\fIstreams\fP associated with \fIstdin\fP,
|
|
\fIstdout\fP, and \fIstderr\fP to other files.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIfclose\fP() , \fIfopen\fP() , \fIfdopen\fP()
|
|
, \fImbsinit\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<stdio.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|