manual page distributed with 4.2BSD

SCCS-vsn: lib/libc/stdio/setbuf.3 5.1

diff --git a/usr/src/lib/libc/stdio/setbuf.3 b/usr/src/lib/libc/stdio/setbuf.3
index 5e49609..56eadef 100644 (file)
--- a/usr/src/lib/libc/stdio/setbuf.3
+++ b/usr/src/lib/libc/stdio/setbuf.3
@@ -2,12 +2,12 @@
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"

-.\"    @(#)setbuf.3    4.1 (Berkeley) %G%
+.\"    @(#)setbuf.3    5.1 (Berkeley) %G%

 .\"
 .\"

-.TH SETBUF 3S 
+.TH SETBUF 3S  "19 January 1983"

 .UC 4
 .SH NAME
 .UC 4
 .SH NAME

-setbuf \- assign buffering to a stream
+setbuf, setbuffer, setlinebuf \- assign buffering to a stream

 .SH SYNOPSIS
 .B #include <stdio.h>
 .PP
 .SH SYNOPSIS
 .B #include <stdio.h>
 .PP


@@ -18,20 +18,59 @@ setbuf \- assign buffering to a stream
 .B *stream;
 .br
 .B char *buf;
 .B *stream;
 .br
 .B char *buf;

+.PP
+.B setbuffer(stream, buf, size)
+.br
+.SM
+.B FILE
+.B *stream;
+.br
+.B char *buf;
+.br
+.B int size;
+.PP
+.B setlinebuf(stream)
+.br
+.SM
+.B FILE
+.B *stream;

 .SH DESCRIPTION
 .SH DESCRIPTION

+The three types of buffering available are unbuffered, block buffered,
+and line buffered.
+When an output stream is unbuffered, information appears on the
+destination file or terminal as soon as written;
+when it is block 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.
+.I Fflush
+(see 
+.IR fclose (3S))
+may be used to force the block out early.
+Normally all files are block buffered.
+A buffer is obtained from
+.IR  malloc (3)
+upon the first
+.I getc
+or
+.IR  putc (3S)
+on the file.
+If the standard stream
+.B stdout
+refers to a terminal it is line buffered.
+The standard stream
+.B stderr
+is always unbuffered.
+.PP

 .I Setbuf
 .I Setbuf

-is used after a stream has been opened but before it
-is read or written.
-It causes the character array
+is used after a stream has been opened but before it is read or written.
+The character array

 .I buf
 .I buf

-to be used instead of an automatically allocated buffer.
-If
+is used instead of an automatically allocated buffer.  If

 .I buf
 is the constant pointer
 .SM
 .B NULL,
 input/output will be completely unbuffered.
 .I buf
 is the constant pointer
 .SM
 .B NULL,
 input/output will be completely unbuffered.

-.PP

 A manifest constant 
 .SM
 .B BUFSIZ
 A manifest constant 
 .SM
 .B BUFSIZ


@@ -40,22 +79,60 @@ tells how big an array is needed:
 .B char
 buf[BUFSIZ];
 .PP
 .B char
 buf[BUFSIZ];
 .PP

-A buffer is normally obtained from
-.IR  malloc (3)
-upon the first
-.I getc
+.IR Setbuffer ,
+an alternate form of 
+.IR setbuf ,
+is used after a stream 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
 or

-.IR  putc (3)
-on the file,
-except that the standard output is line buffered when directed to a terminal.
-Other output streams directed to terminals,
-and the standard error stream

 .I stderr
 .I stderr

-are normally not buffered.
-If the standard output is line buffered, then it is flushed each time
-data is read from the standard input by
-.IR read (2).
+from block buffered or unbuffered to line buffered.
+Unlike
+.I setbuf
+and
+.I setbuffer
+it can be used at any time that the file descriptor is active.
+.PP
+A file can be changed from unbuffered or line buffered to block buffered
+by using
+.I freopen
+(see
+.IR fopen (3S)).
+A file can be changed from block buffered or line buffered to unbuffered
+by using
+.I freopen
+followed by
+.I setbuf
+with a buffer argument of 
+.SM
+.BR NULL .

 .SH "SEE ALSO"
 .SH "SEE ALSO"

-fopen(3), getc(3), putc(3), malloc(3)
+fopen(3S),
+getc(3S),
+putc(3S),
+malloc(3),
+fclose(3S),
+puts(3S),
+printf(3S),
+fread(3S)

 .SH BUGS
 The standard error stream should be line buffered by default.
 .SH BUGS
 The standard error stream should be line buffered by default.

+.LP
+The
+.I setbuffer
+and
+.I setlinebuf
+functions are not portable to non 4.2 BSD versions of UNIX.