1.fp 5 CW 2.TH SFIO 3 "01 June 2008" 3.SH NAME 4\fBsfio\fR \- safe/fast string/file input/output 5.SH SYNOPSIS 6.de Tp 7.fl 8.ne 3 9.TP 10.. 11.de Ss 12.fl 13.ne 3 14.SS "\\$1" 15.. 16.ta 1.0i 2.0i 3.0i 4.0i 5.0i 17.Ss "LIBRARIES" 18.nf 19.ft 5 20#include <sfio.h> 21 22libsfio.a -lsfio 23libstdio.a -lstdio 24libsfio-mt.a -lsfio-mt 25libstdio-mt.a -lstdio-mt 26.ft 1 27.fi 28.Ss "DATA TYPES" 29.nf 30.ft 5 31Void_t; 32Sfoff_t; 33Sflong_t; 34Sfulong_t; 35Sfdouble_t; 36 37Sfio_t; 38 39Sfdisc_t; 40ssize_t (*Sfread_f)(Sfio_t*, Void_t*, size_t, Sfdisc_t*); 41ssize_t (*Sfwrite_f)(Sfio_t*, const Void_t*, size_t, Sfdisc_t*); 42Sfoff_t (*Sfseek_f)(Sfio_t*, Sfoff_t, int, Sfdisc_t*); 43int (*Sfexcept_f)(Sfio_t*, int, Void_t*, Sfdisc_t*); 44 45Sffmt_t; 46int (*Sffmtext_f)(Sfio_t*, Void_t*, Sffmt_t*); 47int (*Sffmtevent_f)(Sfio_t*, int, Void_t*, Sffmt_t*); 48 49SFIO_VERSION 50.ft 1 51.fi 52.Ss "BIT FLAGS" 53.nf 54.ft 5 55SF_STRING 56SF_READ 57SF_WRITE 58SF_APPENDWR (SF_APPEND) 59SF_LINE 60SF_SHARE 61SF_PUBLIC 62SF_MALLOC 63SF_STATIC 64SF_IOCHECK 65SF_WHOLE 66SF_MTSAFE 67SF_IOINTR 68.ft 1 69.fi 70.Ss "OPENING/CLOSING STREAMS" 71.nf 72.ft 5 73Sfio_t* sfnew(Sfio_t* f, Void_t* buf, size_t size, int fd, int flags); 74Sfio_t* sfopen(Sfio_t* f, const char* string, const char* mode); 75Sfio_t* sfpopen(Sfio_t* f, const char* cmd, const char* mode); 76Sfio_t* sftmp(size_t size); 77int sfclose(Sfio_t* f); 78 79 80.ft 1 81.fi 82.Ss "THREAD SAFETY" 83.nf 84.ft 5 85int sfmutex(Sfio_t* f, int type); 86 87SFMTX_LOCK 88SFMTX_TRYLOCK 89SFMTX_UNLOCK 90SFMTX_CLRLOCK 91.ft 1 92.fi 93.Ss "INPUT/OUTPUT OPERATIONS" 94.nf 95.ft 5 96int sfgetc(Sfio_t* f); 97int sfputc(Sfio_t* f, int c); 98int sfnputc(Sfio_t* f, int c, int n); 99int sfungetc(Sfio_t* f, int c); 100 101Sfulong_t sfgetm(Sfio_t* f, Sfulong_t max); 102int sfputm(Sfio_t* f, Sfulong_t v, Sfulong_t max); 103Sfulong_t sfgetu(Sfio_t* f); 104int sfputu(Sfio_t* f, Sfulong_t v); 105Sflong_t sfgetl(Sfio_t* f); 106int sfputl(Sfio_t* f, Sflong_t v); 107Sfdouble_t sfgetd(Sfio_t* f); 108int sfputd(Sfio_t* f, Sfdouble_t v); 109 110char* sfgetr(Sfio_t* f, int rsc, int type); 111ssize_t sfputr(Sfio_t* f, const char* s, int rsc); 112Sfoff_t sfmove(Sfio_t* fr, Sfio_t* fw, Sfoff_t n, int rsc); 113 114ssize_t sfread(Sfio_t* f, Void_t* buf, size_t n); 115ssize_t sfwrite(Sfio_t* f, const Void_t* buf, size_t n); 116Sfoff_t sfseek(Sfio_t* f, Sfoff_t offset, int type); 117Void_t* sfreserve(Sfio_t* f, ssize_t n, int type); 118.ft 1 119.fi 120.Ss "DATA FORMATTING" 121.nf 122.ft 5 123int sfscanf(Sfio_t* f, const char* format, ...); 124int sfsscanf(const char* s, const char* format, ...); 125int sfvsscanf(const char* s, const char* format, va_list args); 126int sfvscanf(Sfio_t* f, const char* format, va_list args); 127 128int sfprintf(Sfio_t* f, const char* format, ...); 129char* sfprints(const char* format, ...); 130char* sfvprints(const char* format, va_list args); 131ssize_t sfaprints(char** sp, const char* format, ...); 132ssize_t sfvaprints(char** sp, const char* format, va_list args); 133int sfsprintf(char* s, int n, const char* format, ...); 134int sfvsprintf(char* s, int n, const char* format, va_list args); 135int sfvprintf(Sfio_t* f, const char* format, va_list args); 136 137Sffmt_t; 138 139SFFMT_LEFT 140SFFMT_SIGN 141SFFMT_BLANK 142SFFMT_ZERO 143SFFMT_THOUSAND 144SFFMT_LONG 145SFFMT_LLONG 146SFFMT_SHORT 147SFFMT_LDOUBLE 148SFFMT_IFLAG 149SFFMT_ALTER 150SFFMT_SKIP 151SFFMT_ARGPOS 152SFFMT_VALUE 153 154int (*Sffmtext_f)(Sfio_t* f, Void_t* v, Sffmt_t* fe); 155int (*Sffmtevent_f)(Sfio_t* f, int type, Void_t* v, Sffmt_t* fe); 156void va_copy(va_list to, va_list fr); 157long sffmtversion(Sffmt_t* fe, type); 158.ft 1 159.fi 160.Ss "BUFFERING, SYNCHRONIZATION" 161.nf 162.ft 5 163Void_t* sfsetbuf(Sfio_t* f, Void_t* buf, size_t size); 164int sfsync(Sfio_t* f); 165int sfpoll(Sfio_t** flist, int n, int timeout); 166Sfio_t* sfpool(Sfio_t* f, Sfio_t* poolf, int mode); 167int sfpurge(Sfio_t* f); 168.ft 1 169.fi 170.Ss "DISCIPLINE, EVENT HANDLING" 171.nf 172.ft 5 173Sfdisc_t* sfdisc(Sfio_t* f, Sfdisc_t* disc); 174int sfraise(Sfio_t* f, int type, Void_t* data); 175ssize_t sfrd(Sfio_t* f, Void_t* buf, size_t n, Sfdisc_t* disc); 176ssize_t sfwr(Sfio_t* f, const Void_t* buf, size_t n, Sfdisc_t* disc); 177Sfoff_t sfsk(Sfio_t* f, Sfoff_t offset, int type, Sfdisc_t* disc); 178 179SF_NEW 180SF_READ 181SF_WRITE 182SF_SEEK 183SF_CLOSING (SF_CLOSE) 184SF_DPUSH 185SF_DPOP 186SF_DPOLL 187SF_DBUFFER 188SF_SYNC 189SF_PURGE 190SF_FINAL 191SF_READY 192SF_LOCKED 193SF_ATEXIT 194SF_EVENT 195.ft 1 196.fi 197.Ss "STREAM CONTROL" 198.nf 199.ft 5 200int sfresize(Sfio_t* f, Sfoff_t size); 201int sfset(Sfio_t* f, int flags, int i); 202int sfsetfd(Sfio_t* f, int fd); 203Sfio_t* sfstack(Sfio_t* base, Sfio_t* top); 204Sfio_t* sfswap(Sfio_t* f1, Sfio_t* f2); 205.ft 1 206.fi 207.Ss "STREAM INFORMATION" 208.nf 209.ft 5 210Sfoff_t sfsize(Sfio_t* f); 211Sfoff_t sftell(Sfio_t* f); 212ssize_t sfvalue(Sfio_t* f); 213int sffileno(Sfio_t* f); 214 215int sfstacked(Sfio_t* f); 216int sfeof(Sfio_t* f); 217int sferror(Sfio_t* f); 218int sfclrerr(Sfio_t* f); 219int sfclrlock(Sfio_t* f); 220 221int sfnotify(void (*notify)(Sfio_t* f, int type, Void_t* data)); 222 223int sfwalk(Sfwalk_f walkf, Void_t* data, int type); 224.ft 1 225.fi 226.Ss "MISCELLANEOUS FUNCTIONS" 227.nf 228.ft 5 229ssize_t sfmaxr(ssize_t maxr, int s); 230ssize_t sfslen(); 231int sfulen(Sfulong_t v); 232int sfllen(Sflong_t v); 233int sfdlen(Sfdouble_t v); 234ssize_t sfpkrd(int fd, Void_t* buf, size_t n, 235 int rsc, long tm, int action); 236.ft 1 237.fi 238.Ss "FULL STRUCTURE SFIO_T" 239.nf 240.ft 5 241#include <sfio_t.h> 242#define SFNEW(buf,size,file,flags,disc) 243.ft 1 244.fi 245.Ss "EXAMPLE DISCIPLINES" 246.nf 247.ft 5 248#include <sfdisc.h> 249 250int sfdcdio(Sfio_t* f, size_t bufsize); 251int sfdcdos(Sfio_t* f); 252int sfdcfilter(Sfio_t* f, const char* cmd); 253int sfdcseekable(Sfio_t* f); 254int sfdcslow(Sfio_t* f); 255int sfdcsubstream(Sfio_t* f, Sfio_t* parent, 256 Sfoff_t offset, Sfoff_t extent); 257int sfdctee(Sfio_t* f, Sfio_t* tee); 258int sfdcunion(Sfio_t* f, Sfio_t** array, int n); 259int sfdclzw(Sfio_t* f); 260int sfdcgzip(Sfio_t* f, int flags); 261.ft 1 262.fi 263.Ss "STDIO-COMPATIBILITY" 264.nf 265.ft 5 266#include <stdio.h> 267cc ... -lstdio -lsfio 268cc ... -lstdio-mt -lsfio-mt 269.ft 1 270.fi 271.SH DESCRIPTION 272.PP 273Sfio provides I/O functions to manage buffered streams. 274Each Sfio stream is a \fIfile stream\fP, representing a file (see \f5open(2)\fP), 275or a \fIstring stream\fP, representing a memory segment. 276Beyond the usual I/O operations on streams, 277Sfio provides I/O disciplines for extended data processing, 278stream stacks for recursive stream processing, and 279stream pools for automatic data synchronization. 280Applications can extend the \f5sfprintf()/sfscanf()\fP functions 281to define their own conversion patterns as well as redefine existing ones. 282.PP 283A discipline defines analogues of 284the system calls \f5read(2), write(2)\fP and \f5lseek(2)\fP. 285Such system calls or their discipline replacements are used to process stream data. 286Henceforth, ``\fIsystem call\fP'' will refer to either a system call 287or its discipline replacement. 288.PP 289A system call is said to cause an exception if its return value is non-positive. 290Unless overridden by exception handlers (see \f5sfdisc()\fP), 291an interrupted system call (\f5errno == EINTR\fP on UNIX systems) 292will be automatically reinvoked to continue the ongoing operation. 293.PP 294The buffer of a stream is typically a memory segment allocated via \f5malloc(3)\fP 295or supplied by the application. 296File streams may also use memory mapping (\f5mmap(2)\fP) if that is more efficient. 297When memory mapping is used, 298the underlying file should not be truncated while the stream is active. 299Memory mapping can be turned off using \f5sfsetbuf()\fP. 300.PP 301There are three \fIstandard streams\fP: 302\f5sfstdin\fP for input (file descriptor \f50\fP on UNIX systems), 303\f5sfstdout\fP for normal output (file descriptor \f51\fP), and 304\f5sfstderr\fP for error output (file descriptor \f52\fP). 305 306.PP 307.Ss "LIBRARIES" 308.PP 309This version of Sfio can be built and used for both uni-threaded and multi-threaded 310environments. In the former case, streams are not protected from 311simultaneous accesses by different threads. In the latter case, a stream 312is typically locked with a mutex during access so that another thread 313trying to access the same stream will block until the mutex is released. 314 315A program that does not use multiple threads can link with \fBlibsfio.a\fP 316while a program that uses multiple threads should link with \fBlibsfio-mt.a\fP. 317The libraries \fBlibstdio.a\fP and \fBlibstdio-mt.a\fP provide 318corresponding Stdio functions to link with code already compiled using the 319native header \fBstdio.h\fP instead of the one provided by Sfio. 320 321.PP 322.Ss "DATA TYPES" 323.PP 324.Ss " Void_t*" 325This defines a type suitable to exchange 326data of unknown types between application and Sfio. 327\f5Void_t\fP is a macro defined as \f5void\fP for ANSI-C and C++ and 328\f5char\fP for other compilation environments. 329.PP 330.Ss " Sfoff_t" 331This defines an integral type suitable to address 332the largest possible file extent. 333.PP 334.Ss " Sfulong_t, Sflong_t, Sfdouble_t" 335These are respectively the largest 336unsigned integer, signed integer, and floating point value types on the local platform. 337.PP 338.Ss " Sfio_t" 339This defines the type of a stream handle. 340.PP 341.Ss " Sfdisc_t" 342.Ss " ssize_t (*Sfread_f)(Sfio_t*, Void_t*, size_t, Sfdisc_t*)" 343.Ss " ssize_t (*Sfwrite_f)(Sfio_t*, const Void_t*, size_t, Sfdisc_t*)" 344.Ss " Sfoff_t (*Sfseek_f)(Sfio_t*, Sfoff_t, int, Sfdisc_t*)" 345.Ss " int (*Sfexcept_f)(Sfio_t*, int, Void_t*, Sfdisc_t*)" 346\f5Sfdisc_t\fP defines a stream discipline structure. 347\f5Sfread_f\fP, \f5Sfwrite_f\fP and \f5Sfseek_f\fP are the types 348of discipline functions to replace the system calls: 349\f5read(2)\fP, \f5write(2)\fP and \f5lseek(2)\fP. 350\f5Sfexcept_f\fP is the type of an event-handling function. 351See \f5sfdisc()\fP for more details. 352.PP 353.Ss " Sffmt_t" 354.Ss " int (*Sffmtext_f)(Sfio_t*, Void_t*, Sffmt_t*)" 355.Ss " int (*Sffmtevent_f)(Sfio_t*, int, Void_t*, Sffmt_t*)" 356\f5Sffmt_t\fP defines a formatting environment that can be used 357to extend scanning and printing in the \f5sfprint()/sfscanf()\fP 358functions. \f5Sffmtext_f\fP and \f5Sffmtevent_f\fP define the types 359of extension functions definable in \f5Sffmt_t\fP. 360See \f5Sffmt_t\fP below for more details. 361.PP 362.Ss " SFIO_VERSION" 363This is a macro value of type \f5long int\fP that defines 364the current version number of Sfio. For example, the Sfio2000's 365version number is \f520000515L\fP 366(which also indicates its latest version date: 05/15/2000). 367 368.Ss "BIT FLAGS" 369A number of bit flags control stream operations. 370They are set either at stream initialization or by calling \f5sfset()\fP. 371Following are the flags: 372.Tp 373\f5SF_STRING\fP: 374The stream is memory-based. 375.Tp 376\f5SF_READ\fP, \f5SF_WRITE\fP, \f5SF_APPENDWR\fP (\f5SF_APPEND\fP): 377Flags \f5SF_READ\fP and \f5SF_WRITE\fP indicate readability and writability. 378Flag \f5SF_APPENDWR\fP asserts that the stream is a file opened in append mode 379(see \f5open(2)\fP and \f5fcntl(2)\fP) 380so that data is always output at the end of file. 381On systems without direct support for append mode, 382Sfio uses \f5lseek(2)\fP or its discipline replacement 383to approximate this behavior. 384.Tp 385\f5SF_LINE\fP: 386The stream is line-oriented. 387For a \f5SF_WRITE\fP stream, 388this means that buffered data is flushed 389whenever a new-line character, \f5\en\fP, is output. 390For a \f5SF_READ\fP stream, \f5SF_LINE\fP is only 391significant during calls to functions in the \f5sfscanf()\fP family. 392\f5SF_LINE\fP is set on initialization of 393any stream representing a terminal device. 394.Tp 395\f5SF_SHARE\fP, \f5SF_PUBLIC\fP: 396Flag \f5SF_SHARE\fP means that the underlying file descriptor 397is shared by independent entities (for example, multiple processes). 398 399For a seekable file stream, \f5SF_SHARE\fP means that 400the logical stream and the physical file positions will be made the same 401before a system call to perform physical I/O. 402There are different possibilities. 403If \f5SF_PUBLIC\fP is not set, 404the physical file position is made equal to the logical stream position. 405If \f5SF_PUBLIC\fP is set, there are two cases. 406If the physical file position has changed from its last known position, 407the logical stream position is made equal to the new physical file position. 408Finally, if the physical file location remains the same as its last known position, 409the physical file position is made the same as the logical stream position. 410 411For an unseekable stream (e.g., pipes or terminal devices), if possible, 412\f5SF_SHARE\fP means that 413the block and record I/O operations (\f5sfread()\fP, \f5sfwrite()\fP, \f5sfmove()\fP, 414\f5sfgetr()\fP, \f5sfputr()\fP, \f5sfreserve()\fP, \f5sfscanf()\fP 415and \f5sfvprintf()\fP) will ensure: 416(1) after each writing operation, the stream is synchronized and 417(2) each reading operation only reads the requested amount. 418Note, however, that (2) is not always possible 419without proper OS facilities such as \f5recv(2)\fP or \f5streamio(4)\fP. 420 421A standard stream that is seekable will be initialized with \f5SF_SHARE|SF_PUBLIC\fP. 422.Tp 423\f5SF_MALLOC\fP: 424The stream buffer was obtained via \f5malloc(3)\fP 425and can be reallocated or freed. 426.Tp 427\f5SF_STATIC\fP: 428The stream structure should not be freed when closed (\f5sfclose()\fP). 429This flag is used by an applications that allocate their own 430stream structures. Such applications must use the header file \f5sfio_t.h\fP 431instead of \f5sfio.h\fP. 432.Tp 433\f5SF_IOCHECK\fP: 434If the stream has a discipline exception handler, 435exceptions will be raised in \f5sfsync()\fP, \f5sfpurge()\fP 436or before a system call \f5read(2)\fP or \f5write(2)\fP (see \f5sfdisc()\fP). 437.Tp 438\f5SF_WHOLE\fP: 439This flag guarantees that data written in any single \f5sfwrite()\fP or 440\f5sfputr()\fP call will always be output as a whole to the output device. 441This is useful in certain applications (e.g., networking) where a complex object 442must be output without being split in different system calls. 443Note that the respective stream still buffers data as much as the buffer can accomodate. 444.Tp 445\f5SF_MTSAFE\fP: 446This flag indicates that the respective stream may be accessed by more than one threads. 447A mutex lock will be used to ensure that only one thread at a time can access 448the stream. Note that this flag can only be set at stream opening time 449(see \f5sfopen()\fP, \f5sfpopen()\fP and \f5sfnew()\fP). 450Certain fast macro functions such as \f5sfgetc()\fP and \f5sfputc()\fP will 451no longer behave as macros. Thus, an application that requires such fast macro functions 452should leave \f5SF_MTSAFE\fP off and performs explicit locking with \f5sfmutex()\fP. 453.Tp 454\f5SF_IOINTR\fP: 455This flag indicates that I/O system calls should not be resumed 456after being interrupted by signals. It is useful for 457aborting I/O operations on such interruptions. Note, however, 458than certain operating systems (e.g., BSD Unix systems) may automatically 459resume interrupted system calls outside the scope of the library. On such systems, 460\f5SF_IOINTR\fP will be ineffective. 461 462.PP 463.Ss "OPENING/CLOSING STREAMS" 464.PP 465.Ss " Sfio_t* sfnew(Sfio_t* f, Void_t* buf, size_t size, int fd, int flags)" 466This function creates or renews a stream. 467It returns the new stream on success and \f5NULL\fP on error. 468.Tp 469\f5f\fP: 470If \f5f\fP is \f5NULL\fP, a new stream is created. 471Otherwise, \f5f\fP is reused. 472In this case, if \f5flags\fP does not have \f5SF_EOF\fP, 473\f5f\fP shall be closed via \f5sfclose()\fP before being reused. 474During a stream renewal, buffer, pool and discipline stack are preserved. 475Note that, except for \f5SF_STATIC\fP streams, 476renewing a stream already closed will result in undefined behavior. 477.Tp 478\f5buf\fP, \f5size\fP: 479These determine a buffering scheme. 480See \f5sfsetbuf()\fP for more details. 481.Tp 482\f5fd\fP: 483If \f5SF_STRING\fP is specified in \f5flags\fP, this is ignored. 484Otherwise, \f5fd\fP is a file descriptor (e.g., from \f5open(2)\fP) 485to use for raw data I/O. 486Note that Sfio supports unseekable file descriptors 487opened for both read and write, e.g., sockets. 488.Tp 489\f5flags\fP: 490This is composed from \f5SF_EOF\fP and 491bit values defined in the \fBBIT FLAGS\fP section. 492Note, in particular, that a multi-threaded application should 493set the bit \f5SF_MTSAFE\fP to protect the new stream from 494being simultaneously accessed by multiple threads. 495 496.Ss " Sfio_t* sfopen(Sfio_t* f, const char* string, const char* mode)" 497 498If \f5string\fP is \f5NULL\fP, 499\f5f\fP is a file stream and 500\f5mode\fP does not imply a string stream, 501\f5sfopen()\fP changes the modes of \f5f\fP according to \f5mode\fP. 502In this case, \f5sfopen()\fP returns \f5f\fP on success and \f5NULL\fP on error. 503This somewhat unusual usage of \f5sfopen()\fP is good for 504resetting certain predefined modes in standard streams including 505\fItext/binary\fP and \fIappend\fP that are inherited from some parent process. 506Note also that \f5SF_READ\fP and \f5SF_WRITE\fP can only be reset if the stream 507is not yet initialized. 508 509\f5sfopen()\fP is normally used to create a new stream or renew a stream. 510In this case, it returns the new stream on success and \f5NULL\fP on error. 511Below are the meanings of the arguments: 512.Tp 513\f5f\fP: 514This is treated as in \f5sfnew()\fP. 515.Tp 516\f5string\fP: 517This is a file name or a string to perform I/O on. 518See above for when this is \f5NULL\fP. 519.Tp 520\f5mode\fP: 521This is composed from the set of letters \f5{s, r, w, +, a, b, t, x, m, u}\fP. 522When conflicting options are present in the same \f5mode\fP string, 523the last one will take effect. 524 525\f5s\fP specifies opening a string stream. 526\f5string\fP can be a null-terminated string or \f5NULL\fP. 527Specifying \f5s\fP alone is equivalent to specifying \f5sr\fP. 528If \f5s\fP is not specified, \f5string\fP defines a file name. 529 530\f5r\fP and \f5w\fP specify read and write modes. 531Write mode creates and/or truncates the given file to make an empty file. 532The \f5+\fP modifier indicates that the stream is opened for both read and write. 533 534\f5a\fP specifies append mode, i.e., data is always output at end of file. 535 536\f5b\fP and \f5t\fP specify binary and text modes. 537 538\f5x\fP specifies exclusive mode, i.e., 539a file opened for writing should not already exist. 540 541\f5m\fP specifies that the stream needs to be protected from 542simultaneous accesses by multiple threads. 543This turns on the bit flag \f5SF_MTSAFE\fP. 544 545\f5u\fP specifies that the stream is guaranteed to be accessed 546by only one thread at a time. The bit flag \f5SF_MTSAFE\fP is left off. 547The absence of option \f5m\fP is the same as the presence of option \f5u\fP. 548 549.Ss " Sfio_t* sfpopen(Sfio_t* f, const char* cmd, const char* mode)" 550This function opens a stream that corresponds to the coprocess \f5cmd\fP. 551The argument \f5mode\fP should be composed from \f5r\fP, \f5w\fP, and \f5+\fP. 552The argument \f5f\fP, if not \f5NULL\fP, is a stream to be renewed (see \f5sfnew()\fP). 553\f5sfpopen()\fP returns the new stream or \f5NULL\fP on error. 554 555The standard input/output of \f5cmd\fP 556is connected to the application via a pipe if the stream is opened for writing/reading. 557If the stream is opened for both reading and writing, 558there will be two different associated file descriptors, one for each type of I/O 559(note the effect on \f5sffileno()\fP). 560 561On opening a coprocess for writing (i.e., \f5mode\fP contains \f5w\fP or \f5+\fP), 562the signal handler for \f5SIGPIPE\fP in the parent application 563will be set to \f5SIG_IGN\fP if it is \f5SIG_DFL\fP at that time. 564This protects the parent application from being accidentally killed 565on writing to a coprocess that closes its reading end. 566Applications that need to detect such write errors should use 567disciplines and exception handlers (see \f5sfdisc()\fP). 568 569The command \f5cmd\fP 570is executed by an \fIinterpreter\fP which is either \f5/bin/sh\fP 571or an executable command defined by the environment variable \f5SHELL\fP. 572In either case, the interpreter is invoked with 2 arguments, respectively \f5-c\fP 573and the given command \f5cmd\fP. When the interpreter is \f5/bin/sh\fP or 574\f5/bin/ksh\fP, \f5sfpopen()\fP may execute the command \f5cmd\fP itself 575if there are no shell meta-characters in \f5cmd\fP. 576 577.Ss " Sfio_t* sftmp(size_t size)" 578This function creates a stream for temporary data. 579It returns the new stream or \f5NULL\fP on error. 580 581A stream created by \f5sftmp()\fP can be completely or partially memory-resident. 582If \f5size\fP is \f5SF_UNBOUND\fP, the stream is a pure string stream. 583If \f5size\fP is zero, the stream is a pure file stream. 584Otherwise, the stream is first created as a string stream but when 585its buffer grows larger than \f5size\fP or on any attempt to change disciplines, 586a temporary file is created. 587Two environment variables, \f5TMPPATH\fP and \f5TMPDIR\fP, 588direct where temporary files are created. 589\f5TMPPATH\fP, if defined, 590specifies a colon-separated set of directories to be 591used in a round-robin fashion to create files. 592If \f5TMPPATH\fP is undefined, 593\f5TMPDIR\fP can be used to specify a single directory to create files. 594If neither of \f5TMPPATH\fP and \f5TMPDIR\fP are defined, \f5/tmp\fP is used. 595 596.Ss " int sfclose(Sfio_t* f)" 597This function closes the stream \f5f\fP and frees its resources. 598\f5SF_STATIC\fP should be used if the stream space is to be preserved. 599If \f5f\fP is the base of a stream stack (see \f5sfstack()\fP), 600all streams on the stack are closed. 601If \f5f\fP is a \f5sfpopen\fP-stream, 602\f5sfclose()\fP waits until the associated command terminates 603and returns its exit status. 604\f5sfclose()\fP returns \f5-1\fP for failure and \f50\fP for success. 605 606\f5SF_READ|SF_SHARE\fP and \f5SF_WRITE\fP streams 607are synchronized before closing (see \f5sfsync()\fP). 608If \f5f\fP has disciplines, 609their exception handlers will be called twice. 610The first exception handler call has the \f5type\fP argument as one of 611\f5SF_CLOSING\fP or \f5SF_NEW\fP (see \f5sfdisc()\fP.) 612The latter, \f5SF_NEW\fP is used when a stream is being closed via \f5sfnew()\fP 613so that it can be renewed. 614The second call uses \f5type\fP as \f5SF_FINAL\fP 615and is done after all closing operations have succeeded but before 616the stream itself is deallocated. 617In either case, if the exception handler returns a negative value, 618\f5sfclose()\fP will immediately return this value. 619If the exception handler returns a positive value, 620\f5sfclose()\fP will immediately return a zero value. 621 622.PP 623.Ss "THREAD SAFETY" 624.PP 625The libraries \f5libsfio.a\fP and \f5libstdio.a\fP (providing binary 626compatibility to Stdio-based code) only support uni-threaded code. 627Multi-threaded applications should link with 628\f5libsfio-mt.a\fP and \f5libstdio-mt.a\fP. 629When this is done, certain platforms may require additional 630thread libraries for linkage. For example, Linux, Irix and Solaris 631require \f5-lpthread\fP while HPUX requires \f5-lcma\fP. 632Aside from linkage differences, the Sfio API remains identical in all cases. 633 634Note that unlike Stdio streams which are in thread-safe mode by default. 635Sfio streams can be opened in either uni-threaded or multi-threaded mode. 636A uni-threaded stream is more efficient than a multi-threaded one. 637For example, functions such as \f5sfgetc()\fP and \f5sfputc()\fP 638remain as macro or inline functions for a uni-threaded stream while 639they will act as full function calls in a multi-threaded case. 640The three standard streams \f5sfstdin/sfstdout/sfstderr\fP 641are in multi-threaded mode by default 642(however, see \f5sfopen()\fP for how this may be changed). 643Other Sfio streams are normally opened uni-threaded unless 644the flag \f5SF_MTSAFE\fP or the option \f5m\fP were specified. 645Stdio-based code can also make a Stdio stream uni-threaded by 646using the option \f5u\fP when opening a file. 647 648.PP 649.Ss "int sfmutex(Sfio_t* f, int type)" 650This function acquires or releases a mutex 651(mutually exclusive) lock on the stream \f5f\fP. 652It can be used by a thread to serialize a sequence of I/O operations 653executed together in some critical section. 654\f5sfmutex()\fP is implicitly used by 655all Sfio operations on a stream with the flag \f5SF_MTSAFE\fP to 656protect it from concurrent accesses via multiple threads. 657\f5sfmutex()\fP returns \f50\fP on success and some non-zero value on failure. 658 659Each stream has a lock count which starts at \f50\fP. 660When the count is positive, a single thread holds the stream. 661Only this thread can further lock or unlock the stream. 662A different thread attempting to acquire such a locked stream will suspend 663until the lock count returns to \f50\fP. 664Each successful locking operation increases the lock count 665while each successful unlocking operation decreases it, 666thus, allowing nesting of matching lock/unlock operations. 667 668The \f5type\fP argument of \f5sfmutex()\fP takes on the below values: 669.Tp 670\f5SFMTX_LOCK\fP: 671Locking a stream if it is unlocked or increasing the lock count of the stream 672if it is already locked by the same thread. This call will block until it is 673possible to lock the stream. 674.Tp 675\f5SFMTX_TRYLOCK\fP: 676This is the non-blocking version of \f5SFMTX_LOCK\fP. 677If the stream is already locked by a different thread, \f5sfmutex()\fP will 678immediately return with an error status. 679.Tp 680\f5SFMTX_UNLOCK\fP: 681Decreasing the lock count and releasing the stream when the lock count reaches 0. 682An attempt to unlock a stream without a previously successful lock may 683result in undefined behavior in certain implementations. 684The current Sfio implementation returns an error status. 685.Tp 686\f5SFMTX_CLRLOCK\fP: 687Resetting the lock count to \f50\fP and releasing the stream. 688As with \f5SFMTX_LOCK\fP, 689an attempt to clear the lock count without a previously successful lock 690may result in undefined behavior. 691.PP 692.Ss "INPUT/OUPUT OPERATIONS" 693.PP 694.Ss " int sfgetc(Sfio_t* f)" 695.Ss " int sfputc(Sfio_t* f, int c)" 696These functions read/write a byte from/to stream \f5f\fP. 697\f5sfgetc()\fP returns the byte read or \f5-1\fP on error. 698\f5sfputc()\fP returns \f5c\fP on success and \f5-1\fP on error. 699 700.Ss " ssize_t sfnputc(Sfio_t* f, int c, size_t n)" 701This function attempts to write the byte \f5c\fP to \f5f\fP \f5n\fP times. 702It returns the number of bytes actually written or \f5-1\fP on failure. 703 704.Ss " int sfungetc(Sfio_t* f, int c)" 705This function pushes the byte \f5c\fP back into \f5f\fP. 706If \f5c\fP matches the byte immediately before the current position in buffered data, 707the current position is simply backed up (note the effect on \f5sftell()\fP and 708\f5sfseek()\fP). There is no theoretical limit on the number of bytes that 709can be pushed back into a stream. Pushed back bytes not part of 710buffered data will be discarded on any operation that implies 711buffer synchronization. 712\f5sfungetc()\fP returns \f5c\fP on success and \f5-1\fP on failure. 713 714.Ss " Sfulong_t sfgetm(Sfio_t* f, Sfulong_t max)" 715.Ss " int sfputm(Sfio_t* f, Sfulong_t v, Sfulong_t max)" 716These functions read and write \f5Sfulong_t\fP values 717encoded in a portable format given that the values are at most \f5max\fP. 718Portability across a write architecture and a read architecture 719requires that the bit order in a byte is the same on both architectures and 720the written value is storable in an \f5Sfulong_t\fP on the read architecture. 721\f5sfgetm()\fP returns the value read or \f5-1\fP on error. 722\f5sfputm()\fP returns the number of bytes written or \f5-1\fP on error. 723 724.Ss " Sfulong_t sfgetu(Sfio_t* f)" 725.Ss " int sfputu(Sfio_t* f, Sfulong_t v)" 726These functions read and write \f5Sfulong_t\fP values 727in a compact variable-length portable format. 728Portability across a write architecture and a read architecture 729requires that the bit order in a byte is the same on both architectures and 730the written value is storable in an \f5Sfulong_t\fP on the read architecture. 731\f5sfgetu()\fP returns the value read or \f5-1\fP on error. 732\f5sfputu()\fP returns the number of bytes written or \f5-1\fP on error. 733See also \f5sfulen()\fP. 734 735.Ss " Sflong_t sfgetl(Sfio_t* f)" 736.Ss " int sfputl(Sfio_t* f, Sflong_t v)" 737These functions are similar to \f5sfgetu()\fP and \f5sfputu()\fP 738but for reading and writing (signed) \f5Sflong_t\fP values. 739See also \f5sfllen()\fP. 740 741.Ss " Sfdouble_t sfgetd(Sfio_t* f)" 742.Ss " int sfputd(Sfio_t* f, Sfdouble_t v)" 743These functions read and write \f5Sfdouble_t\fP values. 744In this case, portability depends on the input and output architectures 745having the same floating point value representation. 746Values are coded and decoded using \f5ldexp(3)\fP and \f5frexp(3)\fP 747so they are constrained to the sizes supported by these functions. 748See also \f5sfdlen()\fP. 749 750.Ss " char* sfgetr(Sfio_t* f, int rsc, int type)" 751This function reads a record of data ending in the record separator \f5rsc\fP. 752After \f5sfgetr()\fP returns, the length of the record even if it is incomplete 753can be retrieved with \f5sfvalue()\fP. 754\f5sfgetr()\fP returns the record on success and \f5NULL\fP on error. 755See also \f5sfmaxr()\fP for limiting the amount of data read to construct a record. 756 757The \f5type\fP argument is composed of some subset of the below bit flags: 758.Tp 759\f5SF_STRING\fP: 760A null byte will replace the record separator to make the record into a C string. 761Otherwise, the record separator is left alone. 762.Tp 763\f5SF_LOCKR\fP: 764Upon successfully obtaining a record \f5r\fP, 765the stream will be locked from further access until it is released with 766a call \f5sfread(f,r,0)\fP. 767.Tp 768\f5SF_LASTR\fP: 769This should be used only after a failed \f5sfgetr()\fP to retrieve 770the last incomplete record. In this case, \f5rsc\fP is ignored. 771 772.Ss " ssize_t sfputr(Sfio_t* f, const char* s, int rsc)" 773This function writes the null-terminated string \f5s\fP to \f5f\fP. 774If \f5rsc\fP is non-negative, \f5(unsigned char)rsc\fP is output after the string. 775\f5sfputr()\fP returns the number of bytes written or \f5-1\fP on failure. 776 777.Ss " Sfoff_t sfmove(Sfio_t* fr, Sfio_t* fw, Sfoff_t n, int rsc)" 778This function moves objects 779from input stream \f5fr\fP to output stream \f5fw\fP. 780\f5sfmove()\fP returns the number of objects moved or \f5-1\fP on failure. 781 782An object can be either a byte if the record separator argument 783\f5rsc\fP is negative or a record of \f5rsc\fP is non-negative. 784In the latter case, a record is incomplete if it does not end in \f5rsc\fP. 785Generally speaking, a stream can have at most one incomplete record. 786If \f5n\fP is negative, all complete objects of \f5fr\fP will be moved. 787Otherwise, \f5n\fP indicates the number of objects to move. 788If either \f5fr\fP or \f5fw\fP is \f5NULL\fP, it acts 789as if it is a stream corresponding to \f5/dev/null\fP, 790the UNIX device that has no read data and throws away any write data. 791For example, the call \f5sfmove(f,(Sfio_t*)0,(Sfoff_t)(-1),'\en')\fP 792counts the number of complete lines in stream \f5f\fP. 793 794.Ss " ssize_t sfread(Sfio_t* f, Void_t* buf, size_t n)" 795This function reads up to \f5n\fP bytes from \f5f\fP into buffer \f5buf\fP. 796It returns the number of bytes actually read or \f5-1\fP on error. 797 798.Ss " ssize_t sfwrite(Sfio_t* f, const Void_t* buf, size_t n)" 799This function writes \f5n\fP bytes from \f5buf\fP to \f5f\fP. 800If \f5f\fP is \f5SF_STRING\fP, and the buffer is not large enough, 801an \f5SF_WRITE\fP exception shall be raised. 802\f5sfwrite()\fP returns the number of bytes written or \f5-1\fP on failure. 803 804.Ss " Sfoff_t sfseek(Sfio_t* f, Sfoff_t offset, int type)" 805This function sets a new I/O position for \f5f\fP. 806It returns the new position or \f5-1\fP on failure. 807 808If the stream is a \f5SF_STRING\fP stream and the new 809address is beyond the current buffer extent, 810an \f5SF_SEEK\fP exception will be raised (see \f5sfdisc()\fP). 811 812The new position is determined based on \f5offset\fP and 813\f5type\fP which is composed from the bit flags: 814.Tp 815\f50\fP or \f5SEEK_SET\fP: 816\f5offset\fP is the desired position. 817.Tp 818\f51\fP or \f5SEEK_CUR\fP: 819\f5offset\fP is relative to the current position (see \f5SF_PUBLIC\fP below). 820.Tp 821\f52\fP or \f5SEEK_END\fP: 822\f5offset\fP is relative to the physical end of file. 823.Tp 824\f5SF_SHARE\fP: 825The stream is treated as if it has the control bit \f5SF_SHARE\fP on. 826This implies that a system call seek will be done to ensure that the 827location seeking to is valid. 828.Tp 829\f5SF_PUBLIC\fP: 830The stream is treated as if it has the control bit \f5SF_PUBLIC\fP on. 831If the physical file position has changed from its last known location, 832the current position is taken as the new physical position. 833Otherwise, the current position is the logical stream position. 834 835.Ss " Void_t* sfreserve(Sfio_t* f, ssize_t n, int type)" 836This function reserves a data block from the stream \f5f\fP. 837It returns the reserved data block on success and \f5NULL\fP on failure. 838 839If \f5f\fP is a \f5SF_READ\fP stream, the data block is a segment of input data. 840If \f5f\fP is a \f5SF_WRITE\fP stream, the data block is a buffer 841suitable for writing output data. 842For consistency, if \f5f\fP is opened with \f5SF_READ|SF_WRITE\fP, 843it will normally be treated as if it is a \f5SF_READ\fP stream 844(see \f5sfset()\fP for forcing a particular mode) but the returned 845buffer can also be written into (more below). 846However, it is possible to bias to \f5SF_WRITE\fP when the \f5type\fP 847argument is non-negative by adding the \f5SF_WRITE\fP bit \f5type\fP. 848In any case, a reserved data block is guaranteed to be valid only until 849a future access to the stream \f5f\fP. 850 851When \f5f\fP is \f5SF_READ\fP, \f5SF_SHARE\fP and unseekable, 852\f5sfreserve()\fP will attempt to peek at input data without 853consuming it. This enables separate processes to share in reading 854input from unseekable file descriptors (e.g., pipes or devices). 855However, this use of \f5sfreserve()\fP may fail 856on certain platforms that do not properly support 857peeking on unseekable file descriptors. 858 859After a \f5sfreserve()\fP call, whether or not it succeeds, 860\f5sfvalue(f)\fP gives the size of the available data block. 861Any partially reserved data block after a failed \f5sfreserve()\fP 862call can be obtained in another \f5sfreserve()\fP call with the argument 863\f5type\fP being \f5SF_LASTR\fP. The second argument \f5n\fP 864to \f5sfreserve()\fP will be ignored in this case. 865 866A \f5sfreserve()\fP call is successful if it can obtain a data block 867of size at least the absolute value of \f5n\fP. 868For a \f5SF_READ\fP atream, the argument \f5n\fP is treated as follows: 869.Tp 870\f5n < 0\fP: 871\f5sfreserve()\fP attempts to get \fIat least\fP \f5|n|\fP bytes 872into the buffer. 873.Tp 874\f5n == 0\fP: 875If the argument \f5type\fP is \f50\fP, 876\f5sfreserve()\fP attempts to get \fIat least\fP \f51\fP byte into the buffer 877but does not consume it (as consistent with \f5n == 0\fP). 878If \f5type != 0\fP, no attempt will be made to read data into the buffer. 879For example, the call \f5sfreserve(f, 0, -1)\fP only returns the buffer status, 880i.e., size of existing buffered data and pointer to such data, if any. 881The call \f5sfreserve(f, 0, SF_LOCKR)\fP is similar but also locks the stream. 882.Tp 883\f5n > 0\fP: 884\f5sfreserve()\fP will use attempt to get \fIat most\fP \f5n\fP bytes into 885the buffer. Further, if \f5type == \f5SF_LOCKR\fP (see below), read attempts 886end on a positive amount. 887 888For a successful reservation, the argument \f5type\fP dictates treatment 889as follows: 890.Tp 891\f5type == SF_LASTR\fP: 892After a \f5sfreserve()\fP call with \f5type != SF_LOCKR\fP fails, 893there may be some left over data not accessible via conventional Sfio calls. 894Immediately after such a failed call, 895another call to \f5sfreserve\fP with \f5type == SF_LASTR\fP will return any left over 896data and also advance the stream I/O position by the amount of returned data. 897.Tp 898\f5type < 0\fP: 899If \f5n > 0\fP, the stream I/O position is advanced by \f5n\fP. 900If \f5n < 0\fP, the stream I/O position is advanced by the amount 901of available data. 902For example, a successful \f5sfreserve(f, -1, -1)\fP call will return a 903buffer of data and simultanously advance the stream I/O position by the amount 904indicated by \f5sfvalue(f)\fP. 905.Tp 906\f5type == SF_LOCKR\fP: 907The stream I/O position remains unchanged. 908In addition, \f5f\fP will be locked from further access. 909As appropriate to the stream type (\f5SF_READ\fP, \f5SF_WRITE\fP or both), 910\f5f\fP can be unlocked later 911with one of \f5sfread(f,rsrv,size)\fP or \f5sfwrite(f,rsrv,size)\fP 912where \f5rsrv\fP is the reserved data block and \f5size\fP is the amount of 913data to be consumed. For example, if \f5f\fP is a locked \f5SF_READ\fP stream, 914the call \f5sfread(f,rsrv,1)\fP will reopen the stream and simultaneously 915advance the stream I/O position by \f51\fP. 916Finally, a stream opened for both reading and writing 917can release the lock with either call (with associated operational semantics!) 918For example, the below code reads 10 bytes of data from a stream 919opened with both \f5SF_READ\fP and \f5SF_WRITE\fP, modifies the data in place, 920then rewrites the new data back to the stream: 921 922.nf 923.ft 5 924 rsrv = sfreserve(f, 10, 1); 925 for(i = 0; i < 10; ++i) 926 rsrv[i] = toupper(rsrv[i]); 927 sfwrite(f, rsrv, 10); 928.ft 1 929.fi 930 931.ne 6 932.PP 933.Ss "DATA FORMATTING" 934.PP 935Data printing and scanning are done via the 936\f5sfprintf()\fP and \f5sfscanf()\fP family of functions. 937These functions are similar to their 938ANSI-C \f5fprintf()\fP and \f5fscanf()\fP counterparts. 939However, the Sfio versions have been extended for both portability and generality. 940In particular, a notion of a formatting environment stack is introduced. 941Each formatting element on the stack 942defines a separate \fIformatting pair\fP of a format specification string, 943\f5char* format\fP (the usual second argument in the formatting 944functions), and an argument list, \f5va_list args\fP (the third argument 945in functions \f5sfvprintf()\fP and \f5sfvscanf()\fP). 946A formatting environment element may also specify extension functions 947to obtain or assign arguments and to provide new semantics for pattern processing. 948To simplify the description below, whenever we talk 949about an argument list, unless noted otherwise, 950it is understood that this means either the true 951argument list when there is no extension function or the action to be taken 952by such a function in processing arguments. 953The manipulation of the formatting environment stack is done 954via the pattern \f5!\fP discussed below. 955 956.Ss "%! and Sffmt_t" 957The pattern \f5%!\fP manipulates the formatting environment stack to 958(1) change the top environment to a new environment, 959(2) stack a new environment on top of the current top, 960or (3) pop the top environment. 961The bottom of the environment stack always contains a virtual environment with the 962original formatting pair and without any extension functions. 963 964The top environment of a stack, say \f5fe\fP, is automatically popped whenever 965its format string is completely processed. 966In this case, its event-handling function (if any) is called 967as \f5(*eventf)(f,SF_FINAL,NIL(Void_t*),fe)\fP. 968The top environment 969can also be popped by giving an argument \f5NULL\fP to \f5%!\fP 970or by returning a negative value in an extension function. 971In these cases, the event-handling function is called 972as \f5(*eventf)(f,SF_DPOP,form,fe)\fP where \f5form\fP is the remainder 973of the format string. A negative return value from the event handling function 974will prevent the environment from being popped. 975 976A formatting environment is a structure of type \f5Sffmt_t\fP 977which contains the following elements: 978 979.nf 980.ft 5 981 Sffmtext_f extf; /* extension processor */ 982 Sffmtevent_f eventf; /* event handler */ 983 984 char* form; /* format string to stack */ 985 va_list args; /* corresponding arg list */ 986 987 int fmt; /* pattern being processed */ 988 ssize_t size; /* object size */ 989 int flags; /* formatting control flags */ 990 int width; /* width of field */ 991 int precis; /* precision required */ 992 int base; /* conversion base */ 993 994 char* t_str; /* extfdata string */ 995 int n_str; /* length of t_str */ 996.ft 1 997.fi 998 999The first four elements of \f5Sffmt_t\fP must be defined by the application 1000before the structure is passed to a formatting function. 1001The two function fields should not be changed during processing. 1002Other elements of \f5Sffmt_t\fP are set by the respective formatting function 1003before it calls the extension function \f5Sffmt_t.extf\fP and, subsequently, 1004can be modified by this function to redirect formatting or scanning. 1005For example, consider a call from a \f5sfprintf()\fP function to process an 1006unknown pattern \f5%t\fP (which we may take to mean ``time'') based on a 1007formatting environment \f5fe\fP. 1008\f5fe->extf\fP may reset \f5fe->fmt\fP to `\f5d\fP' upon returing 1009to cause \f5sfprintf()\fP to process the value being formatted as an integer. 1010 1011Below are the fields of \f5Sffmt_t\fP: 1012.Tp 1013\f5extf\fP: 1014\f5extf\fP is a function to extend scanning and formatting patterns. 1015Its usage is discussed below. 1016.Tp 1017\f5eventf\fP: 1018This is a function to process events as discussed earlier. 1019.Tp 1020\f5form\fP and \f5args\fP: 1021This is the formatting pair of a specification string and corresponding argument list. 1022When an environment \f5fe\fP is being inserted into the stack, 1023if \f5fe->form\fP is \f5NULL\fP, the top environment is changed to \f5fe\fP 1024and its associated extension functions 1025but processing of the current formatting pair continues. 1026On the other hand, if \f5fe->form\fP is not \f5NULL\fP, 1027the new environment is pushed onto the stack 1028so that pattern processing will start with the new formatting pair as well as 1029any associated extension functions. 1030During processing, whenever \f5extf\fP is called, 1031\f5form\fP and \f5args\fP will be set to the current values of 1032the formatting pair in use. 1033.Tp 1034\f5fmt\fP: 1035This is set to the pattern being processed or one of '.', 'I', '('. 1036.Tp 1037\f5size\fP: 1038This is the size of the object being processed. 1039.Tp 1040\f5flags\fP: 1041This is a collection of bits defining the formatting flags specified for the pattern. 1042The bits are: 1043 1044\f5SFFMT_LEFT\fP: Flag \f5-\fP in \f5sfprintf()\fP. 1045 1046\f5SFFMT_SIGN\fP: Flag \f5+\fP in \f5sfprintf()\fP. 1047 1048\f5SFFMT_BLANK\fP: Flag \fIspace\fP in \f5sfprintf()\fP. 1049 1050\f5SFFMT_ZERO\fP: Flag \f50\fP in \f5sfprintf()\fP. 1051 1052\f5SFFMT_THOUSAND\fP: Flag \f5'\fP in \f5sfprintf()\fP. 1053 1054\f5SFFMT_LONG\fP: Flag \f5l\fP in \f5sfprintf()\fP and \f5sfscanf()\fP. 1055 1056\f5SFFMT_LLONG\fP: Flag \f5ll\fP in \f5sfprintf()\fP and \f5sfscanf()\fP. 1057 1058\f5SFFMT_SHORT\fP: Flag \f5h\fP in \f5sfprintf()\fP and \f5sfscanf()\fP. 1059 1060\f5SFFMT_LDOUBLE\fP: Flag \f5L\fP in \f5sfprintf()\fP and \f5sfscanf()\fP. 1061 1062\f5SFFMT_IFLAG\fP: flag \f5I\fP in \f5sfprintf()\fP and \f5sfscanf()\fP. 1063 1064\f5SFFMT_ALTER\fP: Flag \f5#\fP in \f5sfprintf()\fP and \f5sfscanf()\fP. 1065 1066\f5SFFMT_SKIP\fP: Flag \f5*\fP in \f5sfscanf()\fP. 1067 1068\f5SFFMT_ARGPOS\fP: This indicates argument processing for \f5pos$\fP. 1069 1070\f5SFFMT_VALUE\fP: This is set by \f5fe->extf\fP 1071to indicate that it is returning a value to be formatted or 1072the address of an object to be assigned. 1073 1074.Tp 1075\f5width\fP: 1076This is the field width. 1077.Tp 1078\f5precis\fP: 1079This is the precision. 1080.Tp 1081\f5base\fP: 1082This is the conversion base. 1083.Tp 1084\f5t_str\fP and \f5n_str\fP: 1085This is the type string and its size. 1086 1087.Ss " int (*Sffmtext_f)(Sfio_t* f, Void_t* v, Sffmt_t* fe)" 1088This is the type of the extension function \f5fe->extf\fP to process 1089patterns and arguments. 1090Arguments are always processed in order and 1091\f5fe->extf\fP is called exactly once per argument. 1092Note that, when \f5pos$\fP (below) is not used anywhere in a format string, 1093each argument is used exactly once per a corresponding pattern. 1094In that case, \f5fe->extf\fP is called 1095as soon as the pattern is recognized and before any scanning or formatting. 1096On the other hand, when \f5pos$\fP is used in a format string, 1097an argument may be used multiple times. 1098In this case, all arguments shall be processed in order 1099by calling \f5fe->extf\fP exactly once per argument before any pattern processing. 1100This case is signified by the flag \f5SFFMT_ARGPOS\fP in \f5fe->flags\fP. 1101 1102In addition to the predefined formatting patterns and other application-defined 1103patterns, \f5fe->extf\fP may be called with \f5fe->fmt\fP being one 1104of `\f5(\fP' (left parenthesis), `\f5.\fP' (dot), and `\f5I\fP'. 1105 1106The left parenthesis requests a string to be used as the \f5extfdata\fP string discussed below. 1107In this case, upon returning, \f5fe->extf\fP should set the \f5fe->size\fP field 1108to be the length of the string or a negative value to indicate a null-terminated string. 1109 1110The `\f5I\fP' requests an integer to define the object size. 1111 1112The dot requests an integer for width, precision, base, or a separator. 1113In this case, the \f5fe->size\fP field will indicate how many dots have appeared 1114in the pattern specification. Note that, if the actual conversion pattern is 'c' or 's', 1115the value \f5*form\fP will be one of these characters. 1116.Tp 1117\f5f\fP: 1118This is the input/output stream in the calling formatting function. 1119During a call to \f5fe->extf\fP, the stream shall be unlocked 1120so that \f5fe->extf\fP can read from or write to it as appropriate. 1121.Tp 1122\f5v\fP: 1123For both \f5sfscanf()\fP and \f5sfprintf()\fP functions, 1124\f5v\fP points to a location suitable for storing any scalars or pointers. 1125On return, \f5fe->extf\fP treats \f5v\fP as discussed below. 1126.Tp 1127\f5fe\fP: 1128This is the current formatting environment. 1129.PP 1130The return value \f5rv\fP of \f5fe->extf\fP directs further processing. 1131There are two cases. 1132When \f5pos$\fP is present, a negative return value means to ignore \f5fe\fP 1133in further argument processing while a non-negative return value is treated 1134as the case \f5rv == 0\fP below. 1135When \f5pos$\fP is not present, \f5fe->extf\fP is called per argument 1136immediately before pattern processing and its return values are treated 1137as below: 1138.Tp 1139\f5rv < 0:\fP 1140The environment stack is immediately popped. 1141.Tp 1142\f5rv == 0:\fP 1143The extension function has not consumed (in a scanning case) or 1144output (in a printing case) data out of or into the given stream \f5f\fP. 1145The fields \f5fmt\fP, \f5flags\fP, \f5size\fP, 1146\f5width\fP, \f5precis\fP and \f5base\fP of \f5fe\fP 1147shall direct further processing. 1148 1149For \f5sfprintf()\fP functions, if \f5fe->flags\fP 1150has the bit \f5SFFMT_VALUE\fP, 1151\f5fe->extf\fP should have set \f5*v\fP to the value to be processed; 1152otherwise, a value should be obtained from the argument list. 1153Likewise, for \f5sfscanf()\fP functions, 1154\f5SFFMT_VALUE\fP means that 1155\f5*v\fP should have a suitable address; otherwise, 1156an address to assign value should be obtained from the argument list. 1157 1158When \f5pos$\fP is present, 1159if \f5fe->extf\fP changes \f5fe->fmt\fP, this pattern shall be used regardless of 1160the pattern defined in the format string. On the other hand, if \f5fe->fmt\fP 1161is unchanged by \f5fe->extf\fP, the pattern in the format string is used. 1162In any case, the effective pattern should be one of the standardly defined pattern. 1163Otherwise, it shall be treated as unmatched. 1164.Tp 1165\f5rv > 0:\fP 1166The extension function has accessed the stream \f5f\fP 1167to the extent of \f5rv\fP bytes. 1168Processing of the current pattern ceases except that, 1169for scanning functions, if \f5fe->flags\fP does not contain 1170the bit \f5SFFMT_SKIP\fP, the assignment count shall increase by 1. 1171 1172.Ss "void va_copy(va_list to, va_list fr)" 1173This macro function portably copies the argument list \f5fr\fP to 1174the argument list \f5to\fP. It should be used to set the field \f5Sffmt_t.args\fP. 1175 1176.Ss "long sffmtversion(Sffmt_t* fe, int type)" 1177This macro function initializes 1178the formatting environment \f5fe\fP with a version number if \f5type\fP is 1179non-zero. Otherwise, it returns the current value of the version number of \f5fe\fP. 1180This is useful for applications to find out 1181when the format of the structure \f5Sffmt_t\fP changes. 1182Note that the version number corresponds to the Sfio version number 1183which is defined in the macro value \f5SFIO_VERSION\fP. 1184 1185.Ss " int sfprintf(Sfio_t* f, const char* format, ...);" 1186.Ss " char* sfprints(const char* format, ...);" 1187.Ss " char* sfvprints(const char* format, va_list args);" 1188.Ss " ssize_t sfaprints(char** sp, const char* format, ...);" 1189.Ss " ssize_t sfvaprints(char** sp, const char* format, va_list args);" 1190.Ss " int sfsprintf(char* s, int n, const char* format, ...)" 1191.Ss " int sfvsprintf(char* s, int n, const char* format, va_list args);" 1192.Ss " int sfvprintf(Sfio_t* f, const char* format, va_list args);" 1193These functions format output data. 1194\f5sfprintf()\fP and \f5sfvprintf()\fP write to output stream \f5f\fP. 1195\f5sfsprintf()\fP and \f5sfvsprintf()\fP write to buffer \f5s\fP 1196which is of size \f5n\fP. 1197\f5sfprints()\fP and \f5sfvprints()\fP construct data in some Sfio-defined buffer. 1198\f5sfaprints()\fP and \f5sfvaprints()\fP are similar to \f5sfprints()\fP 1199and \f5sfvprints()\fP 1200but they return a string constructed via \f5malloc()\fP in \f5*sp\fP 1201and expect this string to be freed by the caller when no longer needed. 1202\f5sfvprintf()\fP is the underlying primitive for the other functions. 1203Except for \f5sfprints()\fP and \f5sfvprints()\fP 1204which return a null-terminated string or \f5NULL\fP, 1205other functions return the number of output bytes or \f5-1\fP on failure. 1206 1207The length of string constructed by \f5sfprints()\fP, \f5sfsprintf()\fP, or 1208\f5sfvsprintf()\fP can be retrieved by \f5sfslen()\fP. 1209.PP 1210The standard patterns are: 1211\f5n, s, c, %, h, i, d, p, u, o, x, X, g, G, e, E, f\fP and \f5!\fP. 1212Except for \f5!\fP which shall be described below, 1213see the ANSI-C specification of \f5fprintf(3)\fP for details on the other patterns. 1214Let \f5z\fP be some pattern type. A formatting pattern is defined as below: 1215 1216.nf 1217.ft 5 1218 %[pos$][flag][width][.precision[.base]][(extfdata)]z 1219.ft 1 1220.fi 1221 1222.Tp 1223\f5pos$\fP: 1224A pattern can specify which argument in the argument list to use. 1225This is done via \f5pos$\fP where \f5pos\fP is the argument position. 1226Arguments are numbered so that the first argument after \f5format\fP is at position 1. 1227If \f5pos\fP is not specified, the argument following the most recently used one 1228will be used. 1229The pattern \f5%!\fP (see below) cannot be used subsequent to a usage of \f5pos$\fP. 1230Doing so may cause unexpected behaviors. 1231.Tp 1232\f5flag\fP: 1233The flag characters are 1234\f5h\fP, \f5hh\fP, \f5l\fP, \f5ll\fP, \f5L\fP, \f5I\fP, \f5j\fP, \f5t\fP, \f5z\fP, 1235\f5\-\fP, \f5+\fP, \fIspace\fP, \f50\fP, \f5'\fP and \f5#\fP. 1236 1237Flag \f5I\fP defines the size or type of the object being formatted. 1238There are two cases: (1) \f5I\fP by itself and (2) \f5I\fP 1239followed by either a decimal number or `*'. 1240 1241In the first case, for integer and floating point patterns, 1242the object type is taken to be the largest appropriate type 1243(i.e., one of \f5Sflong_t\fP, \f5Sfulong_t\fP or \f5Sfdouble_t\fP). 1244For conversion specifiers \f5s\fP and \f5c\fP, the flag is ignored. 1245 1246In the second case, a given decimal value would define a size while 1247`*' would cause the size to be obtained from the argument list. 1248Then, if the conversion specifier is \f5s\fP, this size defines the 1249length of the string or strings being formatted (see the discussion of \f5base\fP below). 1250For integer and floating point patterns, 1251the size is used to select a type from one of the below lists as 1252indicated by the conversion specifier: 1253 1254.nf 1255.ft 5 1256 Sflong_t, long, int, short 1257 Sfulong_t, unsigned long, unsigned int, unsigned short 1258 Sfdouble_t, double, float 1259.ft 1 1260.fi 1261 1262The selection algorithm always matches types from left to right in any given list. 1263Although selection is generally based on sizes in bytes, 1264for compatibility with Microsoft-C, the size 64 1265is matched with an appropriate type with the same number of bits, if any. 1266If the given size does not match any of the listed types, 1267it shall match one of \f5int\fP, \f5unsigned int\fP, and \f5double\fP 1268as defined by the formatting pattern. 1269 1270Below are a few examples of using the \f5I\fP flag. 1271The first example prints an \f5Sflong_t\fP integer. 1272This example is actually not portable and 1273only works on platforms where \f5sizeof(Sflong_t)\fP is 8. 1274The second example shows how to that portably. 1275The third example specifies printing a string of length 16. 1276This length shall be used regardless of whether or not the given string 1277is shorter or longer than 16. 1278The last example shows the use of the pattern \f5%n\fP to assign the amount 1279of data already output into a \f5short\fP integer \f5n_output\fP. 1280 1281.nf 1282.ft 5 1283 sfprintf(sfstdout,"%I8d", Sflong_obj); 1284 sfprintf(sfstdout,"%I*d", sizeof(Sflong_obj), Sflong_obj); 1285 sfprintf(sfstdout,"%I*s", 16, s); 1286 sfprintf(sfstdout,"%d%I*n", 1001, sizeof(short), &n_output); 1287.ft 1 1288.fi 1289 1290Flags \f5h\fP, \f5l\fP, and \f5L\fP are the ANSI-C conventions to 1291select the types of input objects. 1292For example, \f5%hd\fP indicates a \f5short int\fP 1293while \f5%ld\fP indicates a \f5long int\fP. 1294 1295Flag \f5hh\fP addresses the byte value types, i.e., \f5char\fP and \f5unsigned char\fP. 1296 1297Flags \f5z\fP, \f5t\fP and \f5j\fP address respectively 1298the types \f5size_t\fP, \f5ptrdiff_t\fP and \f5Sflong_t\fP. 1299 1300Flags \f5ll\fP and \f5L\fP address respectively 1301the largest integer and floating value types, i.e., 1302\f5Sfulong_t\fP, \f5Sflong_t\fP, and \f5Sfdouble_t\fP. 1303 1304Flag \f5-\fP left-justifies data within the field (otherwise, right-justification). 1305 1306Flag \f5+\fP means that a signed conversion will always begin with a plus or minus sign. 1307 1308Flag \fIspace\fP is ignored if \f5+\fP is specified; otherwise, 1309it means that if the first character of a signed conversion 1310is not a sign or if the result is empty, a space will be prepended. 1311 1312Flag \f50\fP means padding with zeros on the left. 1313 1314Flag \f5'\fP outputs thousands-separator used by the current locale. 1315\f5setlocale(3)\fP should have been used to set the desired locale. 1316 1317Flag \f5#\fP indicates an alternative format processing. 1318For \f5%o\fP, the first digit is always a zero. 1319For \f5%x\fP and \f5%X\fP, a non-zero result will have a prefix 1320\f50x\fP or \f50X\fP. For \f5%e\fP, \f5%E\fP, \f5%f\fP, \f5%g\fP, and \f5%G\fP, 1321the result always contains a decimal point. For \f5%g\fP and \f5%G\fP, 1322trailing zeros will not be removed. For \f5%d\fP, \f5%i\fP and \f5%u\fP, 1323the form is \fIbase#number\fP where \fIbase\fP is the conversion base 1324and \fInumber\fP is represented by digits for this \fIbase\fP. 1325For example, a base \f52\fP conversion with \f5%#..2d\fP for \f510\fP 1326is \f52#1010\fP instead of \f51010\fP as printed with \f5%..2d\fP. 1327Finally, for \f5%c\fP, bytes will be printed in the C format. 1328For example, when the ASCII character set is used, 1329the byte value 10 will be printed as \f5\\n\fP while 255 is printed 1330as \f5\\377\fP. 1331.Tp 1332\f5width\fP: 1333This defines the width of the printing field. A value to be printed will 1334be justified and padded if necessary to fill out the field width. 1335.Tp 1336\f5precis\fP: 1337After a first dot appears, an integral value defines a precision. 1338For floating point value patterns, precision is the number of precision digits. 1339For \f5%c\fP, precision defines the number of times to repeat the 1340character being formatted. 1341For \f5%s\fP, precision defines the maximum number of characters to output. 1342.Tp 1343\f5base\fP: 1344This is defined after exactly two dots have appeared. 1345 1346For \f5%i\fP, \f5%d\fP, and \f5%u\fP, 1347\f5base\fP should be an integer value in the inclusive range \f5[2,64]\fP 1348and defines a conversion base. 1349If \f5base\fP is not in this range, it is defined to be \f510\fP. 1350The digits to represent numbers are: 1351 1352.nf 1353.ft 5 1354 01234567890 1355 abcdefghijklmnopqrstuvwxyz 1356 ABCDEFGHIJKLMNOPQRSTUVWXYZ @_ 1357.ft 1 1358.fi 1359 1360For \f5%s\fP and \f5%c\fP, \f5base\fP defines a separator. 1361Then, for \f5%s\fP, the input argument is taken to be a NULL-terminated array of strings 1362while, for \f5%c\fP, this is a null-terminated array of characters. 1363The strings or characters will be formatted one of a time based 1364on the usual width and precision rules. 1365After each formatted string or character, except for the last one, 1366the separator \f5base\fP is output if it is a non-zero. 1367 1368There are further restrictions on the syntax of \f5%s\fP and \f5%c\fP when 1369a separator is defined. 1370Below are the legitimate sequences for \f5%s\fP and \f5%c\fP after the second dot: 1371 1372.nf 1373\f5 s c\fP 1374\f5 *s *c\fP 1375\f5 \fP\fIz\fP\f5s \fP\fIz\fP\f5c\fP 1376.fi 1377 1378In the first case, no separator is defined so \f5base\fP is set to zero. 1379In the second case, \f5base\fP is obtained from the argument list. 1380In the third case, the character \fIz\fP 1381must be non-alphanumeric and \f5base\fP will be set to this character. 1382 1383The below example shows both the call and the result 1384of printing a \f5NULL\fP-terminated array 1385of three strings \f5apple\fP, \f5orange\fP, and \f5grape\fP: 1386 1387.nf 1388.ft 5 1389 sfprintf(sfstdout,"|%8..:s|",list); 1390 | apple: orange: grape| 1391.ft 1 1392.fi 1393 1394.Tp 1395\f5(extfdata)\fP: 1396This defines a string \f5extfdata\fP 1397to be passed to the extension function \f5Sffmt_t.extf\fP. 1398Parentheses shall be balanced. 1399If \f5extfdata\fP is \f5*\fP, the string is obtained from the argument list. 1400 1401.PP 1402.Ss " int sfscanf(Sfio_t* f, const char* format, ...)" 1403.Ss " int sfsscanf(const char* s, const char* format, ...)" 1404.Ss " int sfvsscanf(const char* s, const char* format, va_list args)" 1405.Ss " int sfvscanf(Sfio_t* f, const char* format, va_list args)" 1406These functions scan data items. 1407\f5sfscanf()\fP scans from the input stream \f5f\fP 1408while \f5sfsscanf()\fP and \f5sfvsscanf()\fP 1409scan from the null-terminated string \f5s\fP. 1410\f5sfvscanf()\fP is the underlying primitive that performs the actual scanning. 1411Item types are determined from patterns in string \f5format\fP. 1412These functions return 1413the number of items successfully scanned or \f5-1\fP on error. 1414.PP 1415A white space character (blank, tab, or new-line) in \f5format\fP 1416normally matches a maximal sequence of input white space characters. 1417However, if the input stream is in \f5SF_LINE\fP mode (see \f5sfset()\fP), 1418a new-line character only matches white spaces up to an input new-line character. 1419This is useful to avoid blocking when scanning typed inputs. 1420.PP 1421The standard scan patterns are: 1422\f5i, d, u, o, x, X, p, n, f, e, E, g, G, c, %, s, []\fP and \f5!\fP. 1423Except for \f5!\fP which shall be described below, 1424see the ANSI-C specification of \f5fscanf(3)\fP for details on other patterns. 1425Let \f5z\fP be some pattern type. A formatting pattern is specified as below: 1426 1427.nf 1428.ft 5 1429 %[*][pos$][width][.width.base][(extfdata)][flag]z 1430.ft 1 1431.fi 1432 1433.Tp 1434\f5pos$\fP: 1435A pattern can specify which argument in the argument list to use. 1436This is done via \f5pos$\fP where \f5pos\fP is the argument position. 1437Arguments are numbered so that the first argument after \f5format\fP is at position 1. 1438If \f5pos\fP is not specified, the argument following the most recently used one 1439will be used. 1440The pattern \f5%!\fP (see below) cannot be used subsequent to a usage of \f5pos$\fP. 1441.Tp 1442\f5*:\fP 1443This discards the corresponding scanned item. 1444.Tp 1445\f5width\fP and \f5base\fP: 1446\f5width\fP defines the maximum number of bytes to scan 1447and \f5base\fP defines the base of an integral value being scanned. 1448The `.' (dot) notation also allows specifying a `*' (star) to obtain 1449the value from the argument list. The below example specifies scanning 14504 bytes to obtain the value of an integer in base 10. At the end of scanning, 1451the variable \f5v\fP should have the value \f51234\fP. 1452 1453.nf 1454.ft 5 1455 sfsscanf("12345678","%.*.*d", 4, 10, &v); 1456.ft 1 1457.fi 1458 1459.Tp 1460\f5(extfdata)\fP: 1461This defines a string \f5extfdata\fP 1462to be passed to the extension function \f5Sffmt_t.extf\fP. 1463Parentheses shall be balanced. 1464If \f5extfdata\fP is \f5*\fP, the string is obtained from the argument list. 1465.Tp 1466\f5flag:\fP 1467This is \f5#\fP, \f5I\fP, or some sequence of \f5h\fP, \f5l\fP, and \f5L\fP. 1468 1469Flag \f5#\fP is significant for pattern \f5%i\fP and \f5%[\fP. 1470For \f5%i\fP, it means that the \f5#\fP symbol does not have its usual 1471meaning in an input sequence \f5base#value\fP. 1472For example, the scanning result of \f5%#i\fP on input \f52#1001\fP is \f52\fP 1473and the next \f5sfgetc()\fP call will return \f5#\fP. 1474For \f5%[\fP, if the next character in the input stream does not match 1475the given scan set of characters, \f5#\fP causes a match to a null string 1476instead of a failure. 1477 1478Flag \f5I\fP defines the size or type of the object being formatted. 1479There are two cases: (1) \f5I\fP by itself and (2) \f5I\fP 1480followed by either a decimal number or `*'. 1481 1482In the first case, for integer and floating point patterns, 1483the object type is taken to be the largest appropriate type 1484(i.e., one of \f5Sflong_t\fP, \f5Sfulong_t\fP or \f5Sfdouble_t\fP). 1485For string patterns such as \f5%s\fP, the flag is ignored. 1486 1487In the second case, a given decimal value would define a size while 1488`*' would cause the size to be obtained from the argument list. 1489For string patterns such as \f5%s\fP or \f5%[\fP, this size defines the 1490length of the buffer to store scanned data. 1491Specifying a buffer size only limits the amount of data copied into the buffer. 1492Scanned data beyond the buffer limit will be discarded. 1493For integer and floating point patterns, 1494the size is used to select a type from one of the below lists as 1495indicated by the conversion specifier: 1496 1497.nf 1498.ft 5 1499 Sflong_t, long, int, short 1500 Sfulong_t, unsigned long, unsigned int, unsigned short 1501 Sfdouble_t, double, float 1502.ft 1 1503.fi 1504 1505The selection algorithm always matches types from left to right in any given list. 1506Although selection is generally based on sizes in bytes, 1507for compatibility with Microsoft-C, the size 64 1508is matched with an appropriate type with the same number of bits, if any. 1509If the given size does not match any of the listed types, 1510it shall match one of \f5int\fP, \f5unsigned int\fP, and \f5double\fP 1511as indicated by the formatting pattern. 1512 1513Below are examples of using the \f5I\fP flag. 1514The first example scans a 64-bit integer. 1515The second scans some floating point value 1516whose size is explicitly computed and given. 1517The last example scans a string into a buffer with the given size 128. 1518Note that if the scanned string is longer than 127, only the first 127 1519bytes shall be copied into the buffer. The rest of the scanned data 1520shall be discarded. 1521 1522.nf 1523.ft 5 1524 sfscanf(sfstdin,"%I64d", &int64_obj); 1525 sfscanf(sfstdin,"%I*f", sizeof(float_obj), &float_obj); 1526 sfscanf(sfstdin,"%I*s", 128, buffer); 1527.ft 1 1528.fi 1529 1530Flags \f5h\fP, \f5l\fP, and \f5L\fP are the ANSI-C conventions 1531for indicating the type of a scanned element. 1532For example, \f5%hd\fP means scanning a \f5short int\fP. 1533The flags \f5ll\fP and \f5L\fP mean respectively scanning an 1534integer or a floating point value with largest size 1535(i.e, \f5Sflong_t\fP or \f5Sfdouble_t\fP). 1536.PP 1537The \f5%i\fP, \f5%d\fP and \f5%u\fP patterns scan numbers in bases 1538from \f52\fP to \f564\fP. 1539\f5%i\fP scans integral values in self-describing formats. 1540Except for octal, decimal and hexadecimal numbers with the usual formats, 1541numbers in general bases are assumed to be of the form: \fIbase#value\fP 1542where \fIbase\fP is a number in base 10 and \fIvalue\fP 1543is a number in the given base. 1544For example, \f52#1001\fP is the binary representation of the decimal value \f59\fP. 1545If \fIbase\fP is \f536\fP or less, 1546the digits for \fIvalue\fP can be any combination of \f5[0-9], [a-z], [A-Z]\fP 1547where upper and lower case digits are not distinguishable. 1548If \fIbase\fP is larger than \f536\fP, the set of digits is: 1549 1550.nf 1551.ft 5 1552 0123456789 1553 abcdefghijklmnopqrstuvwxyz 1554 ABCDEFGHIJKLMNOPQRSTUVWXYZ @_ 1555.ft 1 1556.fi 1557 1558.PP 1559.Ss "BUFFERING, SYNCHRONIZATION" 1560.PP 1561.Ss " Void_t* sfsetbuf(Sfio_t* f, Void_t* buf, size_t size)" 1562This function changes the buffering scheme for the stream \f5f\fP. 1563The stream will be synchronized before any buffer modification. 1564If a new buffer is successfully set and the old buffer has not been freed, 1565\f5sfsetbuf()\fP returns the old buffer. Otherwise, it returns \f5NULL\fP. 1566After a \f5sfsetbuf()\fP call, 1567\f5sfvalue()\fP returns the size of the returned buffer. 1568 1569Sfio attempts to read data in blocks likely to be serviced fast by the file system. 1570This means block sizes being multiples of a suitable alignment value 1571(e.g., 512, 1024 or 8192). By default, the alignment value 1572is computed via some internal mechanism depending on the local platform but 1573it can also be explicitly set via the call \f5sfsetbuf(f, (Void_t*)f, size)\fP. 1574 1575In invocations of \f5sfsetbuf()\fP other than the above case, 1576the \f5size\fP argument is treated as follows: 1577.Tp 1578\f5size == SF_UNBOUND\fP: 1579Sfio will pick a suitable buffer size. 1580If \f5buf\fP is \f5NULL\fP, 1581Sfio will also pick a suitable buffering scheme (such as memory mapping.) 1582If \f5buf\fP is not \f5NULL\fP, its actual value is ignored 1583but the buffer will be allocated via \f5malloc(3)\fP. 1584This can be used to avoid memory mapping. 1585.Tp 1586\f5size > 0\fP: 1587This is the suggested size to use for buffering or memory mapping. 1588If \f5buf\fP is \f5NULL\fP, 1589Sfio will pick a suitable buffering scheme as discussed above. 1590If \f5buf\fP is not \f5NULL\fP, then \f5buf\fP and \f5size\fP determine 1591a buffer of the given size. 1592.Tp 1593\f5size == 0\fP: 1594If \f5buf\fP is \f5NULL\fP, the stream will be unbuffered. 1595If \f5buf\fP is not \f5NULL\fP, 1596\f5sfsetbuf()\fP simply returns the stream buffer. 1597In this case, no attempt will be made to synchronize the stream. 1598 1599.Ss " int sfsync(Sfio_t* f)" 1600This function synchronizes the logical and physical views of stream \f5f\fP. 1601It returns a negative value for failure and \f50\fP for success. 1602 1603For a \f5SF_WRITE\fP stream, synchronization means to write out any buffered data. 1604For a seekable \f5SF_READ\fP file stream, 1605the physical file position is aligned with the logical stream position and, 1606if \f5SF_SHARE\fP is on, buffered data is discarded. 1607If \f5f\fP is \f5NULL\fP, all streams are synchronized. 1608If \f5f\fP is the base of a stream stack (see \f5sfstack()\fP), 1609all stacked streams are synchronized. 1610Note that a stacked stream can only be synchronized this way. 1611If \f5f\fP is in a pool (see \f5sfpool()\fP) but not being the head, 1612the pool head is synchronized. 1613 1614If \f5f\fP has flag \f5SF_IOCHECK\fP, the \f5SF_SYNC\fP event is raised 1615before and after synchronization. See \f5sfdisc()\fP for details. 1616 1617.Ss " int sfpoll(Sfio_t** flist, int n, int timeout)" 1618This function polls a set of streams to see if I/O operations 1619can be performed on them without blocking. 1620This is useful for multiplexing I/O over a set of streams. 1621If a stream has a discipline, the exception function may be called 1622before and after the stream is polled (see \f5sfdisc()\fP for details). 1623After a successful \f5sfpoll()\fP call, 1624for each ready stream \f5f\fP, \f5sfvalue(f)\fP returns 1625a bit combination of \f5SF_READ\fP and \f5SF_WRITE\fP to tell which I/O 1626mode is available. If \f5SF_READ\fP is available, an attempt to read 1627a byte will not block. If \f5SF_WRITE\fP is available, 1628an attempt to flush will not block. 1629\f5sfpoll()\fP returns the number of ready streams or \f5-1\fP on failure. 1630.Tp 1631\f5flist\fP and \f5n\fP: 1632\f5flist\fP is an array of \f5n\fP streams to be polled. 1633Upon return, ready streams are moved to the front 1634of \f5flist\fP in the same relative order. 1635.Tp 1636\f5timeout\fP: 1637This defines an elapse time in milliseconds 1638to wait to see if any stream is ready for I/O. 1639If \f5timeout\fP is negative, \f5sfpoll()\fP will block until some stream become ready. 1640Note that \f5SF_STRING\fP and normal file streams never block 1641and are always ready for I/O. 1642If a stream with discipline is being polled and 1643its readiness is as yet undetermined (e.g., empty buffer,) 1644the discipline exception function will be called with \f5SF_DPOLL\fP 1645before querying the operating system. 1646 1647.Ss " Sfio_t* sfpool(Sfio_t* f, Sfio_t* poolf, int mode)" 1648This function manipulates pools of streams. 1649In a pool, only one stream is at the head and can have buffered data. 1650All other streams in the pool will be synchronized. 1651A stream becomes head when it is used for some I/O operation. 1652\f5sfpool()\fP returns \f5NULL\fP on failure. 1653.Tp 1654\f5f\fP and \f5poolf\fP: 1655If \f5f\fP is \f5NULL\fP, 1656\f5sfpool()\fP simply returns the head of the pool containing \f5poolf\fP. 1657If \f5f\fP is not \f5NULL\fP and \f5poolf\fP is \f5NULL\fP, 1658\f5f\fP is deleted from its pool. 1659In this case, if no other stream from the same pool can become head, 1660\f5sfpool()\fP will return \f5NULL\fP; otherwise, it returns some stream 1661from the remainder of the pool. 1662If both \f5f\fP and \f5poolf\fP are not \f5NULL\fP, 1663\f5f\fP is moved from its current pool (if any) 1664into the same pool with \f5poolf\fP. 1665In this case, \f5poolf\fP is returned. 1666.Tp 1667\f5mode\fP: 1668If \f5poolf\fP is already in a pool, \f5mode\fP is ignored. 1669Otherwise, \f5mode\fP should be \f50\fP or \f5SF_SHARE\fP. 1670A \f5SF_SHARE\fP pool contains streams with \f5SF_WRITE\fP mode. 1671In addition, on change to a new head stream, 1672buffered write data of the current head 1673is transferred to the new head. 1674 1675.Ss " int sfpurge(Sfio_t* f)" 1676This function discards all buffered data 1677unless \f5f\fP is a \f5SF_STRING\fP stream. 1678Note that if \f5f\fP is a \f5SF_READ\fP stream based on an unseekable device, 1679purged data will not be recoverable. 1680If \f5f\fP is a \f5sfpopen\fP-stream opened for both read and write, 1681data of both the read and write pipe ends will be purged 1682(see \f5sfset()\fP to selectively turn off read or write mode 1683if one set of data is to be preserved.) 1684After purging, if \f5f\fP has flag \f5SF_IOCHECK\fP, 1685the event \f5SF_PURGE\fP is raised. 1686\f5sfpurge()\fP returns \f5-1\fP for failure and \f50\fP for success. 1687 1688.PP 1689.Ss "DISCIPLINE, EVENT-HANDLING" 1690.PP 1691A file stream uses the system calls \f5read(2)\fP, \f5write(2)\fP 1692and \f5lseek(2)\fP to read, write and position in the underlying file. 1693Disciplines enable application-defined I/O methods including exception handling and 1694data pre/post-processing. 1695 1696.Ss " Sfdisc_t* sfdisc(Sfio_t* f, Sfdisc_t* disc)" 1697Each stream has a discipline stack whose bottom is a virtual discipline 1698representing the actual system calls. 1699\f5sfdisc()\fP manipulates the discipline stack of stream \f5f\fP. 1700\f5f\fP will be synchronized before any discipline stack manipulation. 1701After a successful discipline stack manipulation, 1702the stream I/O position (see \f5sfseek()\fP and \f5sftell()\fP) 1703and extent (see \f5sfsize()\fP) are updated 1704to reflect that defined by the top discipline. 1705\f5sfdisc()\fP returns \f5NULL\fP on failure. 1706 1707If the value of \f5disc\fP is identical to the value of \f5f\fP, 1708then the top discipline on the discipline 1709stack is returned without any further action. 1710An application can then use this feature of \f5sfdisc()\fP 1711and the field \f5disc\fP (below) of the discipline structure 1712to traverse the entire discipline stack of a stream \f5f\fP as follows: 1713 1714.nf 1715.ft 5 1716 for(disc = sfdisc(f, (Sfdisc_t*)f); disc; disc = disc->disc) 1717.ft 1 1718.fi 1719 1720If \f5disc\fP is \f5SF_POPDISC\fP or \f5(Sfdisc_t*)0\fP, 1721the top element of the stack, if any, is popped and its address is returned. 1722Otherwise, \f5disc\fP is pushed onto the discipline stack. 1723In this case, if successful, \f5sfdisc()\fP returns 1724the discipline that was pushed down. 1725 1726Note that a discipline can be used on only one stream at a time. 1727An application should take care to allocate different discipline 1728structures for use with different streams. 1729A discipline structure is of the type \f5Sfdisc_t\fP which 1730contains the following public fields: 1731 1732.nf 1733.ft 5 1734 Sfread_f readf; 1735 Sfwrite_f writef; 1736 Sfseek_f seekf; 1737 Sfexcept_f exceptf; 1738 Sfdisc_t* disc; 1739.ft 1 1740.fi 1741 1742.PP 1743The first three fields of \f5Sfdisc_t\fP specify alternative I/O functions. 1744If any of them is \f5NULL\fP, it is inherited 1745from a discipline pushed earlier on the stack. 1746Note that a file stream always 1747has \f5read(2)\fP, \f5write(2)\fP, \f5lseek(2)\fP and \f5NIL(Sfexcept_f)\fP 1748as the \fIlogical bottom discipline\fP. 1749Arguments to I/O discipline functions 1750have the same meaning as that of the 1751functions \f5sfrd()\fP, \f5sfwr()\fP and \f5sfsk()\fP described below. 1752.PP 1753The exception function, \f5(*exceptf)()\fP announces exceptional events during 1754I/O operations. 1755It is called as \f5(*exceptf)(Sfio_t* f, int type, Void_t* value, Sfdisc_t* disc)\fP. 1756Unless noted otherwise, the return value of \f5(*exceptf)()\fP is used as follows: 1757.Tp 1758\f5<0\fP: 1759The on-going operation shall terminate. 1760.Tp 1761\f5>0\fP: 1762If the event was raised due to an I/O error, 1763the error has been repaired and the on-going operation shall continue normally. 1764For some events, e.g., \f5SF_DPOLL\fP, the return value may also have 1765additional meanings. 1766.Tp 1767\f5=0\fP: 1768The on-going operation performs default actions with respect to the raised event. 1769For example, on a reading error or reaching end of file, the top stream of a stack 1770will be popped and closed and the on-going operation continue with the new top 1771stream. 1772.PP 1773The argument \f5type\fP of \f5(*exceptf)()\fP 1774identifies the particular exceptional event: 1775.Tp 1776\f5SF_LOCKED\fP: 1777The stream cannot be accessed. 1778Note that this lock state is not related to the mutex lock 1779that protects a stream from multiple accesses by different threads 1780(see section THREAD SAFETY). Rather, the stream was frozen by 1781certain operations such as \f5sfreserve()\fP or \f5sfstack()\fP. 1782Thus, a stream can be in this state even if the application is uni-threaded. 1783.Tp 1784\f5SF_READ\fP, \f5SF_WRITE\fP: 1785These events are raised around reading and writing operations. 1786 1787If \f5SF_IOCHECK\fP is on, \f5SF_READ\fP and \f5SF_WRITE\fP 1788are raised immediately before \f5read(2) and write(2)\fP calls. 1789In this case, \f5*((ssize_t*)value)\fP is the amount of data to be processed. 1790The return value of \f5(*exceptf)()\fP, if negative, 1791indicates that the stream is not ready for I/O 1792and the calling operation will abort with failure. 1793If it is positive, the stream is ready for I/O 1794but the amount should be restricted to the amount specified by this value. 1795If the return value is zero, the I/O operation is carried out normally. 1796 1797\f5SF_READ\fP and \f5SF_WRITE\fP are also raised on operation failures. 1798In such a case, \f5*((ssize_t*)value)\fP 1799is the return value from the failed operation. 1800.Tp 1801\f5SF_SEEK\fP: 1802This event is raised when a seek operation fails. 1803.Tp 1804\f5SF_NEW\fP, \f5SF_CLOSING\fP (\f5SF_CLOSE\fP), \f5SF_FINAL\fP: 1805These events are raised during a stream closing. 1806\f5SF_NEW\fP is raised for a stream about to be closed to be renewed (see \f5sfnew()\fP). 1807\f5SF_CLOSING\fP is raised for a stream about to be closed. 1808\f5SF_FINAL\fP is raised after a stream has been closed and before 1809its space is to be destroyed (see \f5sfclose()\fP). 1810For these events, a non-zero return value from \f5(*exceptf)()\fP causes 1811\f5sfclose()\fP to return immediately with the same value. 1812.Tp 1813\f5SF_DPUSH\fP, \f5SF_DPOP\fP, \f5SF_DBUFFER\fP: 1814Events \f5SF_DPUSH\fP and \f5SF_DPOP\fP are raised when a 1815discipline is about to be pushed or popped. 1816\f5(Sfdisc_t*)value\fP is the to-be top discipline, if any. 1817 1818A stream buffer is always synchronized before pushing or popping a discipline. 1819If this synchronization fails, \f5SF_DBUFFER\fP will be raised with 1820\f5*((size_t*)value)\fP being the amount of data still in the buffer. 1821If the return value of \f5exceptf\fP is non-negative, 1822the push or pop operation will continue normally; 1823otherwise, \f5sfdisc()\fP returns failure. 1824.Tp 1825\f5SF_DPOLL\fP: 1826This event is raised by 1827\f5sfpoll()\fP to see if the stream is ready for I/O. 1828\f5*((int*)value)\fP indicates a time-out interval to wait. 1829A negative return value from the exception function means blocking. 1830A zero return value means that \f5sfpoll()\fP should 1831query the underlying file descriptor. 1832A positive return value means non-blocking. In addition, 1833this value will be a bit combination of \f5SF_READ\fP and \f5SF_WRITE\fP 1834to indicate what I/O modes are ready. 1835.Tp 1836\f5SF_READY\fP: 1837This event is raised by \f5sfpoll()\fP for each ready stream. 1838The third argument to the event handler is an integer composed with 1839the two bits \f5SF_READ\fP and \f5SF_WRITE\fP to indicate which 1840I/O modes are ready. 1841.Tp 1842\f5SF_SYNC\fP, \f5SF_PURGE\fP: 1843If \f5SF_IOCHECK\fP is set, 1844these events are raised respectively for a \f5sfsync()\fP or \f5sfpurge()\fP call. 1845In each case, the respective event is raised once before the appropriate 1846operation (synchronization or purging) with \f5((int)value)\fP being \f51\fP 1847and once after with \f5((int)value)\fP being \f50\fP. 1848Note that \f5sfsync()\fP is called for each 1849\f5SF_WRITE\fP or \f5SF_SHARE|SF_READ\fP stream on closing. 1850 1851.Tp 1852\f5SF_ATEXIT\fP: 1853This event is raised for each open stream before the process exits. 1854 1855.Ss " int sfraise(Sfio_t* f, int type, Void_t* data)" 1856If \f5f\fP is non-\f5NULL\fP, \f5sfraise()\fP calls all exception handlers 1857of \f5f\fP with the event \f5type\fP and associated \f5data\fP. 1858If an exception handler returns a non-zero value, 1859\f5sfraise()\fP immediate returns the same value. 1860Application-defined events should start from the value \f5SF_EVENT\fP 1861so as to avoid confusion with system-defined events, 1862\f5sfraise()\fP returns \f50\fP on success and \f5-1\fP on failure. 1863 1864If \f5f\fP is \f5NULL\fP, \f5sfraise()\fP iterates over all streams 1865and raise events as described above. In this case, 1866\f5sfraise()\fP returns \f50\fP on success and a negative value 1867on failure. The absolute value of the return value tells how many 1868streams failed on raising the given event. 1869 1870.Ss " ssize_t sfrd(Sfio_t* f, Void_t* buf, size_t n, Sfdisc_t* disc)" 1871.Ss " ssize_t sfwr(Sfio_t* f, const Void_t* buf, size_t n, Sfdisc_t* disc)" 1872.Ss " Sfoff_t sfsk(Sfio_t* f, Sfoff_t offset, int type, Sfdisc_t* disc)" 1873These functions provides safe methods for a discipline I/O function to invoke 1874earlier discipline I/O functions and to properly handle exceptions. 1875They should not be used in any other context. 1876\f5sfrd()\fP and \f5sfwr()\fP return the number of bytes read or written. 1877\f5sfsk()\fP returns the new seek position. 1878On error, all three functions return a negative value which should be \f5-1\fP 1879or the value returned by the exception handler. 1880 1881.PP 1882.Ss "STREAM CONTROL" 1883.PP 1884.Ss " int sfresize(Sfio_t* f, Sfoff_t size)" 1885This function resizes the stream \f5f\P so that its extent is \f5size\fP. 1886If the stream corresponds to a file, the file size is set to \f5size\fP 1887via the system call \f5ftruncate()\fP. 1888When a stream is made larger, the new data space is filled with zero's. 1889\f5sfresize()\fP returns \f50\fP on success and a negative value on failure. 1890 1891.Ss " int sfset(Sfio_t* f, int flags, int set)" 1892This function sets control flags for the stream \f5f\fP. 1893It returns the previous set of flags or \f50\fP on error. 1894 1895Settable flags are: 1896\f5SF_READ\fP, \f5SF_WRITE\fP, \f5SF_IOCHECK\fP, 1897\f5SF_LINE\fP, \f5SF_SHARE\fP, \f5SF_PUBLIC\fP, \f5SF_MALLOC\fP and 1898\f5SF_STATIC\fP. 1899Note that \f5SF_READ\fP and \f5SF_WRITE\fP can be turned on or off only 1900if the stream was opened as \f5SF_READ|SF_WRITE\fP. 1901Turning off one of them means that the stream is to be treated exclusively 1902in the other mode. It is not possible to turn off both. 1903If legal, an attempt to turn on either \f5SF_READ\fP or \f5SF_WRITE\fP 1904will cause the stream to be in the given I/O mode. 1905.Tp 1906\f5set == 0:\fP 1907If \f5flags\fP is zero, the current set of flags is simply returned. 1908Note that when a stream is first opened, not 1909all of its flags are initialized yet (more below). If \f5flags\fP is 1910non-zero, an attempt is made to turn off the specified flags. 1911.Tp 1912\f5set != 0:\fP 1913If \f5flags\fP is zero, the stream is initialized if not yet done so. 1914Then the current set of flags is returned. 1915If \f5flags\fP is non-zero, an attempt is made to turn on the 1916specified flags. 1917 1918.Ss " int sfsetfd(Sfio_t* f, int fd)" 1919This function changes the file descriptor of \f5f\fP. 1920Before a change is realized, 1921\f5(*notify)(f,SF_SETFD,newfd)\fP (see \f5sfnotify()\fP) is called. 1922\f5sfsetfd()\fP returns \f5-1\fP on failure and the new file descriptor on success. 1923.Tp 1924\f5fd >= 0\fP: 1925If the current file descriptor is non-negative, 1926it will be changed using \f5dup(3)\fP to a value larger or equal to \f5fd\fP. 1927Upon a successful change, the previous file descriptor will be closed. 1928If the current file descriptor is negative, it will be set to \f5fd\fP and 1929the stream will be reinitialized. 1930.Tp 1931\f5fd < 0\fP: 1932The stream is synchronized (see \f5sfsync()\fP) and its 1933file descriptor will be set to this value. 1934Then, except for \f5sfclose()\fP, the stream will be inaccessible 1935until a future \f5sfsetfd()\fP call resets the file descriptor to a non-negative value. 1936Thus, \f5sfsetfd(f,-1)\fP can be used to avoid closing the file descriptor 1937of \f5f\fP when \f5f\fP is closed. 1938 1939.Ss " Sfio_t* sfstack(Sfio_t* base, Sfio_t* top)" 1940This function stacks or unstacks stream. 1941Every stream stack is identified by a base stream 1942via which all I/O operations are performed. 1943However, an I/O operation always takes effect on the top stream. 1944If the top stream reaches the end of file or 1945has an unrecoverable error condition, 1946it is automatically popped and closed 1947(see also \f5sfdisc()\fP for alternative handling of these conditions). 1948.Tp 1949\f5base\fP: 1950This is the base stream of the stack. 1951If it is \f5NULL\fP, \f5sfstack()\fP does nothing and returns \f5top\fP. 1952.Tp 1953\f5top\fP: 1954If this is \f5SF_POPSTACK\fP or \f5(Sfio_t*)0\fP, 1955the stack is popped and \f5sfstack()\fP returns the popped stream. 1956Otherwise, \f5top\fP is pushed on top of the stack identified by \f5base\fP 1957and \f5sfstack()\fP returns the \f5base\fP stream. 1958 1959.Ss " Sfio_t* sfswap(Sfio_t* f1, Sfio_t* f2)" 1960This function swaps contents of \f5f1\fP and \f5f2\fP. 1961This fails if either stream is in a stream stack but not being a base stream. 1962If \f5f2\fP is \f5NULL\fP, a new stream is constructed as a duplicate of \f5f1\fP. 1963\f5sfswap()\fP returns \f5f2\fP or \f5f1\fP duplicate on success and 1964\f5NULL\fP on failure. 1965 1966.PP 1967.Ss "STREAM INFORMATION" 1968.PP 1969.Ss " Sfoff_t sfsize(Sfio_t* f)" 1970This function returns the size of stream \f5f\fP (see \f5sfnew()\fP). 1971If \f5f\fP is not seekable or if its size is not determinable, 1972\f5sfsize()\fP returns \f5-1\fP. 1973 1974.Ss " Sfoff_t sftell(Sfio_t* f)" 1975This function returns the current I/O position in stream \f5f\fP. 1976Note that if \f5f\fP is \f5SF_APPEND\fP 1977and a writing operation was just performed, 1978the current I/O position is at the physical end of file. 1979If \f5f\fP is unseekable, \f5sftell\fP returns the number of bytes 1980read from or written to \f5f\fP. 1981See also \f5sfungetc()\fP. 1982 1983.Ss " ssize_t sfvalue(Sfio_t* f)" 1984This function returns the string or buffer length 1985for \f5sfreserve()\fP, \f5sfsetbuf()\fP, and \f5sfgetr()\fP. 1986 1987.Ss " int sffileno(Sfio_t* f)" 1988This function returns the file descriptor of stream \f5f\fP. 1989 1990.Ss " int sfstacked(Sfio_t* f)" 1991This function returns a non-zero value 1992if stream \f5f\fP has been stacked. 1993 1994.Ss " int sfeof(Sfio_t* f)" 1995.Ss " int sferror(Sfio_t* f)" 1996.Ss " int sfclrerr(Sfio_t* f)" 1997\f5sfeof()\fP tells whether or not the stream has an end-of-file condition. 1998\f5sferror()\fP tells whether or not the stream has an error condition. 1999\f5sfclrerr()\fP clears both end-of-file and error conditions. 2000The end-of-file and error conditions are also cleared on an I/O operation. 2001 2002.Ss " int sfclrlock(Sfio_t* f)" 2003This function restores the stream back to a normal state. 2004This means clearing locks and possibly throwing away unprocessed data. 2005As such, this operation is unsafe and should be used with care. 2006For example, it may be used before a long jump (\f5longjmp(3)\fP) 2007out of some discipline I/O function to restore the internal stream states. 2008\f5sfclrlock()\fP returns the current set of flags. 2009 2010.Ss " int sfnotify((void(*)notify)(Sfio_t*, int, void*) )" 2011This sets a function \f5(*notify)()\fP to be called 2012as \f5(*notify)(f, type, data)\fP on various stream events. 2013Arguments \f5type\fP and \f5data\fP indicate the reason for the call and accompanying data: 2014.Tp 2015\f5SF_NEW\fP: 2016\f5f\fP is being opened and \f5data\fP is the underlying file descriptor. 2017.Tp 2018\f5SF_CLOSING\fP (\f5SF_CLOSE\fP): 2019\f5f\fP is the stream being closed and \f5data\fP is the underlying file descriptor. 2020.Tp 2021\f5SF_SETFD\fP: 2022The file descriptor of \f5f\fP is being changed to the one 2023defined by \f5data\fP (see \f5sfsetfd()\fP.) 2024.Tp 2025\f5SF_READ\fP: 2026An attempt to change \f5f\fP to read mode failed. 2027\f5data\fP is the file descriptor of the stream. 2028.Tp 2029\f5SF_WRITE\fP: 2030An attempt to change \f5f\fP to write mode failed. 2031\f5data\fP is the file descriptor of the stream. 2032.Tp 2033\f5SF_MTACCESS\fP: 2034When a notifying function was registered (see \f5sfnotify()\fP), 2035every Sfio call on a stream with flag \f5SF_MTSAFE\fP will 2036invoke the notifying function 2037once on entry after the stream is locked 2038as \f5(*notify)(f, SF_MTACCESS, Sfio_t** fp), and 2039once on return before unlocking as 2040as \f5(*notify)(f, SF_MTACCESS, (Sfio_t**)0). 2041In the call entry case, 2042the notification function could use the argument \f5fp\fP 2043to set a stream that would be used for performing the actual I/O operation. 2044In this way, certain global streams such as the standard streams \f5sfstdin\fP, 2045\f5sfstdout\fP and \f5sfstderr\fP could be made to act differently when used 2046in different streams. 2047 2048.Ss " int sfwalk(Sfwalk_f walkf, Void_t* data, int type)" 2049This function invokes \f5(*walkf)(f, data)\fP on every open stream \f5f\fP 2050whose flags as defined by \f5sfset()\fP contains all bit flags given in \f5type\fP. 2051On such a call, if the return value is negative, \f5sfwalk()\fP will terminate. 2052\f5sfwalk()\fP returns 0 if no stream was processed. 2053Otherwise, it returns the return value from the last invocation of \f5walkf()\fP. 2054 2055As an example, the call \f5sfwalk(walkf, data, SF_READ)\fP will iterate over all streams 2056opened for reading. Similarly, \f5sfwalk(walkf, data, SF_READ|SF_WRITE)\fP 2057iterates over all streams opened for both reading and writing. 2058Lastly, \f5sfwalk(walkf, data, 0)\fP iterates over all streams. 2059 2060.PP 2061.Ss "MISCELLANEOUS FUNCTIONS" 2062.PP 2063.Ss " ssize_t sfmaxr(ssize_t maxr, int set)" 2064Certain records may require too much memory for storage, thus, causing 2065undesirable side effects. Therefore, the library normally bounds the amount 2066of memory used by \f5sfgetr()\fP. A different memory bound 2067can be set via \f5sfmaxr()\fP. While a positive \f5maxr\fP hints to \f5sfgetr()\fP 2068to use only about that much memory to construct a record, a non-positive bound 2069allows \f5sfgetr()\fP to use as much memory as necessary. 2070\f5sfmaxr()\fP sets the value only if \f5set\fP is non-zero. 2071It returns the value before setting or the current value if not setting. 2072 2073.Ss " ssize_t sfslen()" 2074This function returns the length of a string just constructed 2075by \f5sfsprintf()\fP or \f5sfprints()\fP. See also \f5sfvalue()\fP. 2076 2077.Ss " int sfulen(Sfulong_t v)" 2078.Ss " int sfllen(Sflong_t v)" 2079.Ss " int sfdlen(Sfdouble_t v)" 2080These functions return respectively the number of bytes required to code the 2081\f5Sfulong_t\fP, \f5Sflong_t\fP or \f5Sfdouble_t\fP value \f5v\fP by \f5sfputu()\fP, 2082\f5sfputl()\fP or \f5sfputd()\fP. 2083 2084.Ss " ssize_t sfpkrd(int fd, char* buf, size_t n, int rsc, long tm, int action)" 2085This function acts directly on the file descriptor \f5fd\fP. 2086It does a combination of peeking on incoming data and a time-out read. 2087Upon success, it returns the number of bytes received. 2088A return value of \f50\fP means that the end-of-file condition has been detected. 2089A negative value represents an error. 2090.Tp 2091\f5buf\fP, \f5n\fP: 2092These define a buffer and its size to read data into. 2093.Tp 2094\f5rsc\fP: 2095If \f5>=0\fP, this defines a record separator. 2096If the last returned byte is not the record separator, then 2097the read data did not contain a complete record. Otherwise, 2098it contains one or more records. 2099See also \f5action\fP below. 2100.Tp 2101\f5tm\fP: 2102If \f5>=0\fP, this defines a time interval in milliseconds to wait for incoming data. 2103.Tp 2104\f5action\fP: 2105If \f5action > 0\fP, \f5sfpkrd()\fP will peek on incoming data but 2106will not read past it. Therefore, a future \f5sfpkrd()\fP or \f5read(2)\fP will see 2107the same data again. 2108If \f5action <= 0\fP, \f5sfpkrd()\fP will not peek and there are two cases. 2109If \f5rsc < 0\fP, an attempt is made to read \f5n\fP bytes. 2110If \f5rsc >= 0\fP, an attempt is made to read one record. 2111 2112.PP 2113.Ss "FULL STRUCTURE SFIO_T" 2114.PP 2115.Ss " #include <sfio_t.h>" 2116Most applications based on Sfio only need to include 2117the header file \f5sfio.h\fP which defines an abbreviated \f5Sfio_t\fP 2118structure without certain fields private to Sfio. 2119However, there are times (e.g., debugging) 2120when an application may require more details about the full \f5Sfio_t\fP structure. 2121In such cases, the header file \f5sfio_t.h\fP can be used in place of \f5sfio.h\fP. 2122Note that an application doing this will become sensitive to changes 2123in the internal architecture of Sfio. 2124 2125.Ss " #define SFNEW(buf,size,file,flags,disc)" 2126This macro function is defined in \f5sfio_t.h\fP for 2127use in static initialization of an \f5Sfio_t\fP structure. 2128It requires five arguments: 2129.Tp 2130\f5buf, size\fP: 2131These define a buffer and its size. 2132.Tp 2133\f5file\fP: 2134This defines the underlying file descriptor if any. 2135.Tp 2136\f5flags\fP: 2137This is composed from bit flags described above. 2138.Tp 2139\f5disc\fP: 2140This defines a discipline if any. 2141 2142.PP 2143.Ss "EXAMPLE DISCIPLINES" 2144.PP 2145The below functions create disciplines and insert them into 2146the given streams \f5f\fP. These functions return \f50\fP 2147on success and \f5-1\fP on failure. 2148 2149.Ss "int sfdcdio(Sfio_t* f, size_t bufsize)" 2150This creates a discipline that uses the direct IO feature 2151available on file systems such as SGI's XFS to speed up IO. 2152The argument \f5bufsize\fP suggests a buffer size to use for data transfer. 2153 2154.Ss "int sfdcdos(Sfio_t* f)" 2155This creates a discipline to read DOS text files. 2156It basically transforms pairs of \er\en to \en. 2157 2158.Ss "int sfdcfilter(Sfio_t* f, const char* cmd)" 2159This creates a discipline that sends data from \f5f\fP 2160to the given command \f5cmd\fP to process, then reads back the processed data. 2161 2162.Ss "int sfdcseekable(Sfio_t* f)" 2163This creates a discipline that makes an unseekable reading stream seekable. 2164 2165.Ss "int sfdcslow(Sfio_t* f)" 2166This creates a discipline that makes all Sfio operations return immediately 2167on interrupts. This is useful for dealing with slow devices. 2168 2169.Ss "int sfdcsubstream(Sfio_t* f, Sfio_t* parent, Sfoff_t offset, Sfoff_t extent)" 2170This creates a discipline that makes \f5f\fP acts as if it 2171corresponds exactly to the subsection of \f5parent\fP 2172starting at \f5offset\fP with size \f5extent\fP. 2173 2174.Ss "int sfdctee(Sfio_t* f, Sfio_t* tee)" 2175This creates a discipline that copies to the stream \f5tee\fP 2176any data written to \f5f\fP. 2177 2178.Ss "int sfdcunion(Sfio_t* f, Sfio_t** array, int n)" 2179This creates a discipline that makes \f5f\fP act as if it is 2180the concatenation of the \f5n\fP streams given in \f5array\fP. 2181 2182.Ss "int sfdclzw(Sfio_t* f)" 2183This creates a discipline that would decompress data in \f5f\fP. 2184The stream \f5f\fP should have data from a source compressed by 2185the Unix \fBcompress\fP program. 2186 2187.Ss "int sfdcgzip(Sfio_t* f, int opt)" 2188This creates a discipline for reading/writing data compressed by zlib. 2189The argument \f5opt\fP defines the optimization level. 2190 2191.PP 2192.Ss "STDIO-COMPATIBILITY" 2193.PP 2194Sfio provides compatibility functions for all various popular 2195Stdio implementations at source and binary level. 2196The source Stdio-compatibility interface 2197provides the header file \f5stdio.h\fP that defines 2198a set of macros or inlined functions to map Stdio calls to Sfio ones. 2199This mapping may benignly extend or change the meaning of certain 2200original Stdio operations. For example, the Sfio's version of 2201\f5popen()\fP allows a coprocess to be opened for both reading and writing 2202unlike the original call which only allows a coprocess to be opened for a single mode. 2203Similarly, the Sfio's \f5fopen()\fP call can be used to create 2204string streams in addition to file streams. 2205.PP 2206The standard streams \f5stdin\fP, \f5stdout\fP and \f5stderr\fP 2207are mapped via \f5#define\fP to \f5sfstdin\fP, \f5sfstdout\fP and \f5sfstderr\fP. 2208The latter are typically declared of the type \f5Sfio_t*\fP. 2209Certain older Stdio applications require these to be declared 2210as addresses of structures so that static initializations of 2211the sort ``\f5FILE*\ f\ =\ stdin;\fP'' would work. 2212Such applications should use the compile time flag \f5SF_FILE_STRUCT\fP 2213to achieve the desired effect. 2214.PP 2215The binary Stdio-compatibility libraries, \f5libstdio.a\fP and \f5libstdio-mt.a\fP, 2216provide complete implementations of Stdio functions suitable 2217for linking applications already compiled with native header \f5stdio.h\fP. 2218These functions are also slightly altered or extended 2219as discussed above. 2220.PP 2221Below are the supported Stdio functions: 2222.PP 2223.nf 2224.ft 5 2225FILE* fopen(const char* file, const char* mode); 2226FILE* freopen(const char* file, const char* mode, FILE* stream); 2227FILE* fdopen(int filedesc, const char* mode); 2228FILE* popen(const char* command, const char* mode); 2229FILE* tmpfile(); 2230int fclose(FILE* stream); 2231int pclose(FILE* stream); 2232 2233void flockfile(FILE* stream) 2234int ftrylockfile(FILE* stream) 2235void funlockfile(FILE* stream) 2236 2237void setbuf(FILE* stream, char* buf); 2238int setvbuf(FILE* stream, char* buf, int mode, size_t size); 2239void setbuffer(FILE* stream, char* buf, size_t size); 2240int setlinebuf(FILE* stream); 2241int fflush(FILE* stream); 2242int fpurge(FILE* stream); 2243 2244int fseek(FILE* stream, long offset, int whence); 2245void rewind(FILE* stream); 2246int fgetpos(FILE* stream, fpos_t* pos); 2247int fsetpos(FILE* stream, fpos_t* pos); 2248long ftell(FILE* stream); 2249 2250int getc(FILE* stream); 2251int fgetc(FILE* stream); 2252int getchar(void); 2253int ungetc(int c, FILE* stream); 2254int getw(FILE* stream); 2255char* gets(char* s); 2256char* fgets(char* s, int n, FILE* stream); 2257size_t fread(Void_t* ptr, size_t size, size_t nelt, FILE* stream); 2258 2259int putc(int c, FILE* stream); 2260int fputc(int c, FILE* stream); 2261int putchar(int c); 2262int putw(int w, FILE* stream); 2263int puts(const char* s, FILE* stream); 2264int fputs(const char* s, FILE* stream); 2265size_t fwrite(const Void_t* ptr, size_t size, size_t nelt, FILE* stream); 2266 2267int fscanf(FILE* stream, const char* format, ...); 2268int vfscanf(FILE* stream, const char* format, va_list args); 2269int _doscan(FILE* stream, const char* format, va_list args); 2270int scanf(const char* format, ...); 2271int vscanf(const char* format, va_list args); 2272int sscanf(const char* s, const char* format, ...); 2273int vsscanf(const char* s, const char* format, va_list args); 2274 2275int fprintf(FILE* stream, const char* format, ...); 2276int vfprintf(FILE* stream, const char* format, va_list args); 2277int _doprnt(FILE* stream, const char* format, va_list args); 2278int printf(const char* format, ...); 2279int vprintf(const char* format, va_list args); 2280int sprintf(const char* s, const char* format, ...); 2281int snprintf(const char* s, int n, const char* format, ...); 2282int vsprintf(const char* s, const char* format, va_list args); 2283int vsnprintf(const char* s, int n, const char* format, va_list args); 2284 2285int feof(FILE* stream); 2286int ferror(FILE* stream); 2287int clearerr(FILE* stream); 2288.ft 1 2289.fi 2290 2291.PP 2292.Ss "RECENT CHANGES" 2293.PP 2294A few exception types have been added. In particular, exception handlers shall 2295be raised with \f5SF_LOCKED\fP on accessing a stream frozen either by 2296an ongoing operation or a previous operation (e.g., \f5sfgetr()\fP). 2297Before a process exits, the event \f5SF_ATEXIT\fP is raised for each open stream. 2298.PP 2299A number of disciplines were added for various processing functions. 2300Of interests are disciplines to use the direct I/O feature on IRIX6.2, 2301read DOS text files, and decompress files compressed by Unix \fIcompress\fP. 2302.PP 2303Various new stream and function flags have been added. For example, 2304the third argument of \f5sfgetr()\fP is now a set of bit flags and not 2305just a three-value object. However, the old semantics of this argument 2306of \f5sfgetr()\fP is still supported. 2307.PP 2308The \f5sfopen()\fP call has been extended so that sfopen(f,NULL,mode) can be 2309used to changed the mode of a file stream before any I/O operations. 2310This is most useful for changing the modes of the standard streams. 2311.PP 2312The buffering strategy has been significantly enhanced for streams 2313that perform many seek operations. Also, the handling of stream and 2314file positions have been better clarified so that applications that 2315share file descriptors across streams and/or processes can be sure that 2316the file states will be consistent. 2317.PP 2318The strategy for mapping between Sfio and Stdio streams in the binary 2319compatibility package has been significantly enhanced for efficiency. 2320For most platforms, the mapping is now constant time per look-up. 2321.PP 2322The \f5SF_BUFCONST\fP flag was deleted. This is largely unused anyway. 2323.PP 2324The library can be built for thread-safety. This is based largely on 2325Posix pthread mutexes except for on UWIN where native Windows APIs 2326are used. 2327.PP 2328The functions \f5sfgetm()\fP and \f5sfputm()\fP were added to encode 2329unsigned integer values with known ranges. 2330.PP 2331The flag \f5SF_APPEND\fP is identical to \f5SF_APPENDWR\fP. 2332However it conflicts with a different token of the same name 2333defined in the system header \f5stat.h\fP of BSDI Unix systems. 2334On such systems, we shall not define \f5SF_APPEND\fP and this 2335symbol may be removed in a future release. 2336.PP 2337Similarly, the exception \f5SF_CLOSE\fP is identical to \f5SF_CLOSING\fP. 2338However it conflicts with a different token of the same name 2339defined in the system header \f5socket.h\fP of AIX Unix systems. 2340On such systems, we shall not define \f5SF_CLOSE\fP and this 2341symbol may be removed in a future release. 2342.PP 2343The printing and scanning functions were extended to handle multibyte characters 2344and to conform to the C99 standard. 2345.PP 2346The function \f5sfpoll()\fP was rehauled to make it useful 2347for writing servers that must commnunicate with multiple streams 2348without blocking. 2349.PP 2350The formatting pattern \f5%c\fP for \f5sf*printf\fP was extended 2351to allow the flag \f5#\fP to print unprintable character values 2352using the C convention. For example, \f5%#c\fP prints the octal value 012 2353as \f5\\n\fP. 2354 2355.SH AUTHORS 2356Kiem-Phong Vo, kpv@research.att.com, 2357.br 2358David G. Korn, dgk@research.att.com, and 2359.br 2360Glenn S. Fowler, gsf@research.att.com. 2361