setbuf, setvbuf, setbuffer, or setlinebuf Subroutine

Edit online

Purpose

Assigns buffering to a stream.

Library

Standard C Library (libc.a)

Syntax

#include <stdio.h>
void setbuf ( Stream,  Buffer)
FILE *Stream;
char *Buffer;
int setvbuf (Stream, Buffer, Mode, Size)
FILE *Stream;
char *Buffer;
int  Mode;
size_t  Size;
void setbuffer (Stream, Buffer, Size)
FILE *Stream;
char *Buffer;
size_t Size;
void setlinebuf (Stream)
FILE *Stream;

Description

The setbuf subroutine causes the character array pointed to by the Buffer parameter to be used instead of an automatically allocated buffer. Use the setbuf subroutine after a stream has been opened, but before it is read or written.

If the Buffer parameter is a null character pointer, input/output is completely unbuffered.

A constant, BUFSIZ, defined in the stdio.h file, tells how large an array is needed:

char buf[BUFSIZ];

For the setvbuf subroutine, the Mode parameter determines how the Stream parameter is buffered:

Item Description
_IOFBF Causes input/output to be fully buffered.
_IOLBF Causes output to be line-buffered. The buffer is flushed when a new line is written, the buffer is full, or input is requested.
_IONBF Causes input/output to be completely unbuffered.

If the Buffer parameter is not a null character pointer, the array it points to is used for buffering. The Size parameter specifies the size of the array which is used as a buffer, but all of the Size parameter's bytes are not necessarily used for the buffer area. Some bytes from the buffer are used for the internal buffer management. If the specified value of the Size parameter is less than the required value for internal buffer management, the setvbuf and the setbuffer subroutines ignore the specified buffer and performs an internal allocation of buffer.

The BUFSIZ constant in the stdio.h file is one buffer size. If the input or output is unbuffered, the setbuf subroutine ignores the Buffer and Size parameters. The setbuffer subroutine which is an alternate form of the setbuf subroutine, is used after the Stream is opened, but before it is read or written. The size of the Buffer character array is determined by the Size parameter. The Buffer character array is used instead of an automatically allocated buffer. If the Buffer parameter is a null character pointer, the input or output is completely unbuffered.

The setbuffer subroutine is not needed under normal circumstances because the default file I/O buffer size is optimal.

The setlinebuf subroutine is used to change the stdout or stderr file from block buffered or unbuffered to line-buffered. Unlike the setbuf and setbuffer subroutines, the setlinebuf subroutine can be used any time Stream is active.

A buffer is normally obtained from the malloc subroutine at the time of the first getc subroutine or putc subroutine on the file, except that the standard error stream, stderr, is normally not buffered.

Output streams directed to terminals are always either line-buffered or unbuffered.

Note: A common source of error is allocating buffer space as an automatic variable in a code block, and then failing to close the stream in the same block.

The setbuffer and setlinebuf subroutines are included for compatibility with Berkeley System Distribution (BSD).

Parameters

Item Description
Stream Specifies the input/output stream.
Buffer Points to a character array.
Mode Determines how the Stream parameter is buffered.
Size Specifies the size of the buffer to be used.

Example

#include <stdio.h>

#define  SIZE  1024

int main(void)
{
	FILE *fp1;
	char buf[SIZE];
	memset( buf, '\0', sizeof( buf ));
	fp1 = fopen("file1", "r");

	/* Error Handling for fopen */

	if (setvbuf(fp1, buf, _IOFBF, SIZE) != 0)
			 printf("Not proper data provided to setvbuf\n");
	if (fclose(fp1))
			perror("fclose error");
}

Return Values

Upon successful completion, setvbuf returns a value of 0. Otherwise it returns a nonzero value if a value that is not valid is given for type, or if the request cannot be honored.