share/man/man3c/setbuf.3c

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SETBUF 3C "Aug 14, 2002"
   7 .SH NAME
   8 setbuf, setvbuf \- assign buffering to a stream
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <stdio.h>
  13
  14 \fBvoid\fR \fBsetbuf\fR(\fBFILE *\fR\fIstream\fR, \fBchar *\fR\fIbuf\fR);
  15 .fi
  16
  17 .LP
  18 .nf
  19 \fBint\fR \fBsetvbuf\fR(\fBFILE *\fR\fIstream\fR, \fBchar *\fR\fIbuf\fR, \fBint\fR \fItype\fR, \fBsize_t\fR \fIsize\fR);
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 The \fBsetbuf()\fR function may be used after the stream pointed to by
  26 \fIstream\fR (see \fBIntro\fR(3)) is opened but before it is read or written.
  27 It causes the array pointed to by \fIbuf\fR to be used instead of an
  28 automatically allocated buffer. If \fIbuf\fR is the null pointer, input/output
  29 will be completely unbuffered.  The constant  \fBBUFSIZ\fR, defined in the
  30 <\fBstdio.h\fR> header, indicates the size of the array pointed to by
  31 \fIbuf\fR.
  32 .sp
  33 .LP
  34 The \fBsetvbuf()\fR function may be used after a stream is opened  but before
  35 it is read or written.  The \fItype\fR argument determines how  \fIstream\fR
  36 will be buffered. Legal values for  \fItype\fR (defined in <\fBstdio.h\fR>)
  37 are:
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fB_IOFBF\fR\fR
  42 .ad
  43 .RS 10n
  44 Input/output to be fully buffered.
  45 .RE
  46
  47 .sp
  48 .ne 2
  49 .na
  50 \fB\fB_IOLBF\fR\fR
  51 .ad
  52 .RS 10n
  53 Output to be line buffered;  the buffer will be flushed when a \fBNEWLINE\fR is
  54 written, the buffer is full, or input is requested.
  55 .RE
  56
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fB_IONBF\fR\fR
  61 .ad
  62 .RS 10n
  63 Input/output to be completely unbuffered.
  64 .RE
  65
  66 .sp
  67 .LP
  68 If \fIbuf\fR is not the null pointer, the array it points to will be used for
  69 buffering, instead of an automatically allocated buffer.  The \fIsize\fR
  70 argument specifies the size of the buffer to be used. If input/output is
  71 unbuffered,  \fIbuf\fR and  \fIsize\fR are ignored.
  72 .sp
  73 .LP
  74 For a further discussion of buffering, see \fBstdio\fR(3C).
  75 .SH RETURN VALUES
  76 .sp
  77 .LP
  78 If an illegal value for  \fItype\fR is provided, \fBsetvbuf()\fR returns a
  79 non-zero value.   Otherwise, it returns \fB0\fR.
  80 .SH USAGE
  81 .sp
  82 .LP
  83 A common source of error is allocating buffer space as an "automatic" variable
  84 in a code block, and then failing to close the stream in the same block.
  85 .sp
  86 .LP
  87 When using \fBsetbuf()\fR, \fIbuf\fR should always be sized using \fBBUFSIZ\fR.
  88 If the array pointed to by \fIbuf\fR is larger than \fBBUFSIZ\fR, a portion of
  89 \fIbuf\fR will not be used.  If \fIbuf\fR is smaller than \fBBUFSIZ\fR, other
  90 memory may be unexpectedly overwritten.
  91 .sp
  92 .LP
  93 Parts of \fBbuf\fR will be used for internal bookkeeping of the stream and,
  94 therefore, \fBbuf\fR will contain less than \fIsize\fR bytes when full. It is
  95 recommended that  \fBstdio\fR(3C) be used to handle buffer allocation when
  96 using \fBsetvbuf()\fR.
  97 .SH ATTRIBUTES
  98 .sp
  99 .LP
 100 See \fBattributes\fR(5) for descriptions of the following attributes:
 101 .sp
 102
 103 .sp
 104 .TS
 105 box;
 106 c | c
 107 l | l .
 108 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 109 _
 110 Interface Stability     Standard
 111 _
 112 MT-Level        MT-Safe
 113 .TE
 114
 115 .SH SEE ALSO
 116 .sp
 117 .LP
 118 \fBfopen\fR(3C), \fBgetc\fR(3C), \fBmalloc\fR(3C), \fBputc\fR(3C),
 119 \fBstdio\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)