Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/io/c/setvbuf"

From cppreference.com
< cpp‎ | io‎ | c
m (1 revision: import content)
m (fmt)
 
(29 intermediate revisions by 10 users not shown)
Line 1: Line 1:
−
{{cpp/title | setvbuf}}
+
{{cpp/title|setvbuf}}
−
{{cpp/io/c/sidebar}}
+
{{cpp/io/c/navbar}}
−
{{ddcl | header=cstdio |
+
{{ddcl|header=cstdio|
−
int setvbuf( FILE *stream, char *buffer, int mode, size_t size );
+
int setvbuf( std::FILE* stream, char* buffer, int mode, std::size_t size );
 
}}
 
}}
  
−
Sets the internal buffer of the given file stream {{tt|stream}}.  
+
Changes the buffering mode of the given file stream {{c|stream}} as indicated by the argument {{c|mode}}. In addition,
  
−
<!-- ======== -->
+
* If {{c|buffer}} is a null pointer, resizes the internal buffer to {{c|size}}.
−
{{params}}
+
* If {{c|buffer}} is not a null pointer, instructs the stream to use the user-provided buffer of size {{c|size}} beginning at {{c|buffer}}. The stream must be closed (with {{lc|std::fclose}}) before the [[cpp/language/lifetime|lifetime]] of the array pointed to by {{c|buffer}} ends. The contents of the array after a successful call to {{lc|std::setvbuf}} are indeterminate and any attempt to use it is undefined behavior.
−
{{param list begin}}
+
−
{{param list item | stream | the file stream to set the buffer to}}
+
−
{{param list item | buffer | pointer to a buffer for the stream to use}}
+
−
{{param list item | mode |2= buffering mode to use. It can be one of the following values:
+
  
 +
===Parameters===
 +
{{par begin}}
 +
{{par|stream|the file stream to set the buffer to}}
 +
{{par|buffer|pointer to a buffer for the stream to use or null pointer to change size and mode only}}
 +
{{par|mode|2=buffering mode to use. It can be one of the following values:
 
{{cpp/io/c/buffering modes}}
 
{{cpp/io/c/buffering modes}}
 
}}
 
}}
−
{{param list item | size | size of the buffer}}
+
{{par|size|size of the buffer}}
−
{{param list end}}
+
{{par end}}
  
−
<!-- ======== -->
+
===Return value===
−
{{returns}}
+
{{c|0}} on success or nonzero on failure.
−
{{return none}}
+
  
−
<!-- ======== -->
+
===Notes===
−
{{see also}}
+
This function may only be used after {{c|stream}} has been associated with an open file, but before any other operation (other than a failed call to {{lc|std::setbuf}}/{{tt|std::setvbuf}}).
−
{{dcl list begin}}
+
 
−
{{dcl list template | cpp/io/c/dcl list setbuf}}
+
Not all {{c|size}} bytes will necessarily be used for buffering: the actual buffer size is usually rounded down to a multiple of 2, a multiple of page size, etc.
−
{{dcl list end}}
+
 
 +
On many implementations, line buffering is only available for terminal input streams.
 +
 
 +
A common error is setting the buffer of {{tt|stdin}} or {{tt|stdout}} to an array whose lifetime ends before the program terminates:
 +
{{source|1=
 +
int main()
 +
{
 +
    char buf[BUFSIZ];
 +
    std::setbuf(stdin, buf);
 +
} // lifetime of buf ends, undefined behavior
 +
}}
 +
 
 +
The default buffer size {{lc|BUFSIZ}} is expected to be the most efficient buffer size for file I/O on the implementation, but POSIX [https://pubs.opengroup.org/onlinepubs/9699919799/functions/fstat.html {{tt|fstat}}] often provides a better estimate.
 +
 
 +
===Example===
 +
{{example
 +
|One use case for changing buffer size is when a better size is known.
 +
|code=
 +
#include <cstdio>
 +
#include <cstdlib>
 +
#include <iostream>
 +
#include <sys/stat.h>
 +
 
 +
int main()
 +
{
 +
    std::FILE* fp = std::fopen("/tmp/test.txt", "w+");
 +
    if (!fp)
 +
    {
 +
        std::perror("fopen");
 +
        return EXIT_FAILURE;
 +
    }
 +
 
 +
    struct stat stats;
 +
    if (fstat(fileno(fp), &stats) == -1) // POSIX only
 +
    {
 +
        std::perror("fstat");
 +
        return EXIT_FAILURE;
 +
    }
 +
 
 +
    std::cout << "BUFSIZ is " << BUFSIZ << ", but optimal block size is "
 +
              << stats.st_blksize << '\n';
 +
    if (std::setvbuf(fp, nullptr, _IOFBF, stats.st_blksize) != 0)
 +
    {
 +
        std::perror("setvbuf failed"); // POSIX version sets errno
 +
        return EXIT_FAILURE;
 +
    }
 +
 
 +
    // Read entire file: use truss/strace to observe the read(2) syscalls used
 +
    for (int ch; (ch = std::fgetc(fp)) != EOF;)
 +
    {}
 +
 
 +
    std::fclose(fp);
 +
    return EXIT_SUCCESS;
 +
}
 +
|p=true
 +
|output=
 +
BUFSIZ is 8192, but optimal block size is 65536
 +
}}
 +
 
 +
===See also===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/io/c/dsc setbuf}}
 +
{{dsc inc|cpp/io/basic_filebuf/dsc setbuf}}
 +
{{dsc see c|c/io/setvbuf}}
 +
{{dsc end}}
 +
 
 +
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Latest revision as of 11:54, 13 September 2023

 
C++
 
Input/output library
 
C-style I/O
Types and objects
Functions
File access
setvbuf

Direct input/output
Unformatted input/output
Formatted input
(C++11)(C++11)(C++11)    
(C++11)(C++11)(C++11)    
 
Defined in header <cstdio>
int setvbuf( std::FILE* stream, char* buffer, int mode, std::size_t size );

Changes the buffering mode of the given file stream stream as indicated by the argument mode. In addition,

  • If buffer is a null pointer, resizes the internal buffer to size.
  • If buffer is not a null pointer, instructs the stream to use the user-provided buffer of size size beginning at buffer. The stream must be closed (with std::fclose) before the lifetime of the array pointed to by buffer ends. The contents of the array after a successful call to std::setvbuf are indeterminate and any attempt to use it is undefined behavior.

Contents

[edit] Parameters

stream - the file stream to set the buffer to
buffer - pointer to a buffer for the stream to use or null pointer to change size and mode only
mode - buffering mode to use. It can be one of the following values:
_IOFBF full buffering
_IOLBF line buffering
_IONBF no buffering
size - size of the buffer

[edit] Return value

​0​ on success or nonzero on failure.

[edit] Notes

This function may only be used after stream has been associated with an open file, but before any other operation (other than a failed call to std::setbuf/std::setvbuf).

Not all size bytes will necessarily be used for buffering: the actual buffer size is usually rounded down to a multiple of 2, a multiple of page size, etc.

On many implementations, line buffering is only available for terminal input streams.

A common error is setting the buffer of stdin or stdout to an array whose lifetime ends before the program terminates: 

int main()
{
    char buf[BUFSIZ];
    std::setbuf(stdin, buf);
} // lifetime of buf ends, undefined behavior

The default buffer size BUFSIZ is expected to be the most efficient buffer size for file I/O on the implementation, but POSIX fstat often provides a better estimate.

[edit] Example

One use case for changing buffer size is when a better size is known.

Run this code
#include <cstdio>
#include <cstdlib>
#include <iostream>
#include <sys/stat.h>
 
int main()
{
    std::FILE* fp = std::fopen("/tmp/test.txt", "w+");
    if (!fp)
    {
        std::perror("fopen");
        return EXIT_FAILURE;
    }
 
    struct stat stats;
    if (fstat(fileno(fp), &stats) == -1) // POSIX only
    {
        std::perror("fstat");
        return EXIT_FAILURE;
    }
 
    std::cout << "BUFSIZ is " << BUFSIZ << ", but optimal block size is "
              << stats.st_blksize << '\n';
    if (std::setvbuf(fp, nullptr, _IOFBF, stats.st_blksize) != 0)
    {
        std::perror("setvbuf failed"); // POSIX version sets errno
        return EXIT_FAILURE;
    }
 
    // Read entire file: use truss/strace to observe the read(2) syscalls used
    for (int ch; (ch = std::fgetc(fp)) != EOF;)
    {}
 
    std::fclose(fp);
    return EXIT_SUCCESS;
}

Possible output: 

BUFSIZ is 8192, but optimal block size is 65536

[edit] See also

 sets the buffer for a file stream
(function) [edit]
[virtual]
 provides user-supplied buffer or turns this filebuf unbuffered
(virtual protected member function of std::basic_filebuf<CharT,Traits>) [edit]
C documentation for setvbuf
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/io/c/setvbuf&oldid=158998"