.	C manual - I/O nroff with cdoc0
.HI 2
.ce
C Manual - Input/Output
.ce
Edited by R.P.A. Collinson
.ce
Document No: DOC/UNIX.K3.10/2
.sp 5
.ce
Contents
.in +20
.SC 1 Introduction
.SC 2 "The Portable C Library by M.E. Lesk"
.SC 3 "Bell Lab I/O routines"
.br
atof, atoi, ecvt, fcvt, getc, getchar, printf, putc, putchar
.SC 4 "I/O System calls"
.br
close, creat, dup, open, read, seek, write
.SC 5 "File Handling calls and routines"
.br
chdir, chmod, fstat, gtty, link, stat, stty, ttyn, unlink
.in -20
.sp 5
.so unixlicense
.SH 1 "Introduction"
.NF
.PG
This manual gives details for C programmers of the various levels of I/O routines
available to them. It assumes a basic knowledge of the Unix operating system
and the C language. There are two UKC documents which are relevant: DOC/UNIX.K1/1 -
"Unix Introduction"; and DOC/UNIX.K3.10/1 - "C Manual - Language".
.Pg
The majority of this manual is derived from documentation originally supplied
by Bell Labs, consisting of: a paper entitled "The Portable C Library" by
M.E. Lesk and selected pages from the Unix Programmers Manual.
.SB "Basic I/O Philosophy"
.PG
Unix is based around a file system and every construction in the file
system (ordinary file, directory or device) can be treated as a file which is
opened and closed, read and written by user programs.
.PG
When a file is opened by a program, the system returns a number (called a file
descriptor) which the program uses to subsequently refer to the file.
File descriptors are always allocated sequentially starting from 0, and the lowest available file
descriptor is allocated next. Every program run under Unix has three files (and three file
descriptors) allocated automatically by the shell program (see
.it sh
(I)). These file descriptors are:-
.br 
.in+10
.sp
.ti-10
0	the standard input, which is determined by the command issued to the shell.
.ti-10
1	the standard output, which is also determined by the command issued to the shell.
.ti-10
2	the controlling teletype, which cannot be redirected.
.in-10
.PG
There is nothing to stop the user manipulating these files in any way which
is required, but Unix conventions regarding filters etc should be strictly
adhered to.
.SB "Overview of the available I/O routines"
.PG
The basis of I/O in Unix is a set of fundamental system calls which allow
the user to open, close, read and write files - see Section 4 of this manual.
.PG
There are two sets of routines which interact with the I/O system calls: first, the
Portable C library and secondly, a set of I/O routines supplied with the system, which will
be called 'Bell Routines' for convenience.
.PG
The Portable C library and the Bell routines provide similar I/O facilities (the
C Library also provides a method of executing various system functions).
It is usually dangerous to use of selection from both sets of I/O routines in one program, if one
I/O stream in a program uses C library routines
then in general the C library should be used for all the I/O in the
program.
.PG
There is also a general rule that if a file is opened by a system call, it cannot
be accessed either by the C library or the Bell routines. This rule is not
totally unbreakable, but new users should perhaps observe it until
they understand a bit more about Unix I/O.
New users are also advised to read through the paper on the C library which will give them
an idea of the flavour of Unix I/O.
.SB "The Portable C Library"
.PG
The library is stored on an archive file called /lib/libp.a and is
compiled with a C program by adding -lp (the letter l) at the end of the cc 
command, e.g:
.sp
	cc filename.c -lp
.sp
This ensures that the archive file for the library is searched before the normal
C archive file (this is very important if the correct getchar and putchar are to be
obtained).
.SH 3 "Bell Lab I/O Routines"
.PG
This section contains manual pages for the basic Bell routines which are used for
I/O on Unix, these routines are:-
.sp
.ul
Input
.sp
.in+20
.de LI
.br
.ti-20
\\$1		\\$2
..
.LI getchar "get a single character from the standard input stream"
.LI getc "get a single character from the input stream designated by a buffer, this routine is called by getchar"
.sp
.ti-20
.ul
Output
.sp
.LI printf "basic formatted output routine (calls putchar)"
.LI putchar "output a single character to the standard output (calls putc)"
.LI putc "output a character to a designated buffer"
.sp
.ti-20
.ul
Conversion _routines
.sp
.LI atof "convert Ascii to floating point"
.LI atoi "convert Ascii to integer"
.LI ecvt "convert floating to Ascii printing in exponent style"
.LI fcvt "convert floating to Ascii printing in decimal style"
.in-20
.sp
.SB "Notes"
.PG
For getc and putc it is not necessary to type in the entire buffer structure unless it is required to be
accessed, it is sufficient to declare it as
.sp
	char buf[518];
.sp
and call fopen (or fcreat) like:
.sp
	fd = fopen("filename", buf);
.PG
Any error which occurs when using these routines (or the system calls - Section 4) generally
causes a return value of -1 (or 0 in some cases), to obtain the system error message value
(see C manual - Language - Section 7)
the external variable 'errno' must be declared, viz;
.sp
	extern int errno;
.sp
and this will contain the actual value of the error number
returned by the system call.
.SH 4 "I/O System Calls"
.PG
This section contains the manual pages relating to the I/O system calls; the pages are:-
.in+10
.sp
.ti-10
close	close a file given a descriptor
.ti-10
creat	creat a file
.ti-10
dup	duplicate a file descriptor
.ti-10
open	open a file for reading or writing (file must exist)
.ti-10
read	read from a file
.ti-10
seek	find a position in a file
.ti-10
write	write to a file
.in-10
.SB Notes
.PG
Remember that the second parameters to the 'creat' and 'open' calls
are different, the second parameter to the creat call gives the access mode to
be used on the file and the second parameter to the open call is either 0, 1 or 2
specifying reading, writing or both.
.PG
The original CACM Unix paper stated that the 'seek' call returned a value giving the
current position in a file, note that this is not the case. There is no way of asking
the system to give you the current read/write pointer position, the only way to do
this is to count the characters which have been read.
.SH 5 "File Handling Calls and routines"
.PG 
This section contains manual reprints of the most used system calls and
routines which deal with files and teletypes. The pages are:-
.sp
.in+10
.ti-10
chdir	change working directory
.ti -10
chmod	change access mode on the file
.ti-10
fstat	get status of the file
.ti-10
gtty	get teletype information
.ti-10
link	link to a file
.ti-10
stat	get status of open file
.ti-10
stty	set teletype information
.ti-10
ttyn	get current teletype name
.ti-10
unlink	delete a file
.in-10
.SB Notes
.PG
Unlink deletes a file irrespective of its access permission.
