Move guts of setbuf.3 into setvbuf.3 to make it clear which one

should be used in new code.

3 files changed, 191 insertions, 117 deletions

diff --git a/lib/libc/stdio/Makefile.inc b/lib/libc/stdio/Makefile.inc
index 3d19193e315..865419b360c 100644
--- a/lib/libc/stdio/Makefile.inc
+++ b/lib/libc/stdio/Makefile.inc
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile.inc,v 1.26 2014/08/31 02:21:18 guenther Exp $
+#	$OpenBSD: Makefile.inc,v 1.27 2014/11/25 17:01:49 millert Exp $
 
 # stdio sources
 .PATH: ${LIBCSRCDIR}/stdio
@@ -23,9 +23,9 @@ SRCS+=	asprintf.c clrerr.c fclose.c fdopen.c feof.c ferror.c fflush.c fgetc.c \
 
 MAN+=	fclose.3 ferror.3 fflush.3 fgetln.3 fgets.3 fmemopen.3 fopen.3 fputs.3 \
 	fread.3 fseek.3 funopen.3 getc.3 mktemp.3 open_memstream.3 perror.3 \
-	printf.3 putc.3 remove.3 scanf.3 setbuf.3 stdio.3 tmpnam.3 ungetc.3 \
-	fgetws.3 fputws.3 fwide.3 getwc.3 putwc.3 ungetwc.3 wprintf.3 wscanf.3 \
-	getdelim.3
+	printf.3 putc.3 remove.3 scanf.3 setbuf.3 setvbuf.3 stdio.3 tmpnam.3 \
+	ungetc.3 fgetws.3 fputws.3 fwide.3 getwc.3 putwc.3 ungetwc.3 wprintf.3 \
+	wscanf.3 getdelim.3
 
 MLINKS+=ferror.3 clearerr.3 ferror.3 feof.3 ferror.3 fileno.3
 MLINKS+=fflush.3 fpurge.3
@@ -50,7 +50,7 @@ MLINKS+=printf.3 fprintf.3 printf.3 snprintf.3 printf.3 sprintf.3 \
 MLINKS+=putc.3 fputc.3 putc.3 putchar.3 putc.3 putw.3
 MLINKS+=scanf.3 fscanf.3 scanf.3 sscanf.3 scanf.3 vfscanf.3 scanf.3 vscanf.3 \
 	scanf.3 vsscanf.3
-MLINKS+=setbuf.3 setbuffer.3 setbuf.3 setlinebuf.3 setbuf.3 setvbuf.3
+MLINKS+=setbuf.3 setbuffer.3 setbuf.3 setlinebuf.3
 MLINKS+=tmpnam.3 tempnam.3 tmpnam.3 tmpfile.3
 MLINKS+=wprintf.3 fwprintf.3 wprintf.3 swprintf.3 wprintf.3 vwprintf.3 \
 	wprintf.3 vfwprintf.3 wprintf.3 vswprintf.3
diff --git a/lib/libc/stdio/setbuf.3 b/lib/libc/stdio/setbuf.3
index 123e9a01260..1a6873c8a7c 100644
--- a/lib/libc/stdio/setbuf.3
+++ b/lib/libc/stdio/setbuf.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: setbuf.3,v 1.14 2013/07/17 05:42:11 schwarze Exp $
+.\"	$OpenBSD: setbuf.3,v 1.15 2014/11/25 17:01:49 millert Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -31,14 +31,13 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 17 2013 $
+.Dd $Mdocdate: November 25 2014 $
 .Dt SETBUF 3
 .Os
 .Sh NAME
 .Nm setbuf ,
 .Nm setbuffer ,
-.Nm setlinebuf ,
-.Nm setvbuf
+.Nm setlinebuf
 .Nd stream buffering operations
 .Sh SYNOPSIS
 .In stdio.h
@@ -48,94 +47,23 @@
 .Fn setbuffer "FILE *stream" "char *buf" "size_t size"
 .Ft int
 .Fn setlinebuf "FILE *stream"
-.Ft int
-.Fn setvbuf "FILE *stream" "char *buf" "int mode" "size_t size"
 .Sh DESCRIPTION
-The three types of stream 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 line buffered, characters are saved up until a newline
-.Pq Ql \en
-is output or input is read from any stream attached to a terminal device
-(typically
-.Em stdin ) .
-.Pp
-The
-.Xr fflush 3
-function may be used to force the block out early.
-.Pp
-Normally, all files are block buffered.
-When the first
-.Tn I/O
-operation occurs on a file,
-.Xr malloc 3
-is called,
-and an optimally sized buffer is obtained.
-If a stream refers to a terminal
-(as
-.Em stdout
-normally does), it is line buffered.
-.Pp
-The standard error stream
-.Em stderr
-is initially unbuffered.
-.Pp
-The
-.Fn setvbuf
-function may be used to alter the buffering behavior of a stream.
-The
-.Fa mode
-parameter must be one of the following three macros:
-.Pp
-.Bl -tag -width _IOFBF -offset indent -compact
-.It Dv _IONBF
-unbuffered
-.It Dv _IOLBF
-line buffered
-.It Dv _IOFBF
-fully buffered
-.El
-.Pp
-The
-.Fa size
-parameter may be given as zero
-to obtain deferred optimal-size buffer allocation as usual.
-If it is not zero, then except for unbuffered files, the
-.Fa buf
-argument should point to a buffer at least
-.Fa size
-bytes long;
-this buffer will be used instead of the current buffer.
-(If the
-.Fa size
-argument
-is not zero but
-.Fa buf
-is
-.Dv NULL ,
-a buffer of the given size will be allocated immediately,
-and released on close.
-This is an extension to ANSI C;
-portable code should use a size of 0 with any
-.Dv NULL
-buffer.)
+.Bf -symbolic
+These interfaces are obsoleted by
+.Xr setvbuf 3 .
+.Ef
 .Pp
 The
-.Fn setvbuf
-function may be used at any time,
-but may have peculiar side effects
-(such as discarding input or flushing output)
-if the stream is
-.Dq active .
-Portable applications should call it only once on any given stream,
-and before any
-.Tn I/O
-is performed.
+.Fn setbuf ,
+.Fn setbuffer ,
+and
+.Fn setlinebuf
+functions are used to modify the buffering of a stream.
+These functions are provided for compatibility with legacy code.
+New code should use
+.Xr setvbuf 3
+instead.
 .Pp
-The other three calls are, in effect, simply aliases for calls to
-.Fn setvbuf .
 Except for the lack of a return value, the
 .Fn setbuf
 function is exactly equivalent to the call
@@ -147,6 +75,7 @@ The
 function is the same, except that the size of the buffer is up to the caller,
 rather than being determined by the default
 .Dv BUFSIZ .
+.Pp
 The
 .Fn setlinebuf
 function is exactly equivalent to the call:
@@ -154,49 +83,43 @@ function is exactly equivalent to the call:
 .Dl "setvbuf(stream, NULL, _IOLBF, 0);"
 .Sh RETURN VALUES
 The
-.Fn setvbuf
+.Fn setlinebuf
 function returns 0 on success, or
 .Dv EOF
 if the request cannot be honored
 (note that the stream is still functional in this case).
-.Pp
-The
-.Fn setlinebuf
-function returns what the equivalent
-.Fn setvbuf
-would have returned.
 .Sh SEE ALSO
 .Xr fclose 3 ,
 .Xr fopen 3 ,
 .Xr fread 3 ,
 .Xr malloc 3 ,
 .Xr printf 3 ,
-.Xr puts 3
+.Xr puts 3 ,
+.Xr setvbuf 3
 .Sh STANDARDS
 The
 .Fn setbuf
+function conforms to
+.St -isoC-99 .
+The
+.Fn setbuffer
 and
-.Fn setvbuf
-functions conform to
-.St -ansiC .
+.Fn setlinebuf
+functions are non-standard and should not be used if portability is required.
 .Sh HISTORY
-The function
+The
 .Fn setbuf
-first appeared in
+function first appeared in
 .At v7 .
-.Sh BUGS
 The
 .Fn setbuffer
-and
+function first appeared in
+.Bx 4.1c .
+The
 .Fn setlinebuf
-functions are not portable to versions of
-.Bx
-before
+function first appeared in
 .Bx 4.2 .
-On
-.Bx 4.2
-and
-.Bx 4.3
-systems,
+.Sh BUGS
+The
 .Fn setbuf
-always uses a suboptimal buffer size and should be avoided.
+function usually uses a suboptimal buffer size and should be avoided.
diff --git a/lib/libc/stdio/setvbuf.3 b/lib/libc/stdio/setvbuf.3
new file mode 100644
index 00000000000..ae3abb7c1ef
--- /dev/null
+++ b/lib/libc/stdio/setvbuf.3
@@ -0,0 +1,151 @@
+.\"	$OpenBSD: setvbuf.3,v 1.1 2014/11/25 17:01:49 millert Exp $
+.\"
+.\" Copyright (c) 1980, 1991, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" This code is derived from software contributed to Berkeley by
+.\" the American National Standards Committee X3, on Information
+.\" Processing Systems.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: November 25 2014 $
+.Dt SETVBUF 3
+.Os
+.Sh NAME
+.Nm setvbuf
+.Nd stream buffering operations
+.Sh SYNOPSIS
+.In stdio.h
+.Ft int
+.Fn setvbuf "FILE *stream" "char *buf" "int mode" "size_t size"
+.Sh DESCRIPTION
+The three types of stream 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 line buffered, characters are saved up until a newline
+.Pq Ql \en
+is output or input is read from any stream attached to a terminal device
+(typically
+.Em stdin ) .
+.Pp
+The
+.Xr fflush 3
+function may be used to force the block out early.
+.Pp
+Normally, all files are block buffered.
+When the first
+.Tn I/O
+operation occurs on a file,
+.Xr malloc 3
+is called,
+and an optimally sized buffer is obtained.
+If a stream refers to a terminal
+(as
+.Em stdout
+normally does), it is line buffered.
+.Pp
+The standard error stream
+.Em stderr
+is initially unbuffered.
+.Pp
+The
+.Fn setvbuf
+function may be used to alter the buffering behavior of a stream.
+The
+.Fa mode
+parameter must be one of the following three macros:
+.Pp
+.Bl -tag -width _IOFBF -offset indent -compact
+.It Dv _IONBF
+unbuffered
+.It Dv _IOLBF
+line buffered
+.It Dv _IOFBF
+fully buffered
+.El
+.Pp
+The
+.Fa size
+parameter may be given as zero
+to obtain deferred optimal-size buffer allocation as usual.
+If it is not zero, then except for unbuffered files, the
+.Fa buf
+argument should point to a buffer at least
+.Fa size
+bytes long;
+this buffer will be used instead of the current buffer.
+(If the
+.Fa size
+argument
+is not zero but
+.Fa buf
+is
+.Dv NULL ,
+a buffer of the given size will be allocated immediately,
+and released on close.
+This is an extension to ANSI C;
+portable code should use a size of 0 with any
+.Dv NULL
+buffer.)
+.Pp
+The
+.Fn setvbuf
+function may be used at any time,
+but may have peculiar side effects
+(such as discarding input or flushing output)
+if the stream is
+.Dq active .
+Portable applications should call it only once on any given stream,
+and before any
+.Tn I/O
+is performed.
+.Sh RETURN VALUES
+The
+.Fn setvbuf
+function returns 0 on success, or
+.Dv EOF
+if the request cannot be honored
+(note that the stream is still functional in this case).
+.Sh SEE ALSO
+.Xr fclose 3 ,
+.Xr fopen 3 ,
+.Xr fread 3 ,
+.Xr malloc 3 ,
+.Xr printf 3 ,
+.Xr puts 3 ,
+.Xr setbuf 3
+.Sh STANDARDS
+The
+.Fn setvbuf
+function conforms to
+.St -isoC-99 .
+.Sh HISTORY
+The
+.Fn setvbuf
+function first appeared in
+.Bx 4.4 .