1SETBUF(3)                  Library Functions Manual                  SETBUF(3)
2
3
4

NAME

6       setbuf, setbuffer, setlinebuf, setvbuf -stream buffering operations
7

SYNOPSIS

9       #include <stdio.h>
10       #include <sys/types.h>
11
12       void
13       setbuf(stream, buf)
14              FILE *stream;
15              char *buf;
16
17       void
18       setbuffer(stream, buf, size)
19              FILE *stream;
20              char *buf;
21              size_t size;
22
23       int
24       setlinebuf(stream)
25              FILE *stream;
26
27       int
28       setvbuf(stream, buf, mode, size)
29              FILE *stream;
30              char *buf;
31              int mode;
32              size_t size
33

DESCRIPTION

35       The  three types of buffering available are unbuffered, block buffered,
36       and line buffered.  When an output stream  is  unbuffered,  information
37       appears on the destination file or terminal as soon as written; when it
38       is block buffered many characters are saved up and written as a  block;
39       when  it  is  line  buffered characters are saved up until a newline is
40       output or input is read from any stream attached to a  terminal  device
41       (typically  stdin).   The  function  fflush(3) may be used to force the
42       block out early.  (See fclose(3).)
43
44       Normally all files are block buffered.  When the  first  I/O  operation
45       occurs on a file, malloc(3) is called, and an optimally-sized buffer is
46       obtained.  If a stream refers to a terminal (as stdout  normally  does)
47       it  is  line  buffered.   The  standard  error  stream stderr is always
48       unbuffered.
49
50       The setvbuf function may be used to alter the buffering behavior  of  a
51       stream.  The mode parameter must be one of the following three macros:
52
53            _IONBF    unbuffered
54
55            _IOLBF    line buffered
56
57            _IOFBF    fully buffered
58
59       The size parameter may be given as zero to obtain deferred optimal-size
60       buffer allocation as usual.   If  it  is  not  zero,  then  except  for
61       unbuffered  files,  the  buf argument should point to a buffer at least
62       size bytes long; this buffer will be used instead of the  current  buf‐
63       fer.   (If  the  size argument is not zero but buf is NULL, a buffer of
64       the given size will be allocated immediately, and  released  on  close.
65       This  is  an  extension to ANSI C; portable code should use a size of 0
66       with any NULL buffer.)
67
68       The setvbuf function may be used at any time,  but  may  have  peculiar
69       side  effects  (such  as  discarding  input  or flushing output) if the
70       stream is ``active''.  Portable applications should call it  only  once
71       on any given stream, and before any I/O is performed.
72
73       The  other  three  calls  are,  in  effect, simply aliases for calls to
74       setvbuf.  Except for the lack of a return value, the setbuf function is
75       exactly equivalent to the call
76
77            setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);
78
79       The  setbuffer function is the same, except that the size of the buffer
80       is up to the caller, rather than being determined by the  default  BUF‐
81       SIZ.  The setlinebuf function is exactly equivalent to the call:
82
83            setvbuf(stream, (char *)NULL, _IOLBF, 0);
84

RETURN VALUES

86       The setvbuf function returns 0 on success, or EOF if the request cannot
87       be honored (note that the stream is still functional in this case).
88
89       The setlinebuf function returns what the equivalent setvbuf would  have
90       returned.
91

SEE ALSO

93       fopen(3), fclose(3), fread(3), malloc(3), puts(3), printf(3)
94

STANDARDS

96       The  setbuf and setvbuf functions conform to ANSI C X3.159-1989 (``ANSI
97       C'').
98

BUGS

100       The setbuffer and setlinebuf functions are not portable to versions  of
101       BSD  before  4.2BSD.   On 2BSD systems, setbuf always uses a 1kb buffer
102       size.
103
104
105
1064th Berkeley Distribution        July 28, 1997                       SETBUF(3)
Impressum