![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to sfio.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / cmd / odist / pax / man / man3|
Return to sfio.3 CVS log | Up to [Research Unix] / researchv10dc / cmd / odist / pax / man / man3 |
1.1 root 1: .TH SFIO 3 "21 August 1990"
2: .SH NAME
3: \fBsfio\fR \- safe/fast string/file input/output
4: .SH SYNOPSIS
5: .ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i
6: .PP
7: .nf
8: .ft 5
9: #include <sfio.h>
10:
11: #define uchar unsigned char
12: #define uint unsigned int
13: #define ulong unsigned long
14:
15: Sfile_t* sfnew(Sfile_t* f, uchar* buf, int size, int fd, int flags);
16: Sfile_t* sfopen(Sfile_t* f, char* string, char* mode);
17: Sfile_t* sfdopen(int fd, char* mode);
18: Sfile_t* sfpopen(char* cmd, char* mode, Sfile_t** fcomp);
19: Sfile_t* sfstack(Sfile_t* base, Sfile_t* top);
20: Sfile_t* sfpushed(Sfile_t* f);
21: Sfile_t* sftmp(int size);
22:
23: int sfpool(Sfile_t* f, Sfile_t* poolf, int mode);
24: Sfdisc_t* sfsetdisc(Sfile_t* f, Sfdisc_t* disc);
25:
26: int sfclose(Sfile_t* f);
27: int sfsync(Sfile_t* f);
28:
29: int sfpeek(Sfile_t* f, uchar** bufp);
30:
31: int sfgetc(Sfile_t* f);
32: int sfungetc(Sfile_t* f, int c);
33: ulong sfgetu(Sfile_t* f);
34: long sfgetl(Sfile_t* f);
35: double sfgetd(Sfile_t* f);
36: char* sfgets(Sfile_t* f, char* buf, int size);
37: int sfread(Sfile_t* f, uchar* buf, int n);
38: int sfscanf(Sfile_t* f, char* format, ...);
39: int sfsscanf(char* s, char* format, ...);
40: int sfvscanf(Sfile_t* f, char* format, va_list args);
41:
42: int sfputc(Sfile_t* f, int c);
43: int sfnputc(Sfile_t* f, int c, int n);
44: int sfputu(Sfile_t* f, ulong v);
45: int sfputl(Sfile_t* f, long v);
46: int sfputd(Sfile_t* f, double v);
47: int sfputs(Sfile_t* f, char* s, int c);
48: int sfwrite(Sfile_t* f, uchar* buf, int n);
49: int sfmove(Sfile_t* fr, Sfile_t* fw, long n, char* seps);
50: int sfprintf(Sfile_t* f, char* format, ...);
51: int sfsprintf(char* s, int size, char* format, ...);
52: int sfvprintf(Sfile_t* f, char* format, va_list args);
53:
54: void sfnotice(void (*noticef)(Sfile_t* f, int type));
55: int sfset(Sfile_t* f, int flags, int i);
56: uchar* sfsetbuf(Sfile_t* f, uchar* buf, int size);
57: int sffileno(Sfile_t* f);
58: int sfeof(Sfile_t* f);
59: int sferror(Sfile_t* f);
60: int sfclearerr(Sfile_t* f);
61: int sfclrlock(Sfile_t* f);
62: int sfslen();
63: int sfulen(ulong v);
64: int sfllen(long v);
65: int sfdlen(double v);
66:
67: long sforigin(Sfile_t* f);
68: long sfseek(Sfile_t* f, long addr, int offset);
69: long sftell(Sfile_t* f);
70:
71: char* sfecvt(double v, int n, int* decpt, int* sign);
72: char* sffcvt(double v, int n, int* decpt, int* sign);
73: .fR
74: .fi
75: .SH DESCRIPTION
76: .PP
77: \fIsfio\fP is a library of functions to perform input/output on
78: objects called \fIsfio\fP streams.
79: Each \fIsfio\fP stream may correpond to some file descriptor (see \fIopen(2)\fP)
80: or some piece of primary memory.
81: A notion of stream stack is supported for
82: processing of data from complexes of streams.
83: Streams can be pooled so that their buffers can be synchronized
84: properly when switching streams for io.
85: It is also possible to change io disciplines by setting alternative
86: functions for read, write and seek.
87: .PP
88: A stream abstraction is represented by the type \f5Sfile_t\fP which
89: is defined in the header file \f5<sfio.h>\fP. A stream is locked while
90: it is being accessed by some \fIsfio\fP function. A locked stream
91: cannot be further accessed by operations that may change its internal states
92: (see \f5sfclrlock()\fP). Any such access fails and returns
93: an appropriate error code.
94: .PP
95: During an io request, if
96: a system call \f5read\fP or \f5write()\fP (or their
97: discipline counterparts) is interrupted,
98: unless a discipline function has been defined to process it,
99: the calling \fIsfio\fP function will resume the respective system call as necessary.
100: The interrupt condition is defined by \f5errno\ ==\ EINTR\fP (see \f5errno.h\fP).
101: To prevent infinite loops, this condition is always cleared before
102: the system call is resumed.
103: .PP
104: In general, \fIsfio\fP functions either return integer or pointer values.
105: In the event of an error, a function that returns integer value will
106: return \f5-1\fP while a function that returns a pointer value will return
107: \f5NULL\fP.
108: .PP
109: A number of bit flags define stream types and their operations.
110: Following are the flags:
111: .IP
112: \f5SF_READ\fP:
113: The stream is readable.
114: .IP
115: \f5SF_WRITE\fP:
116: The stream is writable.
117: .IP
118: \f5SF_STRING\fP:
119: The stream is a string (a byte array) that
120: is readable if \f5SF_READ\fP is specified or
121: writable if \f5SF_WRITE\fP is specified.
122: .IP
123: \f5SF_APPEND\fP:
124: The stream is a file opened for appending data.
125: This means that data written to the stream is always
126: appended at the end of the file.
127: On operating systems where there is no primitive to specify
128: at file opening time that a file is opened for append only,
129: \f5lseek()\fP (or its discipline replacement) will be used on
130: the file stream to approximate this behavior.
131: .IP
132: \f5SF_RELATIVE\fP:
133: If the stream corresponds to a file,
134: no seek is allowed backward beyond the starting point as defined
135: by \f5lseek(fd,0L,1)\fP (or its discipline replacement)
136: when the stream is initialized by \f5sfnew()\fP (below).
137: .IP
138: \f5SF_LINE\fP:
139: The stream is line-oriented. For write-streams, this means that the
140: buffer is flushed whenever a new-line character is output.
141: For read-streams, this means that \f5sfpeek()\fP (below) will return
142: a buffer of data which ends with a new-line. Note that the amount of
143: data that can be returned is limited by the buffer size.
144: .IP
145: \f5SF_KEEPFD\fP:
146: The file descriptor of the stream will be kept opened when the stream is closed.
147: .IP
148: \f5SF_MALLOC\fP:
149: To indicate that the stream buffer was obtained via \f5malloc()\fP
150: and can be reallocated or freed by the package.
151: .IP
152: \f5SF_REUSE\fP:
153: This flag can be set (\f5sfset()\fP so that when the stream is closed,
154: its data structure and associated information such as pool and discipline
155: is not destroyed.
156: It can also be used in a call to \f5sfnew()\fP (see below).
157: .IP
158: \f5SF_SHARE\fP:
159: This flag indicates that the associated stream is a file stream that may
160: be operated on by means beyond straightforward \fIsfio\fP usage (e.g.,
161: by multiple processes).
162: In this case, each io system call (or its discipline replacement) will be
163: preceded by a \f5lseek()\fP (or its discipline replacement) to ensure that
164: the logical stream location corresponds to the physical file location.
165: .PP
166: \f5sfnew(f,buf,size,fd,flags)\fP
167: is the primitive for creating or renewing streams.
168: For file streams, a number of operations are performed to determine
169: seekability, optimal buffer sizes if not specified, etc.
170: Each stream has a origin.
171: The origin of a \f5SF_STRING\fP stream is always \f50L\fP.
172: If a file stream is not seekable, its origin is defined as \f5-1L\fP.
173: Otherwise, its origin is defined as either the current location or \f50L\fP
174: depending on whether or not the flag \f5SF_RELATIVE\fP is turned on.
175: \f5sfseek()\fP operations are relative to this location.
176: The argument \f5f\fP of \f5sfnew()\fP, if not \f5NULL\fP, is a stream to be modified.
177: If it is \f5NULL\fP, a new stream is created.
178: The argument \f5buf\fP, if not \f5NULL\fP, is a buffer to be used.
179: In this case, \f5size\fP should be positive.
180: If \f5size\fP is 0, the stream is unbuffered.
181: If \f5size\fP is negative, \fIsfio\fP will allocate a buffer.
182: The argument \f5fd\fP is a file descriptor (e.g., from \fIopen()\fP)
183: for io operations if the stream is not an \f5SF_STRING\fP stream.
184: The last argument \f5flags\fP is a bit vector composing from the flags described above.
185: The \f5SF_REUSE\fP flag, if given, indicates that the current attributes
186: of the stream \f5f\fP should be used instead of whatever else is defined by \f5flags\fP.
187: .PP
188: \f5sfopen(f,string,mode)\fP
189: is a high-level function based on \f5sfnew()\fP to create new streams from files
190: or strings.
191: The argument \f5f\fP for \f5sfopen()\fP,
192: if not \f5NULL\fP, is a currently opened stream to be
193: closed and replaced by a new stream corresponding to the object \f5string\fP.
194: The argument \f5mode\fP can be any one of: \f5"r"\fP, \f5"r+"\fP,
195: \f5"w"\fP, \f5"w+"\fP, \f5"a"\fP, \f5"a+"\fP, \f5s\fP and \f5s+\fP.
196: The \f5r\fP, \f5w\fP, and \f5a\fP specify read, write and append mode for file streams.
197: In these cases, the argument \f5string\fP defines a path name to a file.
198: The \f5s\fP specifies that \f5string\fP is a nul-terminated string to be opened for read.
199: The \f5+\fP means that the new stream will be opened for both reading and writing.
200: .PP
201: \f5sfdopen(fd,mode)\fP makes a stream using the file descriptor \f5fd\fP.
202: The \f5mode\fP argument is used in the same way as in \f5sfopen()\fP.
203: .PP
204: \f5sfpopen(cmd,mode,fcomp)\fP
205: opens a stream \f5f\fP which is a pipe to (from) the command \f5cmd\fP
206: if the mode is \f5"w"\fP (\f5"r"\fP). If the mode is \f5"w+"\fP or \f5"r+"\fP,
207: another stream for the opposite operation is created and returned in \f5fcomp\fP.
208: Note that if either of these streams is closed, the other is also closed.
209: .PP
210: \f5sfstack(base,top)\fP is used to push or pop stream stacks.
211: Each stream stack is identified by a \f5base\fP stream
212: via which all io operations are performed.
213: Other streams on the stack are locked so that operations that may change
214: their internal states are forbidden.
215: The type of operations that can be done on a stack is defined by
216: the top level stream. If an io operation is performed and the top level stream
217: reaches the end of file condition or an error condition other than interrupts,
218: it is automatically popped and closed (see also \f5sfsetdisc\fP for alternative
219: handling of these conditions).
220: The first argument of \f5sfstack()\fP specifies the \f5base\fP stream.
221: The second argument, \f5top\fP, if not \f5NULL\fP,
222: is pushed on top of the current top stream.
223: In this case, the \f5base\fP stream pointer is returned.
224: If \f5top\fP is \f5NULL\fP, the stack is popped and the pointer to
225: the popped stream is returned.
226: .PP
227: \f5sfpushed(f)\fP returns the pointer to the stream pushed below \f5f\fP.
228: .PP
229: \f5sftmp(size)\fP creates a stream for writing and reading temporary data.
230: If \f5size\fP is negative, the stream is a pure \f5SF_STRING\fP stream.
231: Otherwise, the stream is originally created as a \f5SF_STRING\fP stream
232: with a buffer of the given \f5size\fP. A discipline is set so that
233: when this buffer is exhausted, a real temporary file will be created.
234: Any attempt to change this discipline will also cause the temporary file
235: to be created.
236: .PP
237: \f5sfpool(f,poolf,mode)\fP manages pools of streams.
238: In a pool of streams, only one stream is current.
239: A stream becomes current when it is used for some io operation.
240: When a new stream is to become current,
241: the current stream is synchronized (see \f5sfsync()\fP)
242: if its type matches the type of the pool.
243: The first argument of \f5sfpool()\fP, \f5f\fP, is the stream to be manipulated.
244: The second argument, \f5poolf\fP, determines the operation to be done on \f5f\fP.
245: If \f5poolf\fP is \f5NULL\fP, \f5f\fP is deleted from its current pool.
246: Otherwise, \f5f\fP is put into the same pool with \f5poolf\fP.
247: If \f5poolf\fP is already in a pool, the third argument is ignored.
248: Otherwise, it determines the type of the new pool.
249: \f5mode\fP can be constructed by bitwise or-ing of \f5SF_READ\fP and \f5SF_WRITE\fP.
250: .PP
251: \f5sfsetdisc(f,disc)\fP changes
252: the io-discipline of the stream \f5f\fP, i.e.,
253: to specify alternative functions for read, write, seek, and to handle exceptions.
254: The default discipline consists of the system calls \f5read()\fP, \f5write()\fP,
255: and \f5lseek()\fP.
256: The \f5disc\fP argument is either \f5NULL\fP to reset to the default discipline
257: or a pointer to a \f5Sfdisc_t\fP structure which contains the following fields:
258: .PP
259: .nf
260: \f5int (*readf)();\fP
261: \f5int (*writef)();\fP
262: \f5long (*seekf)();\fP
263: \f5int (*exceptf)();\fP
264: \f5void* handle;\fP
265: .fi
266: .PP
267: The first three fields of \f5Sfdisc_t\fP specify alternative io functions.
268: If any of them is \f5NULL\fP, the corresponding system call is used.
269: A discipline io function, say \f5(*readf)()\fP,
270: is called with 4 arguments.
271: The first argument is the stream pointer.
272: The second and third arguments correspond to the second and third arguments
273: of the respected system call.
274: The fourth argument is the \f5handle\fP field of \f5Sfdisc_t\fP.
275: The exception function, \f5(*exceptf)()\fP, if provided, is called
276: when an exception happens during a read/write operation, when a stream
277: is being closed, or when the discipline is being reset.
278: A read/write operation is said to cause an exception if its return value
279: is zero or negative. It is up to the exception function to determine
280: the type of exception (for example, by examining \f5errno\fP).
281: When \f5(*exceptf)()\fP is called, the stream will be opened for general operations.
282: However, \f5(*exceptf)()\fP should not attempt to close the stream.
283: \f5(*exceptf)()\fP is called as:
284: \f5(*exceptf)(f,type,handle)\fP. \f5type\fP is:
285: \f50\fP when the discipline is being reset,
286: \f5SF_EOF\fP when the stream is being closed,
287: \f5SF_READ\fP when an exception happens during a read operation, and
288: \f5SF_WRITE\fP when an exception happens during a write operation.
289: For the cases of \f5SF_READ\fP and \f5SF_WRITE\fP,
290: the executing \fIsfio\fP function will examine the return value of \f5(*exceptf)()\fP
291: for further actions:
292: \fInegative\fP for immediate return,
293: \fIzero\fP for executing default actions associated with the exception,
294: and \fIpositive\fP for resuming execution.
295: Note that a \f5SF_STRING\fP stream does not perform external io so the
296: io functions are not used. However, an exception occurs whenever
297: an io operation exceeds the stream buffer boundary and
298: \f5(*exceptf)()\fP, if defined, will be called as appropriate.
299: \f5sfsetdisc()\fP returns the pointer to the previous discipline
300: or \f5NULL\fP if an error happened.
301: Finally, it is the application's responsibility to manage the space used
302: by the \f5Sfdisc_t\fP structures.
303: .PP
304: \f5sfclose(f)\fP closes the given stream \f5f\fP and frees up its resources.
305: If \f5f\fP is \f5NULL\fP, all streams are closed.
306: If \f5f\fP is a stack of streams, all streams on the stack are closed.
307: If \f5f\fP is a \f5sfpopen\fP-stream, its companion stream, if any, is also closed.
308: Further, \f5sfclose()\fP will wait until the associated command terminates,
309: then return its exit status.
310: A few file flags affect the behavior of \f5sfclose()\fP.
311: If \f5SF_KEEPFD\fP is on, the underlying file descriptor is not closed.
312: If \f5SF_REUSE\fP is on, \f5sfclose()\fP will only synchronize the buffer
313: and close the file descriptor (subject to \f5SF_KEEPFD\fP).
314: The stream structure is left intact, including
315: pool (\f5sfpool()\fP) or discipline (\f5sfsetdisc()\fP) information.
316: .PP
317: \f5sfsync(f)\fP causes the physical file pointer of the stream
318: \f5f\fP to correspond to its logical position.
319: If \f5f\fP is the base of a stack of streams, all streams on the stack
320: are synchronized. Further, a stacked stream can only be synchronized
321: via its base stream.
322: .PP
323: \f5sfpeek(f,bufp)\fP provides a safe method for enquiring
324: information on the internal buffer of a stream.
325: If \f5bufp\fP is \f5NULL\fP, \f5sfpeek()\fP simply returns the amount of data
326: available in the buffer to read if \f5f\fP is in read mode
327: or the amount of buffer available to write if \f5f\fP is in write mode.
328: If \f5bufp\fP is not \f5NULL\fP, \f5sfpeek()\fP provides access to the buffer.
329: For a read stream, if the buffer is empty, it is filled and,
330: for a write-stream, if the buffer is full, it is flushed.
331: Then, for a read stream, \f5bufp\fP is set to the place in the buffer
332: where data is available and, for a write stream,
333: it is set to where data can be written.
334: The return value of \f5sfseek()\fP indicates how much data or space is available
335: in the buffer. However, if the stream is in \f5SF_LINE|SF_READ\fP mode,
336: the return value will be the data length up to and including the new-line character.
337: In this case, if there is not a new-line character in the buffered data,
338: more data may be read.
339: Note that the buffer location is not advanced by \f5sfpeek()\fP.
340: That must be done by a regular io call such as \f5sfread\fP or \f5sfwrite\fP on
341: the pointer returned in \f5bufp\fP.
342: Finally, \f5sfpeek()\fP treats a read/write-stream like a read-stream
343: (however, see also \f5sfset()\fP).
344: .PP
345: \f5sfgetc(f)\fP returns a byte from the stream \f5f\fP or -1 when an end-of-file
346: or error condition is encountered.
347: .PP
348: \f5sfungetc(f,c)\fP puts the byte \f5c\fP back into the stream \f5f\fP.
349: This is guaranteed to work only after a \f5sfgetc()\fP call.
350: .PP
351: \f5sfgetu(f)\fP, \f5sfgetl(f)\fP, and \f5sfgetd(f)\fP return
352: an \fIunsigned long\fP, a \fIlong\fP value, or a \fIdouble\fP value
353: that was coded in a portable fashion
354: (see \f5sfputu()\fP, \f5sfputl()\fP, and \f5sfputd()\fP).
355: If there is not enough data to decode a value,
356: these functions will return \f5-1\fP and the stream is set in an error state
357: (\f5see \f5sferror()\fP).
358: .PP
359: \f5sfgets(f,buf,size)\fP reads a line of input from the stream \f5f\fP.
360: If \f5buf\fP is not \f5NULL\fP and \f5size\fP is positive, \f5sfgets\fP
361: reads up to \f5size-1\fP characters into the buffer \f5buf\fP.
362: Otherwise, the characters are read into a static area that is dynamically
363: grown as necessary. Thus, in this case, there is no limit to line length.
364: A nul-character is appended after the input characters.
365: \f5sfgets()\fP returns the pointer to the new string or \f5NULL\fP when
366: no data was read due to end-of-file or an error condition.
367: After a string is read, its length can be found using \f5sfslen()\fP.
368: .PP
369: \f5sfread(f,buf,n)\fP reads up to \f5n\fP bytes from the stream \f5f\fP and
370: stores them in the given buffer \f5buf\fP.
371: It returns the number of bytes actually read.
372: .PP
373: \f5sfscanf(f,format,...)\fP scans a number of items from the stream \f5f\fP.
374: The item types are determined from the string \f5format\fP.
375: See \fIfscanf()\fP (UNIX User's Manual, Section 3) for details on predefined formats.
376: The standardly supported formats are:
377: \f5i, I, d, D, u, U, o, O, x, X, f, F, e, E, g, G, c, %, s,\fP and \f5[]\fP.
378: The \f5sfscanf()\fP interface also supports additional formats as described below.
379: .IP
380: The pattern \f5%&\fP indicates that the next argument in the argument list of
381: \f5sfscanf()\fP is a function, say \f5(*extf)()\fP, to process patterns that are not
382: predefined by the \f5sfscanf()\fP interface.
383: The prototype of \f5(*extf)()\fP is:
384: .nf
385: \f5int (*extf)(Sfile_t* f, int fmt, int length, char** rv);\fP
386: .fi
387: \f5f\fP is the same input stream passed to \f5sfvscanf\fP.
388: \f5fmt\fP is the pattern to be processed.
389: \f5length\fP, if non-negative, is the maximum number of input bytes
390: to be read in processing the pattern,
391: \f5rv\fP is used to return the ``address'' of the value to be assigned.
392: \f5(*extf)()\fP returns the size of the value to be assigned.
393: A negative return value from \f5(*extf)()\fP means that the specified pattern
394: cannot be handled. This pattern is treated as if it is not matched.
395: .IP
396: The pattern \f5%@\fP indicates that the next argument in the argument list \f5args\fP
397: is a function, say \f5(*argf)()\fP, to process the values of matched patterns.
398: The prototype of \f5(*argf)()\fP is:
399: .nf
400: \f5int (*argf)(int fmt, char* value, int n)\fP;
401: .fi
402: If the return value of \f5(*argf)()\fP is negative, the processing
403: of the current format string will be stopped (see \f5%$\fP below).
404: \f5fmt\fP determines the type of \f5value\fP: \f5f\fP for \fIfloat\fP,
405: \f5F\fP for \fIdouble\fP, \f5h\fP for \fIshort\fP, \f5d\fP for \fIint\fP,
406: \f5D\fP for \fIlong\fP, \f5s\fP for \fIchar*\fP. Any other value for \f5fmt\fP
407: means that it is an extended pattern and \f5value\fP contains an address
408: to the scanned value. \f5n\fP contains the size of the object if it is a
409: primitive type. If the object is \f5char*\fP or the address of the scanned
410: value of an extended format, \f5n\fP is the length of this object.
411: .IP
412: The pattern \f5%:\fP indicates that the next two arguments in the argument list
413: \f5args\fP define a new pair of format string and a list of arguments of
414: the type \f5va_list\fP (see \f5varargs.h\fP or \f5stdarg.h\fP).
415: The new pair is pushed on top of the stack and the scanning process continues with them.
416: The top pair of format string and argument list is popped when the processing
417: of the format string is stopped. When a new pair is stacked,
418: \f5(*argf)()\fP and \f5(*extf)()\fP are inherited.
419: They are reset when the stack is popped.
420: .PP
421: \f5sfsscanf(s,format,...)\fP is similar to \f5sfscanf()\fP
422: but it scans data from the string \f5s\fP.
423: .PP
424: \f5sfvscanf(f,format,args)\fP is the primitive underlying \f5sfscanf()\fP
425: and \f5sfscanf()\fP. It also provides a portable variable argument interface.
426: Programs that use \f5sfvscanf()\fP must include either of \f5varargs.h\fP
427: or \f5stdargs.h\fP as appropriate.
428: .PP
429: \f5sfputc(f,c)\fP writes the byte \f5c\fP to the stream \f5f\fP.
430: .PP
431: \f5sfnputc(f,c,n)\fP writes the byte \f5c\fP to the stream \f5f\fP \f5n\fP times.
432: It returns the number of bytes successfully written.
433: .PP
434: \f5sfputu(f,v)\fP, \f5sfputl(f,v)\fP write the \fIunsigned long\fP or \fIlong\fP
435: value \f5v\fP in a format that is byte-order transparent.
436: \f5sfputd(f,v)\fP writes the \fIdouble\fP value \f5v\fP in a portable format.
437: Portability across two different machines
438: requires that the bit order in a byte is the same on both machines.
439: \f5sfputd()\fP also relies on the functions \f5ldexp()\fP and \f5frexp()\fP
440: (See \fIfrexp.3\fP) for coding.
441: Upon success, \f5sfputu()\fP, \f5sfputl()\fP and \f5sfputd()\fP
442: return the number of bytes output.
443: .PP
444: \f5sfputs(f,s,c)\fP writes the null-terminated string \f5s\fP to the stream \f5f\fP.
445: If \f5c\fP is not 0, it is a character to be appended after the string has been output.
446: \f5sfputs()\fP returns the number of bytes written.
447: .PP
448: \f5sfwrite(f,buf,n)\fP writes out \f5n\fP bytes from the buffer \f5buf\fP to the
449: stream \f5f\fP. It returns the number of bytes written.
450: .PP
451: \f5sfmove(fr,fw,n,seps)\fP moves \f5n\fP objects
452: from the stream \f5fr\fP to the stream \f5fw\fP.
453: If either \f5fr\fP or \f5fw\fP is \f5NULL\fP, it acts
454: as if it is a stream corresponding to \fI/dev/null\fP.
455: If \f5n\fP is \f5<0\fP, all of \f5fr\fP is moved.
456: If \f5seps\fP is \f5NULL\fP or an empty string, the objects to be moved are bytes.
457: Otherwise, the moved objects are records separated by bytes defined in \f5seps\fP.
458: In \f5seps\fP, if the first two bytes is \f5\e0\fP, it is mapped to the zero byte.
459: All other cases map a byte to itself.
460: \f5sfmove()\fP returns the number of objects moved.
461: .PP
462: \f5sfprintf(f,format,...)\fP writes out data in
463: a format as defined by the string \f5format\fP.
464: See \fIfprintf()\fP (UNIX User's Manual, Section 3) for details on predefined
465: conversion formats.
466: The standardly supported formats are:
467: \f5n, s, c, %, h, i, d, p, u, o, x, X, g, G, e, E, f,\fP and \f5F\fP.
468: \f5sfprintf()\fP also supports additional formats as described below.
469: .IP
470: The pattern \f5%&\fP indicates that the next argument
471: is a function, say \f5(*extf)()\fP, to interpret patterns not yet defined
472: by \f5sfprintf()\fP.
473: The prototype of \f5(*extf)()\fP is:
474: .nf
475: \f5int (*extf)(void* value, int fmt, int precis, char** sp);\fP
476: .fi
477: \f5value\fP is the value to be formatted.
478: \f5fmt\fP is the pattern to format the value.
479: \f5precis\fP is the amount of precision required.
480: \f5sp\fP is used to return the address of a string containing the formatted value.
481: If upon returning from \f5(*extf)()\fP, \f5*sp\fP is \f5NULL\fP, the pattern \f5fmt\fP
482: is treated as if it is not matched.
483: Otherwise, the return value of \f5(*extf)()\fP, if nonnegative, is taken as the length
484: of the string returned in \f5sp\fP. If not, the string is considered null-terminated.
485: The string \f5*sp\fP is processed as if the pattern \f5`s'\fP was specified.
486: .IP
487: The pattern \f5%@\fP indicates that the next argument is a function, say \f5(*argf)()\fP,
488: to get arguments. As long as \f5(*argf)()\fP is defined, the argument list is ignored.
489: The prototype of \f5(*argf)()\fP is:
490: .nf
491: \f5int (*argf)(int fmt, char* val)\fP;
492: .fi
493: \f5fmt\fP is the pattern to be processed.
494: Following are ASCII characters and corresponding types:
495: \f5@\fP for getting a new \f5(*argf)()\fP,
496: \f5&\fP for getting a new \f5(*extf)()\fP,
497: \f51\fP for getting a new format string for stacking,
498: \f52\fP for getting a new argument list for stacking,
499: \f5d\fP for \fIint\fP,
500: \f5D\fP for \fIlong\fP,
501: \f5f\fP for \fIfloat\fP,
502: \f5F\fP for \f5double\fP, and
503: \f5s\fP for \fIchar*\fP.
504: If \f5(*extf)()\fP is defined, and an undefined pattern is encountered,
505: \f5(*argf)()\fP will be called with this pattern.
506: \f5val\fP is an address to store the value to be formatted.
507: The return value of \f5(*argf)()\fP, if negative, stops the processing
508: of the current format (see below).
509: .IP
510: The pattern \f5%:\fP indicates that the next two arguments define
511: a pair of format string and argument list of the type \f5va_list\fP.
512: If the argument getting function \f5(*argf)()\fP is already defined,
513: it is called with the argument \f5fmt\fP being the characters
514: \f51\fP and \fP2\fP for the new format string and argument list respectively.
515: The new pair is stacked on top and processing continue from there.
516: The top pair of format string and argument is popped when the format string
517: is exhausted. When a new pair is pushed, \f5(*argf)()\fP and \f5(*extf)()\fP
518: are inherited. When a pair is popped, these functions will be reset.
519: .PP
520: \f5sfsprintf(s,size,format,...)\fP is similar to \f5sfprintf()\fP
521: but it is used to format
522: the character array \f5s\fP which is of size \f5size\fP.
523: The length of the resulting string can be gotten via \f5sfslen()\fP.
524: .PP
525: \f5sfvprintf(f,format,args)\fP is the primitive underlying \f5sfprintf()\fP
526: and \f5sfsprintf()\fP. It provides a portable variable argument interface.
527: Programs that use \f5sfvprintf()\fP must include either of \f5varargs.h\fP
528: or \f5stdargs.h\fP as appropriate.
529: .PP
530: \f5sfnotice(noticef)\fP sets a function \f5(*noticef)()\fP which will
531: be called whenever a stream is created or closed.
532: \f5(*noticef)()\fP is called with two arguments.
533: The first argument is the stream pointer and
534: the second argument is either \f50\fP or \f5SF_EOF\fP to indicate
535: whether the stream is being opened or being closed.
536: .PP
537: \f5sfset(f,flags,i)\fP sets flags or file descriptor for the stream \f5f\fP.
538: If \f5flags\fP is the value \f5SF_EOF\fP, the file descriptor of the stream
539: is changed to the value in \f5i\fP. In this case, \f5sfset()\fP returns \f5-1\fP
540: on error or \f5i\fP on success.
541: If \f5flags\fP is not \f5SF_EOF\fP, it defines a collection of flags to be
542: turned on or off depending on whether \f5i\fP is non-zero or zero.
543: The flags that can be turned on or off are:
544: \f5SF_READ\fP, \f5SF_WRITE\fP,
545: \f5SF_LINE\fP, \f5SF_KEEPFD\fP, \f5SF_REUSE\fP, \f5SF_MALLOC\fP and \f5SF_SHARE\fP.
546: The flags \f5SF_READ\fP and \f5SF_WRITE\fP can be used in a call to \f5sfset()\fP
547: only if the stream \f5f\fP was opened for both read and write.
548: Turning off one of these flags means that the stream is to be treated as
549: if it was opened with the other flag exclusively (see \f5sfpeek()\fP).
550: In this case, \f5sfset()\fP returns the entire set of flags controlling the stream.
551: Thus, the current set of flags can be found by \f5sfset(f,0,0)\fP.
552: .PP
553: \f5sfsetbuf(f,buf,size)\fP changes the current buffer of the stream \f5f\fP to
554: the new buffer \f5buf\fP. If the stream is a \f5SF_WRITE\fP stream,
555: any data still in the current buffer is thrown away.
556: Thus, if an application desires to preserve such data, it should
557: call \f5sfsync()\fP before trying to switch buffers.
558: If \f5size\fP is positive, \f5buf\fP is taken as a buffer of the given size.
559: If \f5size\fP is zero, the stream will be unbuffered.
560: If \f5size\fP is negative, an internal buffer is allocated.
561: \f5sfsetbuf()\fP returns the address of the old buffer.
562: .PP
563: \f5sffileno(f)\fP returns the file descriptor of the stream \f5f\fP.
564: .PP
565: \f5sfeof(f)\fP tells whether there is any more data in the stream \f5f\fP.
566: .PP
567: \f5sforigin(f)\fP returns the origin location in the stream \f5f\fP (see \f5sfnew()\fP).
568: If this location is \f5-1L\fP, the stream is not seekable.
569: Note that the standard streams \f5sfstdin\fP, \f5sfstdout\fP, and \f5sfstderr\fP,
570: though statically allocated, are not initialized until an operation that may
571: affect its internal structure. Thus, the return value \f50L\fP of \f5sforigin()\fP
572: on such an initialized stream is not reliable.
573: .PP
574: \f5sferror(f)\fP and \f5sfclearerr(f)\fP returns or clears the error condition
575: of the stream \f5f\fP. Note that the error condition of a stream does not prevent
576: further io operations to be performed on them.
577: .PP
578: \f5sfclrlock(f)\fP clears the lock on a locked stream.
579: Though this is unsafe, it is useful for emergency access
580: to a locked stream or to clear a stream left locked because
581: of non-local jumps (e.g., \f5longjmp()\fP).
582: .PP
583: \f5sfslen()\fP returns the length of the string most recently obtained
584: via a \f5sfgets()\fP, \f5sfsprintf()\fP, \f5sfecvt()\fP or \f5sffcvt()\fP call.
585: .PP
586: \f5sfulen(v)\fP, \f5sfllen(v)\fP and \f5sfdlen(v)\fP
587: return the number of bytes required to code the
588: \fIunsigned long\fP, \fIlong\fP or \fIdouble\fP value \f5v\fP.
589: .PP
590: \f5sfseek(f,addr,offset)\fP sets the next read/write location for the stream \f5f\fP
591: at a new address defined by the combination of \f5addr\fP and \f5offset\fP.
592: If \f5offset\fP is 0, \f5addr\fP is offset from the origin of the stream
593: (see \f5sfnew()\fP).
594: If \f5offset\fP is 1, \f5addr\fP is offset from the current location.
595: Note that if \f5f\fP was opened for appending (\f5SF_APPEND\fP) and the last operation
596: done on it was a write operation, the \fIcurrent location\fP is at the physical
597: end of file.
598: If \f5offset\fP is 2, \f5addr\fP is offset from the \fIphysical\fP end of the stream.
599: In all cases, \f5sfseek()\fP is not allowed to seek backward beyond the stream origin.
600: .PP
601: \f5sftell(f)\fP returns the current location in the stream \f5f\fP relative
602: to the stream origin (see \f5sfnew()\fP).
603: As with \f5sfseek()\fP, if \f5f\fP was opened for appending (\f5SF_APPEND\fP)
604: and the last operation done on it was a write operation,
605: the \fIcurrent location\fP is at the physical end of file.
606: If the stream \f5f\fP is unseekable, \f5sftell\fP returns the number of bytes
607: read from or written to \f5f\fP.
608: .PP
609: \f5sfecvt(v,n,decpt,sign)\fP and
610: \f5sffcvt(v,n,decpt,sign)\fP are functions to convert floating values to ASCII.
611: They corresponds to the standard functions \f5ecvt()\fP and \f5fcvt()\fP.
612: The length of the conversion string most recently done by
613: \f5sfecvt()\fP or \f5sffcvt()\fP can be found by \f5sfslen()\fP.
614: .PP
615: .SH HISTORY AND FUTURE CONSIDERATIONS
616: \fIsfio\fP has similar functionality, but is more general
617: than the \fIstdio\fP package.
618: It grows from our dissatisfaction with the awkwardness, fragility
619: and inefficiency in \fIstdio\fP.
620: An example of \fIstdio\fP awkwardness is that
621: even if a stream was opened for read and write,
622: the application code cannot arbitrarily mix read and write operations.
623: An earlier attempt was made at rewriting \fIstdio\fP.
624: This failed due to problems that arise when linking with code based on \fIstdio\fP.
625: Changing the name space reduces this type of problems.
626: It also allows us to both stream-line and extend the interface as appropriate.
627: .SH AUTHORS
628: Kiem-Phong Vo (att!ulysses!kpv) and David G. Korn (att!ulysses!dgk).
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.