sfio.3

su 的源代码库

.fp 5 CW
.TH SFIO 3 "01 February 2005"
.SH NAME
\fBsfio\fR \- safe/fast string/file input/output
.SH SYNOPSIS
.de Tp
.fl
.ne 3
.TP
..
.de Ss
.fl
.ne 3
.SS "\\$1"
..
.ta 1.0i 2.0i 3.0i 4.0i 5.0i
.Ss "LIBRARIES"
.nf
.ft 5
#include      <sfio.h>

libsfio.a     -lsfio
libstdio.a    -lstdio
libsfio-mt.a  -lsfio-mt
libstdio-mt.a -lstdio-mt
.ft 1
.fi
.Ss "DATA TYPES"
.nf
.ft 5
Void_t;
Sfoff_t;
Sflong_t;
Sfulong_t;
Sfdouble_t;

Sfio_t;

Sfdisc_t;
ssize_t    (*Sfread_f)(Sfio_t*, Void_t*, size_t, Sfdisc_t*);
ssize_t    (*Sfwrite_f)(Sfio_t*, const Void_t*, size_t, Sfdisc_t*);
Sfoff_t    (*Sfseek_f)(Sfio_t*, Sfoff_t, int, Sfdisc_t*);
int        (*Sfexcept_f)(Sfio_t*, int, Void_t*, Sfdisc_t*);

Sffmt_t;
int        (*Sffmtext_f)(Sfio_t*, Void_t*, Sffmt_t*);
int        (*Sffmtevent_f)(Sfio_t*, int, Void_t*, Sffmt_t*);

SFIO_VERSION
.ft 1
.fi
.Ss "BIT FLAGS"
.nf
.ft 5
SF_STRING
SF_READ
SF_WRITE
SF_APPENDWR (SF_APPEND)
SF_LINE
SF_SHARE
SF_PUBLIC
SF_MALLOC
SF_STATIC
SF_IOCHECK
SF_WHOLE
SF_MTSAFE
SF_IOINTR
.ft 1
.fi
.Ss "OPENING/CLOSING STREAMS"
.nf
.ft 5
Sfio_t*    sfnew(Sfio_t* f, Void_t* buf, size_t size, int fd, int flags);
Sfio_t*    sfopen(Sfio_t* f, const char* string, const char* mode);
Sfio_t*    sfpopen(Sfio_t* f, const char* cmd, const char* mode);
Sfio_t*    sftmp(size_t size);
int        sfclose(Sfio_t* f);


.ft 1
.fi
.Ss "THREAD SAFETY"
.nf
.ft 5
int        sfmutex(Sfio_t* f, int type);

SFMTX_LOCK
SFMTX_TRYLOCK
SFMTX_UNLOCK
SFMTX_CLRLOCK
.ft 1
.fi
.Ss "INPUT/OUTPUT OPERATIONS"
.nf
.ft 5
int        sfgetc(Sfio_t* f);
int        sfputc(Sfio_t* f, int c);
int        sfnputc(Sfio_t* f, int c, int n);
int        sfungetc(Sfio_t* f, int c);

Sfulong_t  sfgetm(Sfio_t* f, Sfulong_t max);
int        sfputm(Sfio_t* f, Sfulong_t v, Sfulong_t max);
Sfulong_t  sfgetu(Sfio_t* f);
int        sfputu(Sfio_t* f, Sfulong_t v);
Sflong_t   sfgetl(Sfio_t* f);
int        sfputl(Sfio_t* f, Sflong_t v);
Sfdouble_t sfgetd(Sfio_t* f);
int        sfputd(Sfio_t* f, Sfdouble_t v);

char*      sfgetr(Sfio_t* f, int rsc, int type);
ssize_t    sfputr(Sfio_t* f, const char* s, int rsc);
Sfoff_t    sfmove(Sfio_t* fr, Sfio_t* fw, Sfoff_t n, int rsc);

ssize_t    sfread(Sfio_t* f, Void_t* buf, size_t n);
ssize_t    sfwrite(Sfio_t* f, const Void_t* buf, size_t n);
Sfoff_t    sfseek(Sfio_t* f, Sfoff_t offset, int type);
Void_t*    sfreserve(Sfio_t* f, ssize_t n, int type);
.ft 1
.fi
.Ss "DATA FORMATTING"
.nf
.ft 5
int        sfscanf(Sfio_t* f, const char* format, ...);
int        sfsscanf(const char* s, const char* format, ...);
int        sfvsscanf(const char* s, const char* format, va_list args);
int        sfvscanf(Sfio_t* f, const char* format, va_list args);

int        sfprintf(Sfio_t* f, const char* format, ...);
char*      sfprints(const char* format, ...);
ssize_t    sfaprints(char** sp, const char* format, ...);
ssize_t    sfvaprints(char** sp, const char* format, va_list args);
int        sfsprintf(char* s, int n, const char* format, ...);
int        sfvsprintf(char* s, int n, const char* format, va_list args);
int        sfvprintf(Sfio_t* f, const char* format, va_list args);

Sffmt_t;

SFFMT_LEFT
SFFMT_SIGN
SFFMT_BLANK
SFFMT_ZERO
SFFMT_THOUSAND
SFFMT_LONG
SFFMT_LLONG
SFFMT_SHORT
SFFMT_LDOUBLE
SFFMT_IFLAG
SFFMT_ALTER
SFFMT_SKIP
SFFMT_ARGPOS
SFFMT_VALUE

int        (*Sffmtext_f)(Sfio_t* f, Void_t* v, Sffmt_t* fe);
int        (*Sffmtevent_f)(Sfio_t* f, int type, Void_t* v, Sffmt_t* fe);
void       va_copy(va_list to, va_list fr);
long       sffmtversion(Sffmt_t* fe, type);
.ft 1
.fi
.Ss "BUFFERING, SYNCHRONIZATION"
.nf
.ft 5
Void_t*    sfsetbuf(Sfio_t* f, Void_t* buf, size_t size);
int        sfsync(Sfio_t* f);
int        sfpoll(Sfio_t** flist, int n, int timeout); 
Sfio_t*    sfpool(Sfio_t* f, Sfio_t* poolf, int mode);
int        sfpurge(Sfio_t* f);
.ft 1
.fi
.Ss "DISCIPLINE, EVENT HANDLING"
.nf
.ft 5
Sfdisc_t*  sfdisc(Sfio_t* f, Sfdisc_t* disc);
int        sfraise(Sfio_t* f, int type, Void_t* data);
ssize_t    sfrd(Sfio_t* f, Void_t* buf, size_t n, Sfdisc_t* disc);
ssize_t    sfwr(Sfio_t* f, const Void_t* buf, size_t n, Sfdisc_t* disc);
Sfoff_t    sfsk(Sfio_t* f, Sfoff_t offset, int type, Sfdisc_t* disc);

SF_NEW
SF_READ
SF_WRITE
SF_SEEK
SF_CLOSING (SF_CLOSE)
SF_DPUSH
SF_DPOP
SF_DPOLL
SF_DBUFFER
SF_SYNC	
SF_PURGE
SF_FINAL
SF_READY
SF_LOCKED
SF_ATEXIT
SF_EVENT
.ft 1
.fi
.Ss "STREAM CONTROL"
.nf
.ft 5
int        sfresize(Sfio_t* f, Sfoff_t size);
int        sfset(Sfio_t* f, int flags, int i);
int        sfsetfd(Sfio_t* f, int fd);
Sfio_t*    sfstack(Sfio_t* base, Sfio_t* top);
Sfio_t*    sfswap(Sfio_t* f1, Sfio_t* f2);
.ft 1
.fi
.Ss "STREAM INFORMATION"
.nf
.ft 5
Sfoff_t    sfsize(Sfio_t* f);
Sfoff_t    sftell(Sfio_t* f);
ssize_t    sfvalue(Sfio_t* f);
int        sffileno(Sfio_t* f);

int        sfstacked(Sfio_t* f);
int        sfeof(Sfio_t* f);
int        sferror(Sfio_t* f);
int        sfclrerr(Sfio_t* f);
int        sfclrlock(Sfio_t* f);

int        sfnotify(void (*notify)(Sfio_t* f, int type, int fd));
.ft 1
.fi
.Ss "MISCELLANEOUS FUNCTIONS"
.nf
.ft 5
ssize_t    sfslen();
int        sfulen(Sfulong_t v);
int        sfllen(Sflong_t v);
int        sfdlen(Sfdouble_t v);
ssize_t    sfpkrd(int fd, Void_t* buf, size_t n,
                  int rsc, long tm, int action);
.ft 1
.fi
.Ss "FULL STRUCTURE SFIO_T"
.nf
.ft 5
#include   <sfio_t.h>
#define    SFNEW(buf,size,file,flags,disc)
.ft 1
.fi
.Ss "EXAMPLE DISCIPLINES"
.nf
.ft 5
#include   <sfdisc.h>

int        sfdcdio(Sfio_t* f, size_t bufsize);
int        sfdcdos(Sfio_t* f);
int        sfdcfilter(Sfio_t* f, const char* cmd);
int        sfdcseekable(Sfio_t* f);
int        sfdcslow(Sfio_t* f);
int        sfdcsubstream(Sfio_t* f, Sfio_t* parent,
                         Sfoff_t offset, Sfoff_t extent);
int        sfdctee(Sfio_t* f, Sfio_t* tee);
int        sfdcunion(Sfio_t* f, Sfio_t** array, int n);
int        sfdclzw(Sfio_t* f);
int        sfdcgzip(Sfio_t* f, int flags);
.ft 1
.fi
.Ss "STDIO-COMPATIBILITY"
.nf
.ft 5
#include   <stdio.h>
cc ... -lstdio -lsfio
cc ... -lstdio-mt -lsfio-mt
.ft 1
.fi
.SH DESCRIPTION
.PP
Sfio provides I/O functions to manage buffered streams.
Each Sfio stream is a \fIfile stream\fP, representing a file (see \f5open(2)\fP),
or a \fIstring stream\fP, representing a memory segment.
Beyond the usual I/O operations on streams,
Sfio provides I/O disciplines for extended data processing,
stream stacks for recursive stream processing, and
stream pools for automatic data synchronization.
Applications can extend the \f5sfprintf()/sfscanf()\fP functions
to define their own conversion patterns as well as redefine existing ones.
.PP
A discipline defines analogues of 
the system calls \f5read(2), write(2)\fP and \f5lseek(2)\fP.
Such system calls or their discipline replacements are used to process stream data.
Henceforth, ``\fIsystem call\fP'' will refer to either a system call
or its discipline replacement.
.PP
A system call is said to cause an exception if its return value is non-positive.
Unless overridden by exception handlers (see \f5sfdisc()\fP),
an interrupted system call (\f5errno == EINTR\fP on UNIX systems)
will be automatically reinvoked to continue the ongoing operation.
.PP
The buffer of a stream is typically a memory segment allocated via \f5malloc(3)\fP
or supplied by the application.
File streams may also use memory mapping (\f5mmap(2)\fP) if that is more efficient.
When memory mapping is used,
the underlying file should not be truncated while the stream is active.
Memory mapping can be turned off using \f5sfsetbuf()\fP.
.PP
There are three \fIstandard streams\fP:
\f5sfstdin\fP for input (file descriptor \f50\fP on UNIX systems),
\f5sfstdout\fP for normal output (file descriptor \f51\fP), and
\f5sfstderr\fP for error output (file descriptor \f52\fP).

.PP
.Ss "LIBRARIES"
.PP
This version of Sfio can be built and used for both uni-threaded and multi-threaded
environments. In the former case, streams are not protected from
simultaneous accesses by different threads. In the latter case, a stream
is typically locked with a mutex during access so that another thread
trying to access the same stream will block until the mutex is released.

A program that does not use multiple threads can link with \fBlibsfio.a\fP
while a program that uses multiple threads should link with \fBlibsfio-mt.a\fP.
The libraries \fBlibstdio.a\fP and \fBlibstdio-mt.a\fP provide
corresponding Stdio functions to link with code already compiled using the
native header \fBstdio.h\fP instead of the one provided by Sfio.

.PP
.Ss "DATA TYPES"
.PP
.Ss "  Void_t*"
This defines a type suitable to exchange
data of unknown types between application and Sfio.
\f5Void_t\fP is a macro defined as \f5void\fP for ANSI-C and C++ and
\f5char\fP for other compilation environments.