292 lines
5.5 KiB
Plaintext
292 lines
5.5 KiB
Plaintext
'\"macro stdmacro
|
|
.if n .pH g3s.setbuf @(#)setbuf 30.2 of 12/25/85
|
|
.nr X
|
|
.Op c p a
|
|
.if \nX=0 .ds x} SETBUF 3S "C Programming Language Utilities" "\&"
|
|
.if \nX=1 .ds x} SETBUF 3S "C Programming Language Utilities"
|
|
.if \nX=2 .ds x} SETBUF 3S "" "\&"
|
|
.if \nX=3 .ds x} SETBUF "" "" "\&"
|
|
.Op
|
|
.Op f
|
|
.if \nX=0 .ds x} SETBUF 3F "Fortran Programming Language Utilities" "\&"
|
|
.if \nX=1 .ds x} SETBUF 3F "Fortran Programming Language Utilities"
|
|
.if \nX=2 .ds x} SETBUF 3F "" "\&"
|
|
.if \nX=3 .ds x} SETBUF "" "" "\&"
|
|
.Op
|
|
.TH \*(x}
|
|
.SH NAME
|
|
setbuf, setvbuf, setbuffer, setlinebuf \- assign buffering to a
|
|
.Op c p a
|
|
stream
|
|
.Op
|
|
.Op f
|
|
logical unit
|
|
.Op
|
|
.Op f
|
|
.SH FORTRAN SYNOPSIS
|
|
.B #include <stdio.h>
|
|
.PP
|
|
.B character *(BUFSIZ+8) buf
|
|
.br
|
|
.B integer type, size, setbuf, setvbuf, setbuffer, setlinebuf
|
|
.PP
|
|
.B setbuf (lun, buf)
|
|
.PP
|
|
.B "setvbuf (lun, buf, size)"
|
|
.PP
|
|
.B "setbuffer (lun, buf, size)"
|
|
.PP
|
|
.B setlinebuf (lun)
|
|
.Op
|
|
.Op c p a
|
|
.SH C SYNOPSIS
|
|
.B #include <stdio.h>
|
|
.PP
|
|
.B void setbuf (\s-1FILE\s+1 \(**stream, char \(**buf);
|
|
.PP
|
|
.B "int setvbuf (\s-1FILE\s+1 \(**stream, char \(**buf, int type, size_t size);"
|
|
.PP
|
|
.B "int setbuffer (\s-1FILE\s+1 \(**stream, char \(**buf, int size);"
|
|
.PP
|
|
.B int setlinebuf (\s-1FILE\s+1 \(**stream);
|
|
.Op
|
|
.SH DESCRIPTION
|
|
The three types of buffering available are unbuffered, fully buffered,
|
|
and line buffered.
|
|
When an output
|
|
.Op c p a
|
|
stream
|
|
.Op
|
|
.Op f
|
|
unit
|
|
.Op
|
|
is unbuffered, information appears on the
|
|
destination file or terminal as soon as written;
|
|
when it is fully buffered many characters are saved up and written as a block;
|
|
when it is line buffered characters are saved up until a newline is
|
|
encountered or input is read from stdin.
|
|
.Op c p a
|
|
.IR Fflush (3S)
|
|
.Op
|
|
.Op f
|
|
.IR flush (3F)
|
|
.Op
|
|
may be used to force the block out early.
|
|
By default, output to a terminal is line buffered and
|
|
all other input/output is fully buffered.
|
|
.PP
|
|
.I Setbuf\^
|
|
may be used after a
|
|
.Op c p a
|
|
stream
|
|
.Op
|
|
.Op f
|
|
unit
|
|
.Op
|
|
has been opened but before it
|
|
is read or written.
|
|
It causes the array pointed to by
|
|
.I buf\^
|
|
to be used instead of an automatically allocated buffer.
|
|
If
|
|
.I buf\^
|
|
is the
|
|
.SM NULL
|
|
pointer input/output will be completely unbuffered.
|
|
If
|
|
.I buf\^
|
|
is not the
|
|
.SM NULL
|
|
pointer and the indicated
|
|
.Op c p a
|
|
.I stream\^
|
|
.Op
|
|
.Op f
|
|
.I lun\^
|
|
.Op
|
|
is open to a terminal, output will be line buffered.
|
|
.PP
|
|
A constant
|
|
.SM
|
|
.B BUFSIZ,
|
|
defined in the
|
|
.B <stdio.h>
|
|
header file,
|
|
indicates the assumed minimum length of
|
|
.IR buf .
|
|
It is wise to allocate a few words of extra space for
|
|
.IR buf ,
|
|
to allow for any synchronization problems resulting from
|
|
signals occurring at inopportune times.
|
|
A good choice (and the one used by default in
|
|
.IR stdio (3s))
|
|
is
|
|
.PP
|
|
.RS
|
|
.Op c p a
|
|
char buf[\s-1BUFSIZ + 8\s0];
|
|
.Op
|
|
.Op f
|
|
character *(\s-1BUFSIZ + 8\s0) buf
|
|
.Op
|
|
.RE
|
|
.PP
|
|
.I Setvbuf\^
|
|
may be used after a
|
|
.Op c p a
|
|
stream
|
|
.Op
|
|
.Op f
|
|
unit
|
|
.Op
|
|
has been opened
|
|
but before it is read or written.
|
|
.I Type\^
|
|
determines how
|
|
.Op c p a
|
|
.I stream\^
|
|
.Op
|
|
.Op f
|
|
.I lun\^
|
|
.Op
|
|
will be buffered.
|
|
Legal values for
|
|
.I type\^
|
|
(defined in
|
|
.BR <stdio.h> )
|
|
are:
|
|
.TP .85i
|
|
.SM _IOFBF
|
|
causes input/output to be fully buffered.
|
|
.TP
|
|
.SM _IOLBF
|
|
causes output to be line buffered;
|
|
the buffer will be flushed when a newline
|
|
is written, the buffer is full, or input is requested.
|
|
.TP
|
|
.SM _IONBF
|
|
causes input/output to be completely unbuffered.
|
|
.P
|
|
If input/output is unbuffered,
|
|
.I buf
|
|
and
|
|
.I size
|
|
are ignored.
|
|
For buffered input/output,
|
|
if
|
|
.I buf\^
|
|
is not the
|
|
.SM NULL
|
|
pointer and
|
|
.I size\^
|
|
is greater than eight,
|
|
the array it points to
|
|
will be used for buffering.
|
|
In this case,
|
|
.I size\^
|
|
specifies the length of this array.
|
|
The actual buffer will consist of the first
|
|
.IR size -8
|
|
bytes of
|
|
.I buf\^
|
|
(see the discussion of
|
|
.SM
|
|
.B BUFSIZ
|
|
above).
|
|
If
|
|
.I buf\^
|
|
is the
|
|
.SM NULL
|
|
pointer, or
|
|
.I size\^
|
|
is less than eight,
|
|
space will be allocated to accommodate a buffer. This
|
|
buffer will be of length
|
|
.SM
|
|
.B BUFSIZ.
|
|
(The actual space allocated will be eight bytes longer.)
|
|
.PP
|
|
.I Setbuffer
|
|
and
|
|
.I setlinebuf
|
|
are provided for compatibility with 4.3BSD.
|
|
.IR Setbuffer ,
|
|
an alternate form of
|
|
.IR setbuf ,
|
|
is used after a
|
|
.Op c p a
|
|
stream
|
|
.Op
|
|
.Op f
|
|
unit
|
|
.Op
|
|
has been opened but before it is read or written.
|
|
The character array
|
|
.I buf
|
|
whose size is determined by the
|
|
.I size
|
|
argument is used instead of an automatically allocated buffer. If
|
|
.I buf
|
|
is the constant pointer
|
|
.SM
|
|
.BR NULL ,
|
|
input/output will be completely unbuffered.
|
|
.PP
|
|
.I Setlinebuf
|
|
is used to change
|
|
.I stdout
|
|
or
|
|
.I stderr
|
|
from fully buffered or unbuffered to line buffered.
|
|
Unlike the other routines,
|
|
it can be used at any time that the file descriptor is active.
|
|
.SH "SEE ALSO"
|
|
.Op c p a
|
|
fopen(3S), fflush(3S), getc(3S), malloc(3C), putc(3S), stdio(3S).
|
|
.Op
|
|
.Op f
|
|
flush(3F), perror(3F).
|
|
.Op
|
|
.SH "DIAGNOSTICS"
|
|
Success is indicated by
|
|
.Op c p a
|
|
.I setvbuf\^
|
|
and
|
|
.I setbuffer\^
|
|
returning zero.
|
|
.Op
|
|
.Op f
|
|
a zero return value. A non-zero return value indicates an error. The
|
|
value of \f2errno\f1 can be examined to determine the cause of the
|
|
error.
|
|
.Op
|
|
If it is necessary to allocate a
|
|
buffer and the attempt is unsuccessful,
|
|
.I setvbuf\^
|
|
and
|
|
.I setbuffer\^
|
|
return a non-zero value.
|
|
.I Setvbuf\^
|
|
will also return non-zero if
|
|
the value of
|
|
.I type\^
|
|
is not one of _IONBF, _IOLBF, or _IOFBF.
|
|
.SH NOTES
|
|
A common source of error is allocating buffer space
|
|
as an ``automatic'' variable in a code block, and then
|
|
failing to close the
|
|
.Op c p a
|
|
stream
|
|
.Op
|
|
.Op f
|
|
unit
|
|
.Op
|
|
in the same block.
|
|
.Op f
|
|
.sp
|
|
These functions cannot be used on direct unformatted units.
|
|
.Op
|
|
.\" .so /pubs/tools/origin.att
|
|
.\" @(#)setbuf.3s 6.2 of 10/20/83
|
|
.Ee
|