HP 3000 Manuals HP 3000 Manuals
freopen
Closes and reopens a stream.
Syntax
#include <stdio.h>
FILE *freopen (const char *fname, const char *type,
FILE *stream);
Parameters
fname A pointer to a character string that contains the name of
the file to be opened.
type A pointer to a character string defining the mode of the
file open.
stream A pointer to an open stream.
Return Values
x If successful, a pointer to the FILE structure associated
with the stream.
NULL The file open operation failed.
Description
The freopen function substitutes the named file in place of the open
stream. The original stream is closed, regardless of whether the open
succeeds (close errors are ignored). This function returns a pointer to
new stream.
This function is typically used to attach the preopened streams
associated with stdin, stdout and stderr to other files.
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. fseek() may 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 type 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, freopen() parses type
and ignores all cases where b is specified. An MPE byte stream
format file is opened and a binary stream is associated with it.
In addition, all other type 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 type string.
Spaces can be used in the type string to improve the readability of the
file's open type. Notice that the case of the option is important. An
uppercase B is different from a lowercase b.
These options are the same options that are used by the fopen() function.
For a detailed description of these options, refer to the description of
fopen().
Bln The Bl option specifies the blocking factor to use
if this call to freopen() 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 accepts
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 affect 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 is 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 freopen() 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 Intrinsics
Reference Manual under the FOPEN specification.
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. The default for text and binary
streams is 4095 records. The default for byte
streams is 2 gigabytes.
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 not to 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. This
option is mutually exclusive with the Bs option. If
the V or Bs options are not specified, then the file
is created with an MPE fixed-length record
format.[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/iX Intrinsics Reference Manual under the FOPEN
intrinsic description.
The following example creates or opens a stream associated with a fixed
record ASCII file for writing with 80-byte records and a file size of
1000 records:
#include<stdio.h>
FILE *stream;
stream = freopen("filename","w R80 S1000",stdout);
See Also
fclose(), fopen(), fflush(), ANSI C 4.9.5.4, POSIX.1 8.1