libs/src/sio/sio.3

   1 .\"(c) Copyright 1992, 1993 by Panagiotis Tsirigotis
   2 .\"All rights reserved.  The file named COPYRIGHT specifies the terms
   3 .\"and conditions for redistribution.
   4 .\"
   5 .\" $Id: sio.3,v 1.1.1.1 2003/02/19 17:29:27 bbraun Exp $
   6 .TH SIO 3X "29 May 1992"
   7 .SH NAME
   8 Sread, Sgetc, Srdline, Sfetch, Swrite, Sputc, Sprint, Sprintv, Sdone, Sundo, Stie, Suntie, Sflush, Sclose, Sbuftype, Smorefds, Sgetchar, Sputchar, SIOLINELEN - fast stream I/O
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 .ft B
  13 #include "sio.h"
  14 #include <stdarg.h>
  15 .LP
  16 .ft B
  17 int Sread( fd, buf, nbytes )
  18 int fd ;
  19 char *buf ;
  20 int nbytes ;
  21 .LP
  22 .ft B
  23 int Sgetc( fd )
  24 int fd ;
  25 .LP
  26 .ft B
  27 char *Srdline( fd )
  28 int fd ;
  29 .LP
  30 .ft B
  31 char *Sfetch( fd, length )
  32 int fd ;
  33 long *length ;
  34 .LP
  35 .ft B
  36 int Swrite( fd, buf, nbytes )
  37 int fd ;
  38 char *buf ;
  39 int nbytes ;
  40 .LP
  41 .ft B
  42 int Sputc( fd, c )
  43 int fd ;
  44 char c ;
  45 .LP
  46 .ft B
  47 int Sprint( fd, format [ , ... ] )
  48 int fd ;
  49 char *format ;
  50 .LP
  51 .ft B
  52 int Sprintv( fd, format, ap )
  53 int fd ;
  54 char *format ;
  55 va_list ap ;
  56 .LP
  57 .ft B
  58 int Sdone( fd )
  59 int fd ;
  60 .LP
  61 .ft B
  62 int Sundo( fd, type )
  63 int fd ;
  64 int type ;
  65 .LP
  66 .ft B
  67 int Stie( ifd, ofd )
  68 int ifd, ofd ;
  69 .LP
  70 .ft B
  71 int Suntie( fd )
  72 int fd ;
  73 .LP
  74 .ft B
  75 int Sbuftype( fd, type )
  76 int fd, type ;
  77 .LP
  78 .ft B
  79 int Smorefds()
  80 .LP
  81 .ft B
  82 int Sflush( fd )
  83 int fd ;
  84 .LP
  85 .ft B
  86 int Sclose( fd )
  87 int fd ;
  88 .LP
  89 .ft B
  90 int Sgetchar( fd )
  91 int fd ;
  92 .LP
  93 .ft B
  94 int Sputchar( fd, c )
  95 int fd;
  96 char c ;
  97 .LP
  98 .ft B
  99 int SIOLINELEN( fd )
 100 int fd ;
 101 .SH DESCRIPTION
 102 The \fISIO\fR library provides support
 103 for \fIstream\fR I/O on file descriptors.
 104 The first argument of every function
 105 or macro is a file descriptor. The file descriptor may be used either for
 106 input or for output but not both. Attempting to use a descriptor for
 107 both input and output will cause the call to fail. When you are
 108 done with using a file descriptor, you should inform \fISIO\fR
 109 by invoking \fBSdone()\fR (unless the program is about to
 110 call \fIexit(3)\fR).
 111 You can also use \fBSdone()\fR if
 112 you want to perform a different type of operation on the same
 113 file descriptor (e.g. first you were reading data from the file
 114 descriptor and then you want to write some data).
 115 Another possibility is to do stream I/O at different file offsets
 116 by using \fBSdone()\fR before doing the \fBlseek(2)\fR to the
 117 new file offset.
 118 .LP
 119 I/O operations on different file descriptors do not interfere
 120 (unless the file descriptors refer to the same file, in which case
 121 the results are undefined).
 122 .LP
 123 For disk files I/O always starts at the current file offset.
 124 If that offset is not a multiple of the preferred block size for file
 125 system I/O (the \fIst_blksize\fR field in \fIstruct stat\fR),
 126 performance will not be optimal.
 127 For optimal performance, it is recommended that no I/O operations
 128 (like \fIread(2)\fR or \fIwrite(2)\fR)
 129 are applied to the file descriptor if it is to be used by \fISIO\fR.
 130 .LP
 131 Read I/O is either buffered or is done using memory mapping whenever
 132 that is possible and appropriate.
 133 .LP
 134 The library functions that do stream I/O resemble system calls
 135 (for example \fBSread()\fR resembles \fIread(2)\fR) so that modifying
 136 a program that uses the system calls to use the \fISIO\fR functions
 137 is easy (e.g. just replace \fIread(2)\fR with \fBSread()\fR; the function
 138 signatures as well as the return values are exactly the same).
 139 .LP
 140 .B Sread()
 141 reads \fInbytes\fR bytes from the stream associated with file
 142 descriptor \fIfd\fR into the buffer pointed to by \fIbuf\fR.
 143 .LP
 144 .B Sgetc()
 145 reads a character from the stream
 146 associated with file descriptor \fIfd\fR.
 147 It returns \fBSIO_EOF\fR if the end of file has been reached.
 148 .LP
 149 .B Sgetchar()
 150 (a macro) performs exactly the same function as \fBSgetc()\fR but
 151 it is much faster.
 152 .LP
 153 .B Srdline()
 154 reads a line from the stream
 155 associated with file descriptor \fIfd\fR.
 156 The newline at the end of the line is replaced by a 0 byte. Lines
 157 longer than the maximum line length supported by \fISIO\fR will
 158 have characters deleted.
 159 .LP
 160 .B SIOLINELEN()
 161 (a macro) returns the length of
 162 the line returned by the last call to \fBSrdline()\fR
 163 (the value returned by \fBSIOLINELEN()\fR is valid only after
 164 \fBSrdline()\fR and as long as no other
 165 \fISIO\fR calls are performed on that file descriptor).
 166 .LP
 167 .B Sfetch()
 168 returns a pointer to data coming from the stream
 169 associated with file
 170 descriptor \fIfd\fR. The amount of data available is indicated
 171 by the \fIlength\fR argument. One possible use for this function
 172 is copying of files.
 173 .LP
 174 .B Swrite()
 175 writes \fInbytes\fR bytes to the stream associated with file
 176 descriptor \fIfd\fR from the buffer pointed to by \fIbuf\fR.
 177 .LP
 178 .B Sputc()
 179 writes a single character to the stream
 180 associated with file descriptor \fIfd\fR.
 181 .LP
 182 .B Sputchar()
 183 (a macro) performs exactly the same function as \fBSputc()\fR
 184 but it is much faster.
 185 .LP
 186 .B Sprint()
 187 imitates the behavior of printf(3) as defined in the
 188 ANSI C Standard. There are some limitations. Check the \fBSprint()\fR
 189 man page for more information.
 190 .LP
 191 .B Sprintv()
 192 is the same as \fBSprint()\fR except that it takes a
 193 \fIstdarg\fR argument list.
 194 .LP
 195 .B Sundo()
 196 returns the characters returned by the last call to
 197 \fBSrdline()\fR, \fBSgetc()\fR or \fBSgetchar()\fR to the stream
 198 so that they can be reread. The \fItype\fR argument to \fBSundo()\fR
 199 can be \fBSIO_UNDO_LINE\fR or \fBSIO_UNDO_CHAR\fR depending
 200 on whether the call whose effect needs to be undone was
 201 \fBSrdline()\fR or \fBSgetc()\fR/\fBSgetchar()\fR respectively.
 202 There is no check on
 203 whether the last function invoked on \fIfd\fR was one of the above
 204 and the results are undefined if there is no correspondence
 205 between the \fItype\fR and the last operation on \fIfd\fR.
 206 (i.e. the result is undefined if you try \fBSIO_UNDO_CHAR\fR
 207 and the last operation was not \fBSgetchar()\fR or \fBSgetc()\fR).
 208 .LP
 209 .B Stie()
 210 ties the file descriptor \fIifd\fR to the file descriptor \fIofd\fR.
 211 This means that whenever a \fIread(2)\fR is done on \fIifd\fR, it is
 212 preceded by a \fIwrite(2)\fR on \fIofd\fR.
 213 For filters it is useful to do \fIStie( 0, 1 )\fR to maximize concurrency.
 214 It is also useful to do the same thing when you issue prompts to the
 215 user and you want the user reply to appear on the same line with the
 216 prompt.
 217 \fIifd\fR, \fIofd\fR  will be initialized for input, output respectively
 218 (if any of them is initialized, it must be for the appropriate
 219 stream type (input or output)).
 220 If \fIifd\fR was tied to another file descriptor, the old tie is broken.
 221 .LP
 222 .B Suntie()
 223 undoes the effect of \fBStie()\fR for the specified input file descriptor.
 224 .LP
 225 .B Sbuftype()
 226 determines the buffering type for the output stream associated with
 227 file descriptor \fIfd\fR.
 228 By default output directed to terminals is line buffered, output
 229 directed to file descriptor 2 (standard error) is unbuffered and
 230 everything else is fully buffered.
 231 Possible values for the \fItype\fR argument are
 232 .RS
 233 .TP 15
 234 .B SIO_FULLBUF
 235 for full buffering
 236 .TP
 237 .B SIO_LINEBUF
 238 for line buffering
 239 .TP
 240 .B SIO_NOBUF
 241 for no buffering
 242 .RE
 243 .LP
 244 .B Smorefds()
 245 should be used to inform \fBSIO\fR that the number of available file
 246 descriptors has been increased. \fBSIO\fR uses an array of internal
 247 stream descriptors which are indexed by the file descriptor number. Some
 248 operating systems (ex. SunOS 4.1[.x]) allow the number of available
 249 file descriptors to vary. If that number is increased beyond its initial
 250 value \fBSIO\fR needs to know in order to allocate more stream descriptors.
 251 .LP
 252 .B Sdone()
 253 flushes any buffered output for \fIfd\fR
 254 and releases the \fISIO\fR resources used. \fBSdone()\fR
 255 is useful in case the program needs to reprocess the
 256 data of a file descriptor (assuming the file descriptor corresponds
 257 to a file).  The program can call \fBSdone()\fR,
 258 \fIlseek(2)\fR to the beginning of the file
 259 and then proceed to reread the file.
 260 .LP
 261 .B Sflush()
 262 causes any buffered stream output to be written to the
 263 file descriptor. If its argument is the special value \fBSIO_FLUSH_ALL\fR
 264 then all output streams will be flushed.
 265 .LP
 266 .B Sclose()
 267 closes a file descriptor used for stream I/O, flushes
 268 any buffered output and releases the \fISIO\fR resources used.
 269 .SH EXAMPLES
 270 .LP
 271 The following code implements a (poor) substitute for the tee command
 272 (it copies standard input to a file as well as to standard output).
 273 .ne 10
 274 .RS
 275 .nf
 276 .ft B
 277 #include "sio.h"
 278 .sp .5
 279 main( argc, argv )
 280         int argc ;
 281         char *argv[] ;
 282 {
 283         char *file = (argc > 1) ? argv[ 1 ] : "tee.file" ;
 284         int fd = creat( file, 0644 ) ;
 285         long length ;
 286         char *s ;
 287 .sp .5
 288         while ( s = Sfetch( 0, &length ) )
 289         {
 290                 Swrite( 1, s, length ) ;
 291                 Swrite( fd, s, length ) ;
 292         }
 293         exit( 0 ) ;
 294 }
 295 .fi
 296 .ft R
 297 .RE
 298 .SH RETURN VALUES
 299 .LP
 300 .B Sread()
 301 returns the number of bytes read on success
 302 (0 means end-of-file)
 303 or \fBSIO_ERR\fR on failure (\fIerrno\fR is set to indicate the error).
 304 .LP
 305 .B Sgetc()
 306 returns the character read on success,
 307 SIO_EOF when the end-of-file is reached,
 308 or \fBSIO_ERR\fR on failure (\fIerrno\fR is set to indicate the error).
 309 .LP
 310 .B Srdline()
 311 returns a pointer to the next line on success.
 312 On failure or when the end-of-file is reached it returns
 313 .SM NULL.
 314 If the end-of-file is reached \fIerrno\fR is set to 0, otherwise it indicates
 315 the error.
 316 .LP
 317 .B Sfetch()
 318 returns a pointer to file data on success.
 319 (the \fIlength\fR argument indicates how many bytes
 320 are available).
 321 On failure or when the end-of-file is reached it returns
 322 .SM NULL.
 323 If the end-of-file is reached \fIerrno\fR is set to 0, otherwise it indicates
 324 the error.
 325 .LP
 326 .B Swrite()
 327 returns the number of bytes written on success
 328 or \fBSIO_ERR\fR on failure (\fIerrno\fR is set to indicate the error).
 329 .LP
 330 .B Sputc()
 331 returns the character it was given as an argument on success
 332 .B Sprint()
 333 returns the number of characters printed on success
 334 or \fBSIO_ERR\fR on failure (\fIerrno\fR is set to indicate the error).
 335 .LP
 336 .B Sdone()
 337 returns \fB0\fR on success
 338 or \fBSIO_ERR\fR on failure (\fIerrno\fR is set to indicate the error).
 339 .LP
 340 .B Sundo()
 341 returns \fB0\fR on success
 342 or \fBSIO_ERR\fR on failure (\fIerrno\fR is set to indicate the error).
 343 .LP
 344 .B Stie()
 345 returns \fB0\fR on success
 346 or \fBSIO_ERR\fR on failure (\fIerrno\fR is set to indicate the error).
 347 .LP
 348 .B Suntie()
 349 returns \fB0\fR on success
 350 or \fBSIO_ERR\fR on failure
 351 (\fIerrno\fR is set to \fBEBADF\fR if there
 352 was no tied file descriptor).
 353 .LP
 354 .B Sbuftype()
 355 returns \fB0\fR on success
 356 or \fBSIO_ERR\fR on failure
 357 (\fIerrno\fR is set to \fBEBADF\fR if this is not an output stream
 358 or to \fBEINVAL\fR if an unknown \fItype\fR is specified).
 359 .LP
 360 .B Smorefds()
 361 returns \fB0\fR on success
 362 or \fBSIO_ERR\fR on failure (because of lack of memory).
 363 .LP
 364 .B Sflush()
 365 returns \fB0\fR on success
 366 or \fBSIO_ERR\fR on failure (\fIerrno\fR is set to indicate the error).
 367 .LP
 368 .B Sclose()
 369 returns \fB0\fR on success
 370 or \fBSIO_ERR\fR on failure (\fIerrno\fR is set to indicate the error).
 371 .LP
 372 .B Sgetchar()
 373 returns the character read on success,
 374 SIO_EOF when the end-of-file is reached,
 375 or \fBSIO_ERR\fR on failure (\fIerrno\fR is set to indicate the error).
 376 .LP
 377 .B Sputchar()
 378 returns the character it was given as an argument on success
 379 or \fBSIO_ERR\fR on failure (\fIerrno\fR is set to indicate the error).
 380 .LP
 381 .B SIOLINELEN()
 382 returns the length of the last line read by \fBSrdline()\fR.
 383 .LP
 384 Attempting a read operation on a descriptor opened for writing or vice
 385 versa will cause the operation to fail with \fIerrno\fR set to \fBEBADF\fR.
 386 .LP
 387 The first \fISIO\fR operation on a descriptor must be a read or write
 388 operation. It cannot be a control operation (like \fBSflush()\fR). Such
 389 an operation will fail with \fIerrno\fR set to \fBEBADF\fR.
 390 .LP
 391 .IP "\fBNOTE 1:\fR" 15
 392 \fBStie()\fR is an input/output operation for the
 393 respective file descriptors, not a control operation. \fBSuntie()\fR
 394 is a control operation.
 395 .IP "\fBNOTE 2:\fR"
 396 \fBSIO_ERR\fR is defined to be \fB-1\fR.
 397 .SH "SEE ALSO"
 398 .LP
 399 Sprint(3)
 400 .SH BUGS
 401 .LP
 402 If the operating system does not provide for invocation of a
 403 finalization function upon exit, the program will have to
 404 explicitly flush all output streams.
 405 The following operating systems provide such a facility:
 406 SunOS 4.x, Ultrix 4.x.
 407 .LP
 408 Socket file descriptors can be used for input as well as output but
 409 \fBSIO\fR does not support this.
 410 .LP
 411 The current implementation will not try to use memory mapping to
 412 read a file if the file offset is not 0 (it will use buffered I/O instead).
 413 .LP
 414 Pointers returned by \fBSfetch()\fR point to read-only memory.
 415 Attempting to modify this memory will result in a segmentation
 416 violation.