iolib

UNIX版本6的源代码

.ds s \\s8
.ds S \\s0
.ds * \v'.2m'*\v'-.2m'
.tr ~.
.ds . \s14~\s0
.tr _\(ul
.de sn
.sp
.ft I
.ne 2
..
.de sN
.sp .5
.ft R
..
.TL
The Portable C Library (on \s-2UNIX\s0) *
.AU
M. E. Lesk
.AI
.MH
.SH
1. INTRODUCTION
.PP
The C language [1] now exists on three operating systems.
.FS
* This document is an abbreviated form of
``The Portable C Library'', by M. E. Lesk, describing only
the UNIX section of the library.
.FE
A set of library routines common to
\*sPDP\*S 11 \*sUNIX\*S, Honeywell 6000 \*sGCOS\*S,
and \*sIBM\*S 370 \*sOS\*S
has been provided to improve program portability.
This memorandum describes the UNIX implementation of
the portable routines.
.PP
The programs
defined here were chosen to follow the standard routines
available on \*sUNIX\*S, with alterations to improve transferability
to other computer systems.  It is expected that future C implementations
will try to support the basic library outlined in this document.
It provides character stream input and output on multiple files;
simple accessing of files by name; and some elementary
formatting and translating routines.
The remainder of this memorandum lists the portable and
non-portable library routines and explains some of the programming
aids available.
.PP
The I/O routines in the C library
fall into several classes.
Files are addressed through intermediate numbers called
.I
file-descriptors
.R
which are described in section 2.  Several default file-descriptors
are provided by the system; other aspects of the system
environment are explained in section 3.
.PP
Basic character-stream input and output involves the reading or writing of
files considered as streams of characters.
The C library
includes facilities for this, discussed
in section 4.
Higher-level character stream operations permit translation of
internal binary representations of numbers to and from
character representations, and formatting or unpacking of character
data.
These operations are performed with the subprograms in section 5.
Binary input and output routines permit data transmission
without the cost of translation to or from readable \*sASCII\*S character representations.
Such data transmission
should only be directed to files or tapes, and not to
printers or terminals.  As is usual with such routines, the
only simple guarantee that can be made to the programmer seeking
portability is that data written by a particular sequence of
binary writes, if read by the exactly matching sequence of binary reads,
will restore the previous contents of memory.
Other reads or writes have system-dependent effects.
See section 6 for a discussion of binary input and output.
Section 7 describes some further routines in the portable library.
These include a storage allocator and
some other control and conversion functions.
.SH
2. FILE DESCRIPTORS
.PP
Except for the standard input and output files, all files must
be explicitly opened before
any I/O is performed on them.
When files are opened for writing, they are created if not already present.
They must be closed when finished, although the normal
.I
cexit
.R
routine will take care of that.
When opened a disc file or device is associated with a file descriptor, an integer
between 0 and 9.
This file descriptor is used for further I/O to the file.
.PP
Initially you are given three file descriptors by the system: 0, 1, and 2.
File 0 is the standard input; it is normally the teletype
in time-sharing or input data cards in batch.
File 1 is the standard output; it is normally the
teletype in time-sharing or the line printer in batch.
File 2 is the error file; it is an output file, normally the same
as file 1, except that when file 1 is diverted via a command
line '>' operator, file 2 remains attached to the
original destination, usually the terminal.
It is used for error message output.
These popular \*sUNIX\*S conventions are considered part
of the C library specification.
By closing 0 or 1, the default input or output may be re-directed;
this can also be done on the command line by
.ft I
>file
.ft P
for output or
.ft I
<file
.ft P
for input.
.PP
Associated with the portable library
are two external integers,
named
.I
cin
.R
and
.I
cout.
.R
These are respectively the numbers of the
standard input unit and standard output unit.
Initially 0 and 1 are used, but you may redefine
them at any time.
These cells are used by the routines
.I
getchar,
putchar,
gets,
.R
and
.I
puts
.R
to select their I-O unit number.
.SH
3. THE C ENVIRONMENT
.PP
The C language is almost exactly the same on all machines,
except for essential machine differences such as word
length and number of characters per word. 
On \*sUNIX\*S
\*sASCII\*S character code is used.
Characters range from \(mi128 to +127 in numeric value,
there is sign extension when characters are assigned to integers,
and right shifts are arithmetic.
The ``first'' character in a word is stored in the right half word.
.PP
More serious problems of compatibility are caused by the loaders
on the different operating systems.
.PP
\*sUNIX\*S permits external names to be in
upper and lower case,
up to seven characters long.
There may be multiple external definitions (uninitialized) of
the same name.
.PP
The C alphabet for identifier names includes
the upper and lower case letters, the digits, and the underline.
It is not possible for C programs to communicate with
\*sFORTRAN\*S programs.
.SH
4. BASIC CHARACTER STREAM ROUTINES
.PP
These routines transfer streams of characters in and out of
C programs.  Interpretation of the characters is left to
the user.
Facilities for interpreting numerical strings are presented in section
5; and routines to transfer binary data to and from files or devices
are discussed in section 6.
In the following routine descriptions, the optional
argument
.ft I
fd
.ft P
represents a file-descriptor; if not present, it is taken
to be 0 for input and 1 for output.  When your program
starts, remember that these are associated with the ``standard''
input and output files.
.sn
COPEN (filename, type)
.sN
\fICopen\fR initiates activity on a file; if necessary it will
create the file too.
Up to 10 files may be open at one time.
When called as described here,
.ft I
copen
.ft R
returns a filedescriptor for a character stream file.
Values less than zero returned by
.I
copen
.R
indicate an error trying to open the file.
Other calls to
.ft I
copen
.ft R
are described in sections 6 and 7.
.sp 3p
Arguments :
.sp 3p
.ft I
Filename:
.ft P
a string representing a file name, according to the
local operating system conventions.
All accept a string of letters and digits as a legal file name,
although leading digits are not recommended on \*sGCOS\*S.
.br
.ft I
Type:
.ft R
a character `r', `w', or `a' meaning read, write, or append.
Note that the type is a single character, whereas the
file name must be a string.
.sn
CGETC ( fd )
.sN
.ft I
Cgetc
.ft R
returns the next character from the input unit associated with \fIfd\fR. 
On end of file \fIcgetc\fR returns `\\0'.
To signal end of file from the teletype,
type the special symbol appropriate to \*sUNIX\*S:
EOT (control-D)
.sn
CPUTC (ch , fd )
.sN
.ft I
Cputc
.ft R
writes a character onto the given output unit.
.ft I
Cputc
.ft R
returns as its value the character written.
.PP
Output for disk files is buffered
in 512 character units, irrespective
of newlines;
teletype output goes character by character
.sn
CCLOSE (fd)
.sN
Activity on file
.ft I
fd
.ft R
is terminated and
any output buffers are emptied.
You usually don't have to call
.ft I
cclose; cexit
.ft R
will
do it for you on all open files.
However, to write some data
on a file and then read it back in, the correct sequence is:
.DS
fd = copen (``file'', `w');
write on fd ...
cclose (fd);
fd = copen(``file'', `r');
read from fd ...
.DE
.sn
CFLUSH (fn)
.sN
To get buffer flushing, but retain the ability to write more
on the file, you may call this routine.
.PP
Normally, output intended
for the teletype is not buffered
and this call is not needed.
.sn
CEXIT ([errcode])
.sN
.ft I
Cexit
.ft R
closes all files and then terminates execution.
If a non-zero argument is given, this is assumed to be
an error indication or other returned value to be signalled
to the operating system.
.PP
.I
Cexit
.R
.B
must
.R
be called explicitly; a return
from the main program is not
adequate.
.sn
CEOF (fd)
.sN
.ft I
Ceof
.ft R
returns nonzero when end of file has been reached on input unit \fIfd.\fR
.sn
GETCHAR ()
.sN
.ft I
Getchar
.ft R
is a special case of \fIcgetc;\fR it reads
one character from the standard input unit.
.ft I
Getchar (\|)
.ft R
is defined as
.ft I
cgetc (cin);
.ft R
it should not have an argument.
.sn
PUTCHAR (ch)
.sN
.ft I
Putchar (ch)
.ft R
is the same as
.ft I
cputc (ch, cout);
.ft R
it writes one character on the standard output.
.sn
GETS (s)
.sN
.ft I
Gets
.ft R
reads everything up to the next newline into the
string pointed to by \fIs.\fR  If the last character read
from this input unit was newline, then \fIgets\fR reads
the next line, which on \*sGCOS\*S and \*sIBM\*S corresponds exactly
to a logical record.
The terminating newline is replaced by `\\0'.
The value of \fIgets\fR is \fIs,\fR or 0 if end of file.
.sn
PUTS (s)
.sN
Copies the string \fIs\fR onto the standard output unit. 
The terminating `\\0' is replaced by a newline character.
The value of
.I
puts
.R
is
.I
s.
.R
.sn
UNGETC (ch , fd)
.sN
.ft I
Ungetc
.ft R
pushes back its character argument to the unit
.ft I
fd,
.ft R
which must be open for input.
After
.ft I
ungetc (`a', fd); ungetc (`b', fd);
.ft R
the next two characters
to be read from \fIfd\fR will be `b' and then `a'.
Up to 100 characters may be pushed back on each file.
This subroutine permits a program to read past the end
of its input, and then restore it for the next routine to read.
It is impossible to change an external file with
.ft I
ungetc;
.ft R
its purpose is only for internal communications, most particularly
.ft I
scanf,
.ft R
which is described in section 5.
Note that
.ft I
scanf
.ft R
actually requires only one character
of ``unget'' capability; thus it is possible that
future implementors may change the specification of the
.ft I
ungetc
.ft R
routine.
.SH
5. HIGH-LEVEL CHARACTER STREAM ROUTINES
.PP
These two routines,
.ft I
printf
.ft R
for output and
.ft I
scanf
.ft R
for input, permit simple translation to and from character
representations of numerical quantities.
They also allow generation or interpretation of formatted
lines.
.sn
PRINTF (\|[fd, ] control-string, arg1, arg2, ...)
.sp .5
PRINTF (\|[\(mi1, output-string, ] control-string, arg1, arg2, ...)
.sN
.ft I
Printf
.ft R
converts, formats, and prints its arguments under control of the
control string.
The control string contains two types of objects: plain characters,
which are simply copied to the output stream, and conversion
specifications, each of which causes conversion and printing of the
next successive argument to \fIprintf\fR.
.sp
Each conversion specification is introduced by the character `%'.
Following the `%', there may be:
.in 5
\(em an optional minus sign `\(mi' which specifies left adjustment of the
converted argument in the indicated field;
.sp 3p
\(em an optional digit string specifying a minimum field width; if the converted
argument has fewer characters than the field width it will be padded
on the left (or right, if the left
adjustment indicator has been given) to make up the field width;
the padding character is blank normally and zero if the field
width was specified with a leading zero
(note that this does not imply an octal field width);
.sp 3p
\(em an optional period `.' which serves to separate the field width
from the next digit string;
.sp 3p
\(em an optional digit string (the precision) which specifies the maximum
number of characters to be printed from a string,
or the number of digits to be printed to the right
of the decimal point of a floating or double number.
.sp 3p
\(em an optional length modifier \(fml\(fm which indicates that the corresponding
data item is a
.I
long
.R
rather than an
.I
int.
.R
.sp 3p
\(em a character which indicates the type of conversion to be applied.
.in 0
.sp
The conversion characters and their meanings are:
.in 5
.sp 5p
.ti -0.2i
\fBd\fR	The argument is converted to decimal notation.
.sp 3p
.ti -0.2i
\fBo\fR	The argument is converted to octal notation.
.sp 3p
.ti -0.2i
\fBx\fR	The argument is converted to hexadecimal notation.
.sp 3p
.ti -0.2i
\fBu\fR	The argument is converted to unsigned decimal notation.
This is only implemented (or useful) on \*sUNIX\*S.
.sp 3p
.ti -0.2i
\fBc\fR	The argument is taken to be a single character.
.sp 3p
.ti -0.2i
\fBs\fR	The argument is taken to be a string and characters from the
string are printed until a null character is reached or until the
number of characters indicated by the precision specification
is exhausted.
.sp 3p
.ti -0.2i
\fBe\fR	The argument is taken to be a float or double
and converted to decimal notation of the form
.ft I
[\(mi]\|m.nnnnnnE\|[\(mi]\|xx
.ft R
where the length of the string of \fIn\fP's is specified by
the precision.
The default precision is 6 and the maximum is 22.
.sp 3p
.ti -0.2i
\fBf\fR	The argument is taken to be a float or double and
converted to decimal notation of the
form
.ft I
[\(mi]mmm.nnnnn
.ft R
where the length of the string of
\fIn\fR's is specified by
the precision.  The default precision is 6 and the maximum
is 22.
Note that the precision does not determine
the number of significant digits printed in \fBf\fR format.
.in 0
.sp 3p
If no recognizable conversion character appears after the `%', that character
is printed; thus `%' may be printed by use of the string ``%%''.
.PP
As an example of \fIprintf,\fR the following program fragment
.DS
.I
int i, j; float x; char \**s;
i = 35; j=2; x= 1.732; s = ``ritchie'';
printf (``%d %f %s\\n'', i, x, s);
printf (``%o, %4d or %\(mi4d%5.5s\\n'', i, j, j, s);
.R
.DE
would print
.DS
.I
.cs I 24
35 1.732000 ritchie
043,    2 or 2   ritch
.cs I
.R
.DE
.PP
If \fIfd\fR is not specified, output is to unit
.I
cout.
.R