NAME

psio − NeWS buffered input/output package

SYNOPSIS

#include <NeWS/psio.h>
psio_assoc(pinstream, poutstream)
PSFILE ∗pinstream;
PSFILE ∗poutstream;
psio_availinputbytes(pstream)
PSFILE ∗pstream;
psio_availoutputbytes(pstream)
PSFILE ∗pstream;
psio_bytesoutput(pstream)
PSFILE ∗pstream
void psio_clearerr(pstream)
PSFILE ∗pstream;
psio_clearnonblock(pstream)
PSFILE ∗pstream;
int psio_close(pstream)
PSFILE ∗pstream;
psio_eof(pstream)
PSFILE ∗pstream;
psio_error(pstream)
PSFILE ∗pstream;
PSFILE ∗psio_fdopen(fd, mode)
int fd;
char ∗mode;
int psio_flush(pstream)
PSFILE ∗pstream;
int psio_fileno(pstream)
PSFILE ∗pstream;
psio_fprintf(pstream, format[,arg]...)
PSFILE ∗pstream;
char ∗format;
PSFILE ∗psio_getassoc(pinstream)
PSFILE ∗pinstream;
int psio_getc(pstream)
PSFILE ∗pstream;
PSFILE ∗psio_open(fname, mode)
char ∗fname;
char ∗mode;
psio_pgetc(pstream, dest, pausecode)
PSFILE ∗pstream;
int dest;
int pausecode;
psio_pgetc_nb(pstream, dest, pausecode)
PSFILE ∗pstream;
int dest;
int pausecode;
psio_pputc(c, pstream, pausecode)
char c;
PSFILE ∗pstream;
int pausecode;
psio_printf(format [,arg]...)
char ∗format;
psio_putc(ch, pstream)
char ch;
PSFILE ∗pstream;
int psio_read(dest, size, num, pstream)
unsigned char ∗dest;
int size, num;
PSFILE ∗pstream;
psio_setnonblock(pstream)
PSFILE ∗pstream;
PSFILE ∗psio_sopen(∗string, length, ∗mode)
char ∗string;
int length;
char ∗mode;
psio_ungetc(ch, pstream)
char ch;
PSFILE ∗pstream;
psio_write(source, size, num, pstream)
char ∗source;
int size, num;
PSFILE ∗pstream;

DESCRIPTION

The functions described here constitute a user-level I/O buffering scheme for use when communicating with NeWS. 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. 

The macros psio_getc and psio_putc read and write single characters quickly.  The higher level routines psio_read, psio_printf, psio_fprintf, psio_write all use or act as if they use psio_getc and psio_putc; they can be freely intermixed. 

A file with associated buffering is called a stream and is declared to be a pointer to a defined type PSFILE.  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 psio.h include file and associated with the standard open files:

psio_stdin standard input file

psio_stdout standard output file

psio_stderr standard error file

Any module that uses this package must include the header file of pertinent macro definitions, as follows:

#include "psio.h"

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): psio_getc, psio_putc, psio_eof, psio_error, psio_fileno, psio_clearerr, psio_pgetc, psio_pgetc_nb, psio_pputc, psio_setnonblock, psio_clearnonblock, psio_assoc, psio_getassoc, psio_availinputbytes, psio_availoutputbytes, and psio_bytesoutput.  The psio package contains enhancements over the stdio package that the X11/NeWS server and  clients need to utilize.  These features include:

The ability to open a psio stream on an in-memory string using the psio_sopen function. 

Support for non-blocking I/O.  If you set the file descriptors of the psio streams for non-blocking I/O, the actions that do not expect to see non-blocking behavior, such as psio_getc, psio_putc 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: psio_pgetc, psio_pgetc_nb, and psio_pputc.  The psio 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 psio_setnonblock macro. 

Support for buffer look-aheads.  The  package sometimes needs to skip over some of the data in the psio buffer and read data that is not at the front of the buffer.  The psio package cooperates with the  package in this respect. 

Support for growable buffers.  If a stream is set for non-blocking output and overfills its buffer, or if a buffer look-ahead cannot find the data it needs in the existing buffer, psio automatically makes the buffer grow in order to allow the writes to continue without blocking, and to allow the look-ahead to succeed. 

Support for linked input/output streams.  Using the psio_assoc macro, you can associate an output stream with an input stream so that the output stream is flushed whenever the psio package needs to block on the input stream. 

Macros to query the number of bytes available for reading, or the number of bytes available for output. 
LIST OF FUNCTIONS:

NameDescription

psio_assocAssociate the specified output stream with the specified input stream.  The output stream will be flushed when psio needs to block on the input stream.  Implemented as a macro. 

psio_availinputbytes
Return the number of bytes currently in the buffer waiting to be read.  Implemented as a macro.

psio_availoutputbytes
Return the number of bytes that can be written to the stream before the buffer is filled.  Implemented as a macro.

psio_bytesoutput
Return the number of bytes currently in the buffer that have been written and are waiting to be flushed.  Implemented as a macro.

psio_clearerrClear the error and end-of-file flags for the specified stream.  Implemented as a macro. 

psio_clearnonblock
Turn off the psio automatic non-blocking I/O feature for the specified stream.  Implemented as a macro. 

psio_closeClose the file associated with the stream and free the associated memory. 

psio_eofCheck the stream for a previously detected end-of-file status.  Implemented as a macro. 

psio_errorCheck the stream for a previously detected error.  Implemented as a macro. 

psio_fdopenOpen a stream and associate it with the specified file descriptor. 

psio_flushWrite any pending output for the specified output stream. 

psio_filenoReturn the file descriptor associated with the specified stream.  Implemented as a macro. 

psio_fprintfPlace output onto the named output stream according to standard printf specifications. 

psio_getassocReturn the output stream associated with the specified input stream.  Implemented as a macro. 

psio_getcGet a character or EOF from the specified input stream.  Implemented as a macro. 

psio_getcLike psio_getc, except that the result of the getc is assigned to dest, and if the operation needs to block, pausecode is executed first. pausecode is executed every time the buffer is emptied.  An attempt to refill the buffer is made before the pausecode is executed, so that the pausecode can determine if more input is available.  Implemented as a macro. 

psio_pgetc_nb
Like psio_pgetc, 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 psio_pgetc call).  Implemented as a macro. 

psio_openOpen the named file with the specified mode. 

psio_printfPlace output onto the stream psio_stdout according to standard printf specifications. 

psio_putcWrite a character to the specified output stream.  Implemented as a macro. 

psio_pputcLike psio_putc, except that if the operation needs to block, pausecode is executed first.  pausecode is executed every time the buffer is flushed. 

psio_readRead num blocks of size bytes from the specified input stream into the buffer dest. 

psio_setnonblock
Indicate that non-blocking I/O is to be performed on the specified stream.  The psio 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 psio_getc) 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 psio set and reset the file descriptor every time a read or write is performed.  Implemented as a macro. 

psio_sopenOpen the in-memory string of length length for reading or writing depending on mode.  If string is NULL, 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. 

psio_ungetcPush the character ch back into the specified input stream. 

psio_writeWrite num blocks of size bytes to the specified output stream from the buffer source. 

DIAGNOSTICS

The value EOF is returned uniformly to indicate that a PSFILE pointer has not been initialized with psio_open, that input has been attempted on an output stream, that output has been attempted on an input stream, or that a PSFILE pointer designates corrupt or otherwise unintelligible PSFILE data.  An integer constant (−1) is returned upon end-of-file or error by most integer functions that deal with streams.  psio_open returns a pointer to the psio stream or NULL (0) if there is an error. 

SEE ALSO

intro(3S), fclose(3S), ferror(3S), fopen(3S), fread(3S), getc(3S), printf(3S), putc(3S), ungetc(3S). 
 

SunOS 5.2  —  Last change: 29 June 1989