Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
std::setvbuf(3)		      C++ Standard Libary	       std::setvbuf(3)

NAME
       std::setvbuf - std::setvbuf

Synopsis
	  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	 indi-
       cated 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.

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
		   buffering mode to use. It can be one	of the following  val-
       ues:

	  mode	 - _IOFBF full buffering
		   _IOLBF line buffering
		   _IONBF no buffering
	  size	 - size	of the buffer

Return value
	  0 on success or nonzero on failure.

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 ac-
       tual 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	termi-
       nal 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.

Example
	  one use case for changing buffer size	is when	a better size is known

       // Run this code

	#include <iostream>
	#include <cstdio>
	#include <cstdlib>
	#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

See also
	  setbuf    sets the buffer for	a file stream
		    (function)
	  setbuf     provides  user-supplied  buffer or	turns this filebuf un-
       buffered
	  [virtual] (virtual protected	member	function  of  std::basic_file-
       buf<CharT,Traits>)

http://cppreference.com		  2022.07.31		       std::setvbuf(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::setvbuf&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help