Namespaces
Variants
Views
Actions

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

From cppreference.com
< cpp‎ | io‎ | c
m (fclose(fp) as added on the C side)
m (fmt)
 
(9 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
{{cpp/title | setvbuf}}
+
{{cpp/title|setvbuf}}
 
{{cpp/io/c/navbar}}
 
{{cpp/io/c/navbar}}
−
{{ddcl | header=cstdio |
+
{{ddcl|header=cstdio|
 
int setvbuf( std::FILE* stream, char* buffer, int mode, std::size_t size );
 
int setvbuf( std::FILE* stream, char* buffer, int mode, std::size_t size );
 
}}
 
}}
  
−
Changes the the buffering mode of the given file stream {{tt|stream}} as indicated by the argument {{tt|mode}}. In addition,
+
Changes the buffering mode of the given file stream {{c|stream}} as indicated by the argument {{c|mode}}. In addition,
  
−
* If {{tt|buffer}} is a null pointer, resizes of the internal buffer to {{tt|size}}.
+
* If {{c|buffer}} is a null pointer, resizes the internal buffer to {{c|size}}.
−
* If {{tt|buffer}} is not a null pointer, instructs the stream to use the user-provided buffer of size {{tt|size}} beginning at {{tt|buffer}}. The stream must be closed (with {{lc|fclose}}) before the [[c/language/lifetime|lifetime]] of the array pointed to by {{tt|buffer}} ends. The contents of the array after a successful call to {{tt|setvbuf}} are indeterminate and any attempt to use it is undefined behavior.
+
* 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.
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | stream | the file stream to set the buffer to or null pointer to change size and mode only}}
+
{{par|stream|the file stream to set the buffer to}}
−
{{par | buffer | pointer to a buffer for the stream to use}}
+
{{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:
+
{{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}}
 
}}
 
}}
−
{{par | size | size of the buffer}}
+
{{par|size|size of the buffer}}
 
{{par end}}
 
{{par end}}
  
Line 25: Line 24:
  
 
===Notes===
 
===Notes===
−
This function may only be used after {{tt|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}}).
+
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}}).
  
−
Not all {{tt|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.
+
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.
 
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:
+
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=
 
{{source|1=
−
int main() {
+
int main()
 +
{
 
     char buf[BUFSIZ];
 
     char buf[BUFSIZ];
 
     std::setbuf(stdin, buf);
 
     std::setbuf(stdin, buf);
Line 39: Line 39:
 
}}
 
}}
  
−
The default buffer size {{lc|BUFSIZ}} is expected to be the most efficient buffer size for file I/O on the implementation, but POSIX [http://pubs.opengroup.org/onlinepubs/9699919799/functions/fstat.html fstat] often provides a better estimate.
+
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===
−
{{example|one use case for changing buffer size is when a better size is known
+
{{example
 +
|One use case for changing buffer size is when a better size is known.
 
|code=
 
|code=
−
#include <iostream>
 
 
#include <cstdio>
 
#include <cstdio>
−
#include <stdlib.h>
+
#include <cstdlib>
 +
#include <iostream>
 
#include <sys/stat.h>
 
#include <sys/stat.h>
  
 
int main()
 
int main()
 
{
 
{
−
     std::FILE* fp = std::fopen("test.txt", "r");
+
     std::FILE* fp = std::fopen("/tmp/test.txt", "w+");
−
     if(!fp) {
+
     if (!fp)
−
      std::perror("fopen"); return 1;
+
    {
 +
        std::perror("fopen");
 +
        return EXIT_FAILURE;
 
     }
 
     }
  
 
     struct stat stats;
 
     struct stat stats;
−
     if(fstat(fileno(fp), &stats) == -1) { // POSIX only
+
     if (fstat(fileno(fp), &stats) == -1) // POSIX only
−
         std::perror("fstat"); return 1;
+
    {
 +
         std::perror("fstat");
 +
        return EXIT_FAILURE;
 
     }
 
     }
  
 
     std::cout << "BUFSIZ is " << BUFSIZ << ", but optimal block size is "
 
     std::cout << "BUFSIZ is " << BUFSIZ << ", but optimal block size is "
 
               << stats.st_blksize << '\n';
 
               << stats.st_blksize << '\n';
−
     if(std::setvbuf(fp, NULL, _IOFBF, stats.st_blksize) != 0) {
+
     if (std::setvbuf(fp, nullptr, _IOFBF, stats.st_blksize) != 0)
−
      perror("setvbuf failed"); // POSIX version sets errno
+
    {
−
      return 1;
+
        std::perror("setvbuf failed"); // POSIX version sets errno
 +
        return EXIT_FAILURE;
 
     }
 
     }
  
−
     int ch;
+
     // Read entire file: use truss/strace to observe the read(2) syscalls used
−
     while((ch=std::fgetc(fp)) != EOF); // read entire file: use truss/strace to
+
     for (int ch; (ch = std::fgetc(fp)) != EOF;)
−
                                      // observe the read(2) syscalls used
+
     {}
−
     fclose(fp);
+
 
 +
    std::fclose(fp);
 +
    return EXIT_SUCCESS;
 
}
 
}
 
|p=true
 
|p=true
Line 80: Line 88:
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/io/c/dsc setbuf}}
+
{{dsc inc|cpp/io/c/dsc setbuf}}
−
{{dsc inc | cpp/io/basic_filebuf/dsc setbuf}}
+
{{dsc inc|cpp/io/basic_filebuf/dsc setbuf}}
−
{{dsc see c | c/io/setvbuf}}
+
{{dsc see c|c/io/setvbuf}}
 
{{dsc end}}
 
{{dsc end}}
  
−
[[de:cpp/io/c/setvbuf]]
+
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
−
[[es:cpp/io/c/setvbuf]]
+
−
[[fr:cpp/io/c/setvbuf]]
+
−
[[it:cpp/io/c/setvbuf]]
+
−
[[ja:cpp/io/c/setvbuf]]
+
−
[[pt:cpp/io/c/setvbuf]]
+
−
[[ru:cpp/io/c/setvbuf]]
+
−
[[zh:cpp/io/c/setvbuf]]
+

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"