HP 3000 Manuals HP 3000 Manuals
HP C/iX Library Input and Output
The C language does not provide any direct facility to perform input or
output. Instead, C implementations usually provide a set of functions
that perform I/O. Care must be used when calling the I/O functions
because the compiler does not ensure that the arguments to the functions
are correct. Most errors in calls to I/O functions may not provide the
correct results and may cause addressing violations and abnormal
terminations.
HP C/iX provides two I/O facilities. You can call MPE intrinsics
directly or call a set of supplied C functions that provide an interface
that is transportable to other systems. Because most of the C functions
are built on top of MPE, they may not execute as quickly as direct MPE
calls. The added time in most cases is small and the resulting
portability is usually well worth the extra execution time.
[REV BEG]
You should use either HP C/iX I/O functions or MPE/iX intrinsics, but not
both, in the same program. Using HP C/iX I/O functions with MPE/iX
intrinsics to operate on the same file can result in unpredictable
program behavior. The HP C/iX I/O routines use data and file control
buffers that are different from the ones used by the MPE/iX I/O
intrinsics.[REV END]
[REV BEG]
HP C/iX I/O and POSIX I/O functions utilize a byte stream model. The
data is treated as a continuous stream of bytes. There are conceptually
no record boundaries.[REV END]
[REV BEG]
The HP C/iX I/O functions allow C programs to access any file type
supported by MPE. These functions emulate stream I/O when accessing MPE
(non-byte stream) files.[REV END]
The performance of stream emulation suffers when accessing
variable-length records with certain I/O functions. For example, the HP
C I/O function fseek enables the caller to position a file pointer to any
given byte number. In the case of files that are composed of fixed-sized
records, the positioning operation is direct because the address of the
record that contains the interesting byte can be calculated and the file
pointer can be positioned to it. If a file has variable-length records,
the fseek function still works, but the implementation requires the file
to be rewound and then all records are read until the required record is
reached.[REV BEG] The fseek function is much slower with variable-length
record MPE files than with fixed-length record MPE files.[REV END]
[REV BEG]
Basic Stream Usage
[REV END]
Using a stream is similar to using an MPE file. A stream is opened by
calling the C library function fopen(). The fopen function creates a
data structure that contains descriptive data about a stream and returns
a pointer to this structure. This pointer designates the stream in all
further transactions.
When you use the fopen function to open an existing file, the fixed
attributes of the file take precedence over the mode requested by
fopen(). In particular, an existing ASCII file is opened as a text
stream, and an existing binary file is opened as a binary stream,
regardless of the mode requested by fopen().
Three constant pointers that designate standard streams opened
automatically by the C startup routines can also be used in further
transactions. Refer to the section called "Standard Files" for details.
After a stream has been opened, you may read from it or write to it in
several ways. Reading or writing can be done on a character-by-character
basis using the inline macros getc and putc, or on a block-by-block basis
using functions such as fread or fwrite. The macros getchar and putchar
and the higher-level functions fgetc, fgets, fprintf, fputc, fputs,
fread, fscanf, fwrite, gets, printf, puts, and scanf use, or act as if
they use, getc and putc; they may be freely intermixed.
An open stream can also be controlled by functions such as fseek and
rewind. These functions allow you to position the stream position
indicator to an arbitrary byte.
When you are finished using a stream, the stream should be closed. This
may be accomplished by issuing a call to fclose, implicitly by calling
exit, or by returning from the main function. It is important to close
all files because the fclose function causes information that is buffered
in memory to be written out to the physical file. Calling an MPE
termination routine does not properly close open streams.
Stream Types
[REV BEG]
The HP C/iX library supports two[REV END] stream types: text and binary
streams. The stream type dictates how special characters are to be
processed and how records are to be padded. Streams created by the HP
C/iX library default to text streams.
Text Streams.
A text stream is an ordered sequence of characters composed into lines
with each line consisting of zero or more characters plus a terminating
newline (\n) character.
[REV BEG]
On MPE/iX, text streams are line-oriented fixed record length ASCII
files.[REV END] Text streams are usually the product of editor programs
and are read directly without any interpretation by other functions. The
newline character is not actually written to the file, but is used by the
HP C/iX I/O functions to indicate when a buffer is full of information
and should be posted to the file.
On input, newline characters are added to the records read from the file
to make it appear as if the newline character is actually in the file.
This is done to allow programs, such as EDITOR, to produce files that can
be read by C functions in a manner compatible with other systems. ASCII
files managed by MPE do not actually contain \n characters, but appear to
when read by C functions. Further, the type of record structure used in
the file has impact on what is seen when a file is read. Assume that
there is an ASCII MPE file with variable-length records. If the
following 5 bytes are written:
'A', 'B', 'C', 'D', '\n'
only 4 bytes are actually output to the MPE file. The record in the file
appears as:
ABCD
The \n is used by the C functions to indicate that a record should be
written, but the newline character is not actually written. When the
same record is read back in, the \n is added to the end of the buffer.
The result is that successive getc operations return the same five
characters originally written out:
'A', 'B', 'C', 'D', '\n'
If the same example is examined with an ASCII file composed of
fixed-length records, each of which is six characters in length, the
result is different. Assume the same five characters are written. When
the C I/O system encounters the \n, it gets ready to write out a record.
The record contains "ABCD" at this point. However, since the record is a
fixed-length record with a length of six characters, the two characters
after the 'D' are padded with spaces (040). The record written to the
MPE file is:
ABCD__
where _ indicates a space. As before, the \n triggers the write, but the
actual \n character is not written out.
When the record is read back into the program, the \n is restored at the
end of the record, but the I/O functions have no way of knowing whether
the trailing spaces are pad characters written by the MPE/iX file system,
or actual data characters written by a C program. This ambiguity is
resolved in one of two ways (described below), depending on whether
ANSI-conformant behavior has been requested.
The standard ANSI conformant interpretation, which is requested by
including LIBCANSI.LIB.SYS in the RL list when linking (as described in
chapter 1), is to discard all trailing spaces in fixed-length records
when reading text streams. In the example given above, the result is
that the following five characters are read back:
`A', `B', `C', `D', `\n'
However, for compatibility with previous releases of the HP C/iX library,
the default behavior is that trailing spaces in fixed-length records in
text files are not stripped. Thus, if the program in the example is not
linked with LIBCANSI, it reads the following seven characters:
`A', `B', `C', 'D', space, space, `\n'
Because of the special meaning of the \n character, in text streams, you
should avoid writing binary data to a text stream. If the binary data
happens to contain a byte with the same numeric value as the newline
character (ASCII code 10), the result is an unexpected record break.
Binary Streams.
Like text streams, binary streams are also ordered sequence of bytes.
Binary streams, however, transparently record data. No special attention
is given to \n characters or any other characters. No padding is
performed for binary streams.
If a \n character is written to a binary stream, it is actually written.
Binary streams return the same number of characters originally written
except in one special case.
[REV BEG]
On MPE/iX, if fopen() opens a binary stream it is a fixed-length record
format file. If the file is closed, the last record in the file, if
incomplete, is filled with trailing zeros. The end-of-file is located on
a record boundary, regardless of the last byte written to the file.
By default, if you are using POSIX on MPE/iX, fopen() creates a byte
stream file. If the file is closed, the last byte written is the
end-of-file.
[REV END]
File Descriptors
To perform I/O operations, you must associate a stream with a file or
device. For the unbuffered I/O operations (the ones in the standard I/O
library), you do this by declaring a pointer to a structure type called
FILE. The FILE structure, which is defined in <stdio.h>, contains several
fields to hold information about the pointer to the buffer, the file
descriptor, and the file access mode.
The FILE structures provide the operating system with bookkeeping
information, but your only means of access to the stream is the pointer
to the FILE structure (called a file pointer). The file pointer, which
you must declare in your program, holds the stream identifier returned by
the fopen function. You use the file pointer to read from, write to, or
close the stream.
For unbuffered functions, you must associate a file with a file
descriptor by using the open function. A file descriptor is a unique
integer that identifies a particular file. This file descriptor is also
contained in the FILE structure returned by fopen.
Standard Files.
There are three constant pointers defined in <stdio.h> that designate
standard C streams. These streams are automatically opened by the C
language startup routines. The standard stream designators are:
Table 2-1. Standard Stream Designators
-----------------------------------------------------------------
| | | |
| Stream | Function | Default |
| | | |
-----------------------------------------------------------------
| | | |
| stdin | Standard Input | $STDINX |
| | | |
-----------------------------------------------------------------
| | | |
| stdout | Standard Output | $STDLIST |
| | | |
-----------------------------------------------------------------
| | | |
| stderr | Standard Error | $STDLIST |
| | | |
-----------------------------------------------------------------
The stdin stream is opened for reading. Your program only receives data
from the stdin stream. It cannot write data to this stream. The stdin
stream defaults to the standard MPE file $STDINX. If you run your program
in interactive mode, the input device is normally a keyboard.
The stdout stream is opened for writing. Your program only outputs data
to the stdout stream. It cannot read data from this stream. The stdout
stream defaults to the standard MPE file $STDLIST. If you run your
program in an interactive mode, the output device is normally your
terminal.
The stderr stream is also opened for writing. Your program cannot read
data from this stream. Like stdout, this stream defaults to the standard
MPE file $STDLIST. For interactive programs, this file is normally your
terminal. The stderr stream is used to print error and warning messages
when an erroneous condition is detected in your program. The stderr
stream is unbuffered by default. An unbuffered stream transfers data to
its destination one byte at a time.
Reading from stdin in Interactive and Batch Modes
When reading from stdin in interactive mode using fgets, gets, fscanf,
scanf, or fread, the input text stream is not padded with trailing
blanks.
When reading from stdin in batch mode using fgets, gets, fscanf, scanf,
or fread, the input stream may or may not be padded with trailing blanks
before being terminated with a null character. Whether or not padding is
applied depends on the file type of the input batch stream file.
If the batch stream file is a variable record length ASCII file, no
padding is applied and reading from stdin in batch behaves the same as
reading in interactive mode.
If the batch stream file has fixed record lengths, the input records are
padded with trailing blanks. When reading from fixed record length batch
stream files, be sure to use large enough buffers to accommodate the
entire record, including the null character appended to the string by the
I/O system.
Whether using fixed or variable record length ASCII files, insert the EOD
command in the batch stream file between the embedded program data and
the next MPE/iX command. This prevents the program from accidentally
reading command lines from the file.
For example, given the following program
#include <stdio.h>
main (void)
{
char iobuff[81];
printf("\n Please enter your name:");
gets(iobuff);
printf("%s\n",iobuff);
}
a batch job to run this program is:
!JOB WALTER.JONES
!RUN ECHONAME
Walter Morgan
!EOD
!SHOWTIME
!EOJ
Restrictions
Due to the implementation of the HP C/iX library and the MPE/iX file
system, operations on certain types of files may be restricted. Refer to
appendix B, "Restrictions and Special Considerations," for more
information.