HP 3000 Manuals HP 3000 Manuals
fopen
Opens a stream.
Syntax
#include <stdio.h>
FILE *fopen (const char *fname, const char *mode);
Parameters
fname A pointer to a character string containing the name of the
file.
mode A pointer to a character string defining the mode of the
file open.
Return Values
x If successful, a pointer to the FILE structure associated
with the stream.
NULL The file open operation failed.
Description
The fopen function opens the file named by fname and associates a stream
with it. This function returns a pointer to the FILE structure
associated with the stream.
Opening a file in read mode fails if the file does not exist or cannot be
read.
When a file is opened for update, both input and output may be done on
the resulting stream. Do not directly follow output with input without
an intervening call to fflush() or to a file positioning function
(fseek(), fsetpos(), or rewind()). Do not directly follow input with
output without an intervening call to a file positioning function unless
the input operation encounters end-of-file.
When a file is opened for appending, it is impossible to overwrite
information already in the file. The fseek function can be used to
reposition the file pointer to any position in the file, but when output
is written to the file, the current file pointer is disregarded. All
output is written at the end of the file and the file pointer is
repositioned at the end of the output. When opening a binary file the
file position indicator may, in some cases, be positioned beyond the last
data written because of blank or null padding.
When opened, a stream is fully buffered only if it can be determined not
to refer to an interactive device. The error and end-of-file indicators
for a stream are cleared.
The mode parameter points to a character string beginning with one of the
following sequences:
r Open or create text stream for reading.
w Open or create text stream for writing. Truncate to zero
length.
a Open or create text stream in append mode. All writes
are at end-of-file.
rb Open or create binary stream for reading.
wb Open or create binary stream for writing. Truncate to
zero length.
ab Open or create binary stream in append mode. All writes
are at end-of-file.
r+ Open or create text stream for update (reading and
writing).
w+ Open or create text stream for update. Truncate to zero
length.
a+ Open or create text stream for append update (read
anywhere but all writes at end-of-file).
r+b or rb+ Open or create binary stream for update (reading and
writing).
w+b or wb+ Open or create binary stream for update. Truncate to
zero length.
a+b or ab+ Open or create binary stream for append update (reading
anywhere but all writes to end-of-file).
[REV BEG]
NOTE If you are linking with the POSIX/iX library, the fopen function
only creates or opens byte stream files. Attempting to open any
other file type results in an error.
When fopen() parses mode, all cases of b are ignored in the
standard options, and an MPE byte stream format file is opened and
a binary stream is associated with it. In addition, all other mode
options specified below are invalid.
[REV END]
If you are linking with the HP C/iX library, there are several
enhancements that provide greater control in the MPE file environment.
These options should follow the standard options in the mode string.
Spaces may be used in the mode string to improve the readability of the
file's open mode. Notice that the case of the option is important. An
upper case B is different from a lower case b.
Bln The Bl option specifies the blocking factor to use if
this call to fopen() creates the file. The option
character is followed by an integer that indicates
the blocking factor. If the Bl option is not
specified, then the default is one record per block.
[REV BEG]
Bs If the Bs option is specified, the file is opened or
created as a byte stream file. This is the only
required option for opening byte stream files. The
maximum file size for a byte stream file is two
gigabytes. If specified, the Rn option is ignored.
The Sn option can be used to reset the file size.
This option is mutually exclusive with the V option.
If the Bs or V options are not specified, the file is
created with an MPE fixed-length record format.[REV
END]
Bun The Bu option specifies the number of buffers to be
allocated to this file. If the Bu option is not
specified, the default is 2.
C If the C option is specified, then the file will
accept carriage control information. The default is
to not have carriage control.
Dfn The Df option specifies the final disposition of the
file after the file is closed. The affect of each
value of n is defined as follows:
--------------------------------------
| | |
| 0 | Don't change the |
| | disposition. |
| | |
--------------------------------------
| | |
| 1 | Save the file as a |
| | permanent file. |
| | |
--------------------------------------
| | |
| 2 | Save the file as a |
| | temporary file. |
| | |
--------------------------------------
| | |
| 3 | Don't rewind on close. |
| | |
--------------------------------------
| | |
| 4 | Purge the file on close. |
| | |
--------------------------------------
If the Df option is not specified and the file is a
new file, then the default is to save the file as a
permanent file. If the file is old, the default is
not to change the disposition.
Dsn The Ds option specifies the disk space disposition of the file
after the file is closed for fixed, undefined, and variable
format files. The effect of each value of n is defined as
follows:
-----------------------------------------------
| | |
| 0 | Don't return any disk space |
| | allocated beyond the end-of-file |
| | indicator. |
| | |
-----------------------------------------------
| | |
| 1 | Return to the system any disk |
| | space allocated beyond the |
| | end-of-file indicator. The EOF |
| | becomes the file limit. No |
| | records may be added to the file |
| | beyond this new limit. |
| | |
-----------------------------------------------
| | |
| 2 | Return to the system any disk |
| | space allocated beyond the |
| | end-of-file indicator, but do not |
| | set the file limit to EOF, and |
| | allow records to be added to the |
| | file up to the file limit. |
| | |
-----------------------------------------------
If the Ds option is not specified, the default is not to return
any disk space allocated beyond the end-of-file indicator.
En The E option specifies the maximum number of extents that can be
allocated to the file.
The maximum value is 32. The default value, if the E option is
not specified, is 8 extents.
Fn The F option indicates the value used as the file code if this
call to fopen() creates the file. If the F option is not
specified, the file code is zero.
L If specified, the L option indicates that dynamic locking should
be allowed on this file.
Mn The M option controls multi-access. The option character is
followed by an integer that indicates the level of multi-access
for this open request. The levels are specified in the MPE/iX
Intrinsics Reference Manual under the FOPEN intrinsic
description.
Q If the Q option is specified, file equations are disallowed. The
default is to allow file equations.
Rn The R option specifies the size of the record if the file is
created by this open request. If the V option is also used, this
option specifies the maximum size of the variable-sized records.
The option letter is followed by a decimal number that is equal
to the number of bytes in the record size. Notice that the
number must be positive. A byte count is always specified. The
default for text and binary streams is 256 bytes. The default
for byte streams is 1 byte.
Sn The S option specifies the maximum size of the file. The value
of n is the maximum size of the file in records for text and
binary streams, and in bytes for byte streams. Notice that if
the S parameter is not specified, the default is 4095.
Te If the Te option is specified, the file is saved in the temporary
file domain. If the Te option is not specified and the file is a
new file, the default is to save the file as a permanent file.
If the file is old, the default is to not change the disposition.
Tm If the Tm option is specified, disk read functions trim editor
line numbers, if they exist, and trailing blanks from each record
of an ASCII fixed record length file before returning file data
to the reader. This option is used on files opened with read
only access. Random access to file data using fseek() and
lseek() is not permitted. The default is to not trim editor line
numbers and blanks.
Un If the U option is specified, the file is created with n
user-label records. If this option is not specified, the default
is no user-label records.
[REV BEG]
V If the V option is specified, the file is created with an MPE
variable-length record format. If the V or Bs options are not
specified, then the file is created with an MPE fixed-length
record format. This option is mutually exclusive with the Bs
option.
[REV END]
Xn The X option controls exclusive access ability for the file. The
option character is followed by an integer that indicates the
level of exclusivity for this open request. The levels are
specified in the MPE Intrinsics Reference Manual under the FOPEN
specification.
The following example creates or opens a fixed record binary file for
writing with 256 byte records, a file size of 1000 records, and a file
code of 1030:
#include <stdio.h>
FILE *stream;
stream = fopen("filename","wb R256 S1000 F1030");
See Also
fclose(), freopen(), fflush(), ANSI C 4.9.5.3, POSIX.1 8.1