Import of man-pages 1.70man-pages-1.70

1 files changed, 236 insertions, 0 deletions

diff --git a/man3p/fopen.3p b/man3p/fopen.3p
new file mode 100644
index 000000000..18292c29e
--- /dev/null
+++ b/man3p/fopen.3p
@@ -0,0 +1,236 @@
+.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
+.TH "FOPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\" fopen 
+.SH NAME
+fopen \- open a stream
+.SH SYNOPSIS
+.LP
+\fB#include <stdio.h>
+.br
+.sp
+FILE *fopen(const char *restrict\fP \fIfilename\fP\fB, const char
+*restrict\fP \fImode\fP\fB);
+.br
+\fP
+.SH DESCRIPTION
+.LP
+The \fIfopen\fP() function shall open the file whose pathname is the
+string pointed to by \fIfilename\fP, and associates a
+stream with it.
+.LP
+The \fImode\fP argument points to a string. If the string is one of
+the following, the file shall be opened in the indicated
+mode. Otherwise, the behavior is undefined.
+.TP 7
+\fIr\fP\ or\ \fIrb\fP
+Open file for reading.
+.TP 7
+\fIw\fP\ or\ \fIwb\fP
+Truncate to zero length or create file for writing.
+.TP 7
+\fIa\fP\ or\ \fIab\fP
+Append; open or create file for writing at end-of-file.
+.TP 7
+\fIr+\fP\ or\ \fIrb+\fP\ or\ \fIr+b\fP
+Open file for update (reading and writing).
+.TP 7
+\fIw+\fP\ or\ \fIwb+\fP\ or\ \fIw+b\fP
+Truncate to zero length or create file for update.
+.TP 7
+\fIa+\fP\ or\ \fIab+\fP\ or\ \fIa+b\fP
+Append; open or create file for update, writing at end-of-file.
+.sp
+.LP
+The
+character \fB'b'\fP shall have no effect, but is allowed for ISO\ C
+standard conformance.  Opening a file with read mode (\fIr\fP as the
+first character in the \fImode\fP argument) shall
+fail if the file does not exist or cannot be read.
+.LP
+Opening a file with append mode (\fIa\fP as the first character in
+the \fImode\fP argument) shall cause all subsequent writes
+to the file to be forced to the then current end-of-file, regardless
+of intervening calls to \fIfseek\fP().
+.LP
+When a file is opened with update mode ( \fB'+'\fP as the second or
+third character in the \fImode\fP argument), both input
+and output may be performed on the associated stream. However, the
+application shall ensure that output is not directly followed by
+input without an intervening call to \fIfflush\fP() or to a file positioning
+function ( \fIfseek\fP(), \fIfsetpos\fP(), or \fIrewind\fP()), and
+input is not directly followed by output without an intervening call
+to a file
+positioning function, unless the input operation encounters end-of-file.
+.LP
+When opened, a stream is fully buffered if and only if it can be determined
+not to refer to an interactive device. The error and
+end-of-file indicators for the stream shall be cleared.
+.LP
+If
+\fImode\fP is \fIw\fP, \fIwb\fP, \fIa\fP, \fIab\fP, \fIw\fP+, \fIwb\fP+,
+\fIw\fP+\fIb\fP, \fIa\fP+, \fIab\fP+, or
+\fIa\fP+\fIb\fP, and the file did not previously exist, upon successful
+completion, the \fIfopen\fP() function shall mark for
+update the \fIst_atime\fP, \fIst_ctime\fP, and \fIst_mtime\fP fields
+of the file and the \fIst_ctime\fP and \fIst_mtime\fP
+fields of the parent directory.
+.LP
+If \fImode\fP is \fIw\fP, \fIwb\fP, \fIw\fP+, \fIwb\fP+, or \fIw\fP+\fIb\fP,
+and the file did previously exist, upon
+successful completion, \fIfopen\fP() shall mark for update the \fIst_ctime\fP
+and \fIst_mtime\fP fields of the file. The
+\fIfopen\fP() function shall allocate a file descriptor as \fIopen\fP()
+does. 
+.LP
+After a successful call to the \fIfopen\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, \fIfopen\fP() shall return a pointer to
+the object controlling the stream. Otherwise, a null
+pointer shall be returned,   \ and \fIerrno\fP shall be set to indicate
+the error. 
+.SH ERRORS
+.LP
+The \fIfopen\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 \fIfopen\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 the file 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 \fIfopen\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 EMFILE
+{FOPEN_MAX} streams are currently open in the calling process. 
+.TP 7
+.B EMFILE
+{STREAM_MAX} streams are currently open in the calling process. 
+.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 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 Opening a File
+.LP
+The following example tries to open the file named \fBfile\fP for
+reading. The \fIfopen\fP() function returns a file pointer
+that is used in subsequent \fIfgets\fP() and \fIfclose\fP() calls.
+If the program cannot open the file, it just ignores it.
+.sp
+.RS
+.nf
+
+\fB#include <stdio.h>
+\&...
+FILE *fp;
+\&...
+void rgrep(const char *file)
+{
+\&...
+    if ((fp = fopen(file, "r")) == NULL)
+        return;
+\&...
+}
+\fP
+.fi
+.RE
+.SH APPLICATION USAGE
+.LP
+None.
+.SH RATIONALE
+.LP
+None.
+.SH FUTURE DIRECTIONS
+.LP
+None.
+.SH SEE ALSO
+.LP
+\fIfclose\fP() , \fIfdopen\fP() , \fIfreopen\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 .