'\"macro stdmacro
.if n .pH g3.psio @(#)psio	40.2 of 12/29/89
.ig
Revised: D. Bodnar 9/7/89
format -dqm4 -man6 -rs1 psio.3
..
.nr X
.if \nX=0 .ds x} PSIO 3 "29 June 1989" "\&"
.if \nX=1 .ds x} PSIO 3 "29 June 1989"
.if \nX=2 .ds x} PSIO 3 "" "\&"
.if \nX=3 .ds x} PSIO "" "" "\&"
.TH \*(x}
.\" .IX psio#(3) "" "\fLpsio\fP(3) \(em \*(Sd buffered input/output package"
.ds Ps P\s-2OST\s+2S\s-2CRIPT\s+2
.ds Sd \s-2Ne\h'-0.2n'WS\s+2
.ds Xn \s-2X11/N\s+2e\h'-0.2n'\s-2WS\s+2
.ds Xn X11/Ne\h'-0.2n'WS
.IX psio#(3) "" "\fLpsio\fP(3)"
.ds Pf \s-1PSFILE\s+1
.SH NAME
psio \- \*(Sd buffered input/output package
.SH SYNOPSIS
.ft B
.nf
#include <\*(Sd/psio.h>
.sp
psio_assoc(pinstream, poutstream)  
\*(Pf *pinstream;
\*(Pf *poutstream;
.sp
psio_availinputbytes(pstream)  
\*(Pf *pstream;
.sp
psio_availoutputbytes(pstream)
\*(Pf *pstream;
.sp
psio_bytesoutput(pstream)  
\*(Pf *pstream
.sp
void psio_clearerr(pstream)
\*(Pf *pstream;
.sp
psio_clearnonblock(pstream)   
\*(Pf *pstream;
.sp
int psio_close(pstream)
\*(Pf *pstream;
.sp
psio_eof(pstream)
\*(Pf *pstream;
.sp
psio_error(pstream)
\*(Pf *pstream;
.sp
\*(Pf *psio_fdopen(fd, mode)
int fd;
char *mode;
.sp
int psio_flush(pstream)
\*(Pf *pstream;
.sp
int psio_fileno(pstream)
\*(Pf *pstream;
.sp
psio_fprintf(pstream, format[,arg]...)
\*(Pf *pstream;
char *format;
.sp
\*(Pf *psio_getassoc(pinstream)   
\*(Pf *pinstream;
.sp
int psio_getc(pstream)
\*(Pf *pstream;
.sp
\*(Pf *psio_open(fname, mode)
char *fname;
char *mode;
.sp
psio_pgetc(pstream, dest, pausecode)  
\*(Pf *pstream;
int dest;
int pausecode;
.sp
psio_pgetc_nb(pstream, dest, pausecode)  
\*(Pf *pstream;
int dest;
int pausecode;
.sp
psio_pputc(c, pstream, pausecode)  
char c;
\*(Pf *pstream;
int pausecode;
.sp
psio_printf(format [,arg]...)
char *format;
.sp
psio_putc(ch, pstream)
char ch;
\*(Pf *pstream;
.sp
int psio_read(dest, size, num, pstream)
unsigned char *dest;
int size, num;
\*(Pf *pstream;
.sp
psio_setnonblock(pstream)   
\*(Pf *pstream;
.sp
\*(Pf *psio_sopen(*string, length, *mode) 
char *string;
int length;
char *mode;
.sp
psio_ungetc(ch, pstream)
char ch;
\*(Pf *pstream;
.sp
psio_write(source, size, num, pstream)
char *source;
int size, num;
\*(Pf *pstream;
.ft R
.fi
.bp
.SH DESCRIPTION
.IX news "I/O library functions" "\*(Sd"
The functions described here constitute a user-level I/O buffering
scheme for use when communicating with \*(Sd. This package is based on
the standard I/O package that comes with UNIX. The functions in this
package are used in the same way as the similarly named functions in
Standard I/O.
.LP
The macros
.B psio_getc
and
.BR  psio_putc
read and write single characters quickly.
The higher level routines
.BR psio_read ,
.BR psio_printf ,
.BR psio_fprintf ,
.BR psio_write
all use or act as if they use
.B psio_getc
and
.BR psio_putc ;
they can be freely intermixed.
.LP
A file with associated buffering is called a
.IR stream
and is declared to be a pointer to a defined type
.SM
.BR PSFILE .
.B psio_open
creates certain descriptive data for a stream
and returns a pointer to designate the stream in all further transactions.
Normally, there are three open streams with constant pointers declared in
the
.B "psio.h"
include file and associated with the standard open files:
.\" these must be initialized; this is a bug I might fix
.\" soon -- Jim Graham
.TP 15n
.B psio_stdin
standard input file
.br
.ns
.TP
.B psio_stdout
standard output file
.br
.ns
.TP
.B psio_stderr
standard error file
.LP
Any module that uses this package
must include the header file of pertinent macro definitions,
as follows:
.PP
.RS
\fB#include \|"psio.h"\fP
.RE
.PP
The functions and constants mentioned here
are declared in that header file and need no further declaration.
The constants and the following `functions' are
implemented as macros (redeclaration of these names is perilous):
\fBpsio_getc\fP, 
\fBpsio_putc\fP, 
\fBpsio_eof\fP, 
\fBpsio_error\fP, 
\fBpsio_fileno\fP, 
\fBpsio_clearerr\fP, 
\fBpsio_pgetc\fP, 
\fBpsio_pgetc_nb\fP, 
\fBpsio_pputc\fP, 
\fBpsio_setnonblock\fP, 
\fBpsio_clearnonblock\fP, 
\fBpsio_assoc\fP, 
\fBpsio_getassoc\fP, 
\fBpsio_availinputbytes\fP, 
\fBpsio_availoutputbytes\fP, 
and \fBpsio_bytesoutput\fP.
.sp
The \fBpsio\fP package contains enhancements over the \fBstdio\fP package that the
\*(Xn server and CPS clients need to utilize.  These features include:
.IP
The ability to open a \fBpsio\fP stream on an in-memory string using
the \fBpsio_sopen\fP function.
.IP
Support for non-blocking I/O.  If you set the file descriptors
of the \fBpsio\fP streams for non-blocking I/O, the actions that
do not expect to see non-blocking behavior, such as \fBpsio_getc\fP,
\fBpsio_putc\fP and the functions that use them, will still behave
correctly, blocking on the file descriptor until the I/O completes.
In order to access the streams in a non-blocking mode, there are
macros to perform non-blocking character reads and writes:
\fBpsio_pgetc\fP, \fBpsio_pgetc_nb\fP, and \fBpsio_pputc\fP.  The \fBpsio\fP package 
also performs non-blocking I/O operations on the file descriptor
for you, without your having to use system dependent functions to set up
the file descriptors for non-blocking I/O, as specified by
the \fBpsio_setnonblock\fP macro.
.IP
Support for buffer \fIlook-aheads\fP.  The CPS package sometimes needs to
skip over some of the data in the \fBpsio\fP buffer and
read data that is not at the front of the buffer.  The \fBpsio\fP
package cooperates with the CPS package in this respect.
.IP
Support for growable buffers.  If a stream is set for non-blocking
output and overfills its buffer, or if a buffer \fIlook-ahead\fP
cannot find the data it needs in the existing buffer, \fBpsio\fP
automatically makes the buffer grow in order to allow the writes to continue
without blocking, and to allow the \fIlook-ahead\fP to succeed.
.IP
Support for linked input/output streams.  Using the \fBpsio_assoc\fP
macro, you can associate an output stream with an input stream
so that the output stream is flushed whenever the \fBpsio\fP
package needs to block on the input stream.
.IP
Macros to query the number of bytes available for reading, or
the number of bytes available for output.
.sp 
.SM LIST OF FUNCTIONS:
.sp .25
.IP \fIName\fR 15n
\fIDescription\fR
.IP \fBpsio_assoc\fR
Associate the specified output stream with the specified input
stream.  The output stream will be flushed when \fBpsio\fP needs to
block on the input stream.  Implemented as a macro.
.IP \fBpsio_availinputbytes\fP
Return the number of bytes currently in the buffer waiting to
be read.  Implemented as a macro.
.IP \fBpsio_availoutputbytes\fP
Return the number of bytes that can be written to the stream before
the buffer is filled.  Implemented as a macro.
.IP \fBpsio_bytesoutput\fP
Return the number of bytes currently in the buffer that have been
written and are waiting to be flushed.  Implemented as a macro.
.IP \fBpsio_clearerr\fP
Clear the error and end-of-file flags for the specified stream.
Implemented as a macro.
.IP \fBpsio_clearnonblock\fP
Turn off the \fBpsio\fP automatic non-blocking I/O feature for the
specified stream.  Implemented as a macro.
.IP \fBpsio_close\fP
Close the file associated with the stream and free the associated
memory.
.IP \fBpsio_eof\fP
Check the stream for a previously detected end-of-file status.
Implemented as a macro.
.IP \fBpsio_error\fP
Check the stream for a previously detected error.
Implemented as a macro.
.IP \fBpsio_fdopen\fP
Open a stream and associate it with the specified file descriptor.
.IP \fBpsio_flush\fP
Write any pending output for the specified output stream.
.IP \fBpsio_fileno\fP
Return the file descriptor associated with the specified stream.
Implemented as a macro.
.IP \fBpsio_fprintf\fP
Place output onto the named output stream according to standard
printf specifications.
.IP \fBpsio_getassoc\fP
Return the output stream associated with the specified input
stream.  Implemented as a macro.
.IP \fBpsio_getc\fP
Get a character or EOF from the specified input stream.
Implemented as a macro.
.IP \fBpsio_getc\fP
Like \fBpsio_getc\fP, except that the result of the \fBgetc\fP
is assigned to \fBdest\fP, and if the operation needs to block,
\fBpausecode\fP is executed first. \fBpausecode\fP is executed every
time the buffer is emptied.  An attempt to refill the buffer is
made before the \fBpausecode\fP is executed, so that the \fBpausecode\fP
can determine if more input is available.  Implemented as a macro.
.IP \fBpsio_pgetc_nb\fP
Like \fBpsio_pgetc\fP, except that it tries to fill
the buffer before before pausing.  This is usually desirable
for the first read on the stream after it has just been created
or previously blocked (for example, in a \fBpsio_pgetc\fP call).  Implemented as a macro.
.IP \fBpsio_open\fP
Open the named file with the specified mode.
.IP \fBpsio_printf\fP
Place output onto the stream \fBpsio_stdout\fP according to standard
printf specifications.
.IP \fBpsio_putc\fP
Write a character to the specified output stream.
Implemented as a macro.
.IP \fBpsio_pputc\fP
Like \fBpsio_putc\fP, except that if the operation needs
to block, \fBpausecode\fP is executed first.  \fBpausecode\fP is
executed every time the buffer is flushed.
.IP \f3psio_read\f1
Read \fInum\fR blocks of \fIsize\fR bytes from the specified input
stream into the buffer \fIdest\fR.
.IP \fBpsio_setnonblock\fP
Indicate that non-blocking I/O is to be performed on the specified
stream.  The \fBpsio\fP package will set the corresponding file descriptor
for non-blocking I/O during its reads and writes to prevent blocking.
Note that certain functions (such as \fBpsio_getc\fP) will block anyway,
and that it is faster (though less elegant and portable) if you yourself set the
file descriptor once for non-blocking I/O, rather than
using this feature to have \fBpsio\fP set and reset the file descriptor
every time a read or write is performed.
Implemented as a macro.
.IP \fBpsio_sopen\fP
Open the in-memory \fBstring\fP of length \fBlength\fP for reading
or writing depending on \fBmode\fP.  If string is \fBNULL\fP, then
psio will allocate a buffer for the result (for writing only)
of the specified length; this buffer will be grown if writes
overrun the specified length.
.IP \fBpsio_ungetc\fP
Push the character \fIch\fR back into the specified input stream.
.IP \fBpsio_write\fP
Write \fInum\fR blocks of \fIsize\fR bytes to the specified
output stream from the buffer \fIsource\fR.
.SH DIAGNOSTICS
The value
.SB EOF
is returned uniformly to indicate that a
.SB PSFILE
pointer has not been initialized with
.BR psio_open ,
.\" res sequendae - check that the following clauses are correct:
that input 
.\" (output) 
has been attempted on an output 
.\" (input) 
stream,
that output has been attempted on an input stream,
or that a
.SB PSFILE
pointer designates corrupt or otherwise unintelligible
.SB PSFILE
data.
An integer constant
(\-1) is returned upon end-of-file or error by most
integer functions that deal with streams.
\fBpsio_open\fR returns a pointer to the \fBpsio\fP stream or
\fB\s-1NULL\s+1\fR (0)
if there is an error.
.SH "SEE ALSO"
\fBintro\fP(3S),
\fBfclose\fP(3S),
\fBferror\fP(3S),
\fBfopen\fP(3S),
\fBfread\fP(3S),
\fBgetc\fP(3S),
\fBprintf\fP(3S),
\fBputc\fP(3S),
\fBungetc\fP(3S).

