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

Latest revision as of 11:54, 13 September 2023

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.

#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

setbuf	sets the buffer for a file stream (function) [edit]
setbuf [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

@@ 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,
-===Parameters===
+* If {{c|buffer}} is a null pointer, resizes the internal buffer to {{c|size}}.
-{{param list begin}}
+* 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 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}}
 }}
-{{param list item | size | size of the buffer}}
+{{par|size|size of the buffer}}
-{{param list end}}
+{{par end}}
 ===Return value===
@@ Line 22: / Line 24: @@
 ===Notes===
-This function may only be used after {{tt|stream}} has been associated with an open file, but before any other operation.
+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}}).
-{{tt|buffer}} may be null, in which case this call only resizes the internal buffer.
+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.
+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===
-{{dcl list begin}}
+{{dsc begin}}
-{{dcl list template | cpp/io/c/dcl list setbuf}}
+{{dsc inc|cpp/io/c/dsc setbuf}}
-{{dcl list template | cpp/io/basic_filebuf/dcl list setbuf | mem=std::basic_filebuf}}
+{{dsc inc|cpp/io/basic_filebuf/dsc setbuf}}
-{{dcl list end}}
+{{dsc see c|c/io/setvbuf}}
+{{dsc end}}
+{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

I/O manipulators
Print functions (C++23)
C-style I/O
Buffers
basic_streambuf
basic_filebuf
basic_stringbuf
basic_spanbuf (C++23)
strstreambuf (C++98/26*)
basic_syncbuf (C++20)
Streams
Abstractions
ios_base
basic_ios
basic_istream
basic_ostream
basic_iostream
File I/O
basic_ifstream
basic_ofstream
basic_fstream
String I/O
basic_istringstream
basic_ostringstream
basic_stringstream
Array I/O
basic_ispanstream (C++23)
basic_ospanstream (C++23)
basic_spanstream (C++23)
istrstream (C++98/26*)
ostrstream (C++98/26*)
strstream (C++98/26*)
Synchronized Output
basic_osyncstream (C++20)
Types
streamoff
streamsize
fpos
Error category interface
iostream_category (C++11)
io_errc (C++11)

cppreference.com

Namespaces

Variants

Views

Actions

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

Latest revision as of 11:54, 13 September 2023

Contents

[edit] Parameters

[edit] Return value

[edit] Notes

[edit] Example

[edit] See also

Navigation

Toolbox