Difference between revisions of "cpp/io/basic filebuf"

Latest revision as of 14:55, 25 October 2024

Defined in header `<fstream>`
template< class CharT, class Traits = std::char_traits<CharT> > class basic_filebuf : public std::basic_streambuf<CharT, Traits>

std::basic_filebuf is a std::basic_streambuf whose associated character sequence is a file. Both the input sequence and the output sequence are associated with the same file, and a joint file position is maintained for both operations. The restrictions on reading and writing a sequence with std::basic_filebuf are the same as std::FILEs.

The functions underflow() and overflow() / sync() perform the actual I/O between the file and the get and put areas of the buffer. When CharT is not char, most implementations store multibyte characters in the file and a std::codecvt facet is used to perform wide/multibyte character conversion.

Several typedefs for common character types are provided:

Defined in header `<fstream>`
Type	Definition
`std::filebuf`	std::basic_filebuf<char>
`std::wfilebuf`	std::basic_filebuf<wchar_t>

[edit] Member types

Type	Definition
`char_type`	`CharT`[edit]
`traits_type`	`Traits`; the program is ill-formed if `Traits::char_type` is not `CharT`.[edit]
`int_type`	`Traits::int_type`[edit]
`pos_type`	`Traits::pos_type` which is required to be std::fpos<Traits::state_type>
`off_type`	`Traits::off_type`[edit]
`native_handle_type`(C++26)	implementation-defined type that is TriviallyCopyable and `semiregular`[edit]

[edit] Member functions

Public member functions
(constructor)	constructs a `basic_filebuf` object (public member function) [edit]
operator= (C++11)	assigns a `basic_filebuf` object (public member function) [edit]
swap (C++11)	swaps two `basic_filebuf` objects (public member function) [edit]
native_handle (C++26)	returns the underlying implementation-defined handle (public member function) [edit]
(destructor) [virtual]	destructs a `basic_filebuf` object and closes the file if it is open (virtual public member function) [edit]
is_open	checks if the associated file is open (public member function) [edit]
open	opens a file and configures it as the associated character sequence (public member function) [edit]
close	flushes the put area buffer and closes the associated file (public member function) [edit]
Protected member functions
showmanyc [virtual]	optionally provides the number of characters available for input from the file (virtual protected member function) [edit]
underflow [virtual]	reads from the associated file (virtual protected member function) [edit]
uflow [virtual]	reads from the associated file and advances the next pointer in the get area (virtual protected member function) [edit]
pbackfail [virtual]	backs out the input sequence to unget a character, not affecting the associated file (virtual protected member function) [edit]
overflow [virtual]	writes characters to the associated file from the put area (virtual protected member function) [edit]
setbuf [virtual]	provides user-supplied buffer or turns this filebuf unbuffered (virtual protected member function) [edit]
seekoff [virtual]	repositions the file position, using relative addressing (virtual protected member function) [edit]
seekpos [virtual]	repositions the file position, using absolute addressing (virtual protected member function) [edit]
sync [virtual]	writes characters to the associated file from the put area (virtual protected member function) [edit]
imbue [virtual]	changes the associated locale (virtual protected member function) [edit]

[edit] Non-member functions

std::swap(std::basic_filebuf)

(C++11)

specializes the std::swap algorithm
(function template) [edit]

Inherited from std::basic_streambuf

Member types

Member type	Definition
`char_type`	`CharT`[edit]
`traits_type`	`Traits`; the program is ill-formed if `Traits::char_type` is not `CharT`.[edit]
`int_type`	`Traits::int_type`[edit]
`pos_type`	`Traits::pos_type`[edit]
`off_type`	`Traits::off_type`[edit]

Member functions

(destructor) [virtual]	destructs the `basic_streambuf` object (virtual public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
Locales
pubimbue	invokes imbue() (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
getloc	obtains a copy of the associated locale (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
Positioning
pubsetbuf	invokes setbuf() (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
pubseekoff	invokes seekoff() (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
pubseekpos	invokes seekpos() (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
pubsync	invokes sync() (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
Get area
in_avail	obtains the number of characters immediately available in the get area (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
snextc	advances the input sequence, then reads one character without advancing again (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
sbumpcstossc (removed in C++17)	reads one character from the input sequence and advances the sequence (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
sgetc	reads one character from the input sequence without advancing the sequence (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
sgetn	invokes xsgetn() (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
Put area
sputc	writes one character to the put area and advances the next pointer (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
sputn	invokes xsputn() (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
Putback
sputbackc	puts one character back in the input sequence (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]
sungetc	moves the next pointer in the input sequence back by one (public member function of `std::basic_streambuf<CharT,Traits>`) [edit]

Protected member functions

(constructor)	constructs a `basic_streambuf` object (protected member function) [edit]
operator= (C++11)	replaces a `basic_streambuf` object (protected member function) [edit]
swap (C++11)	swaps two `basic_streambuf` objects (protected member function) [edit]
Locales
imbue [virtual]	changes the associated locale (virtual protected member function of `std::basic_streambuf<CharT,Traits>`) [edit]
Positioning
setbuf [virtual]	replaces the buffer with user-defined array, if permitted (virtual protected member function of `std::basic_streambuf<CharT,Traits>`) [edit]
seekoff [virtual]	repositions the next pointer in the input sequence, output sequence, or both, using relative addressing (virtual protected member function of `std::basic_streambuf<CharT,Traits>`) [edit]
seekpos [virtual]	repositions the next pointer in the input sequence, output sequence, or both using absolute addressing (virtual protected member function of `std::basic_streambuf<CharT,Traits>`) [edit]
sync [virtual]	synchronizes the buffers with the associated character sequence (virtual protected member function of `std::basic_streambuf<CharT,Traits>`) [edit]
Get area
showmanyc [virtual]	obtains the number of characters available for input in the associated input sequence, if known (virtual protected member function of `std::basic_streambuf<CharT,Traits>`) [edit]
underflow [virtual]	reads characters from the associated input sequence to the get area (virtual protected member function of `std::basic_streambuf<CharT,Traits>`) [edit]
uflow [virtual]	reads characters from the associated input sequence to the get area and advances the next pointer (virtual protected member function of `std::basic_streambuf<CharT,Traits>`) [edit]
xsgetn [virtual]	reads multiple characters from the input sequence (virtual protected member function of `std::basic_streambuf<CharT,Traits>`) [edit]
ebackgptregptr	returns a pointer to the beginning, current character and the end of the get area (protected member function) [edit]
gbump	advances the next pointer in the input sequence (protected member function) [edit]
setg	repositions the beginning, next, and end pointers of the input sequence (protected member function) [edit]
Put area
xsputn [virtual]	writes multiple characters to the output sequence (virtual protected member function of `std::basic_streambuf<CharT,Traits>`) [edit]
overflow [virtual]	writes characters to the associated output sequence from the put area (virtual protected member function of `std::basic_streambuf<CharT,Traits>`) [edit]
pbasepptrepptr	returns a pointer to the beginning, current character and the end of the put area (protected member function) [edit]
pbump	advances the next pointer of the output sequence (protected member function) [edit]
setp	repositions the beginning, next, and end pointers of the output sequence (protected member function) [edit]
Putback
pbackfail [virtual]	puts a character back into the input sequence, possibly modifying the input sequence (virtual protected member function of `std::basic_streambuf<CharT,Traits>`) [edit]

[edit] Notes

Feature-test macro	Value	Std	Feature
`__cpp_lib_fstream_native_handle`	202306L	(C++26)	native handles support

[edit] See also

FILE	object type, capable of holding all information needed to control a C I/O stream (typedef) [edit]

@@ Line 1: / Line 1: @@
 {{cpp/title|basic_filebuf}}
-{{cpp/io/basic_filebuf/sidebar}}
+{{cpp/io/basic_filebuf/navbar}}
-{{ddcl | header=fstream | 1=
+{{ddcl|header=fstream|1=
 template<
-     class charT,
+     class CharT,
-     class Traits = std::char_traits<CharT>,
+     class Traits = std::char_traits<CharT>
-    class Allocator = std::allocator<CharT>
 > class basic_filebuf : public std::basic_streambuf<CharT, Traits>
 }}
-{{tt|std::basic_filebuf}} is a {{cpp|std::basic_streambuf}} whose associated character sequence is a file. Both the input sequence and the output sequence are associated with the same file, and a joint file position is maintained for both operations.
+{{tt|std::basic_filebuf}} is a {{lc|std::basic_streambuf}} whose associated character sequence is a file. Both the input sequence and the output sequence are associated with the same file, and a joint file position is maintained for both operations. The restrictions on reading and writing a sequence with {{tt|std::basic_filebuf}} are the same as {{lc|std::FILE}}s.
-The functions underflow() and overflow()/sync() perform the actual I/O between the file and the get and put areas of the buffer. When {{tt|CharT}} is not {{cpp|char}}, most implementations store multibyte characters in the file and a {{cpp|std::codecvt}} facet is used to perform wide/multibyte character conversion.
+The functions {{lc|underflow()}} and {{lc|overflow()}} / {{lc|sync()}} perform the actual I/O between the file and the get and put areas of the buffer. When {{tt|CharT}} is not {{c/core|char}}, most implementations store multibyte characters in the file and a {{lc|std::codecvt}} facet is used to perform wide/multibyte character conversion.
-Two specializations for common character types are also defined:
+{{cpp/basic char typedefs|filebuf|fstream}}
-{{tdcl list begin}}
-{{tdcl list header | streambuf}}
-{{tdcl list hitem | Type | Definition}}
-{{tdcl list item | {{tt|filebuf}} | {{cpp|basic_filebuf<char>}}}}
-{{tdcl list item | {{tt|wfilebuf}} | {{cpp|basic_filebuf<wchar_t>}}}}
-{{tdcl list end}}
 ===Member types===
-{{tdcl list begin}}
+{{dsc begin}}
-{{tdcl list hitem | Member type | Definition}}
+{{dsc hitem|Type|Definition}}
-{{tdcl list template | cpp/io/tdcl list char_type}}
+{{dsc inc|cpp/io/dsc char_type}}
-{{tdcl list template | cpp/io/tdcl list traits_type}}
+{{dsc inc|cpp/io/dsc traits_type}}
-{{tdcl list template | cpp/io/tdcl list int_type}}
+{{dsc inc|cpp/io/dsc int_type}}
-{{tdcl list item | {{tt|pos_type}} | {{cpp|Traits::pos_type}} which is required to be {{cpp|std::fpos<Traits::state_type>}}}}
+{{dsc|{{tt|pos_type}}|{{tt|Traits::pos_type}} which is required to be {{c/core|std::fpos<Traits::state_type>}}}}
-{{tdcl list template | cpp/io/tdcl list off_type}}
+{{dsc inc|cpp/io/dsc off_type}}
-{{tdcl list end}}
+{{dsc inc|cpp/io/dsc native_handle_type}}
+{{dsc end}}
 ===Member functions===
-{{dcl list begin}}
+{{dsc begin}}
-{{dcl list h1 | Public member functions}}
+{{dsc h1|Public member functions}}
-{{dcl list mem ctor | cpp/io/basic_filebuf/basic_filebuf | constructs a basic_filebuf object}}
+{{dsc inc|cpp/io/basic_filebuf/dsc basic_filebuf}}
-{{dcl list mem fun | cpp/io/basic_filebuf/operator{{=}} | assigns a basic_filebuf object | notes={{mark c++11}}}}
+{{dsc inc|cpp/io/basic_filebuf/dsc operator{{=}}}}
-{{dcl list mem fun | cpp/io/basic_filebuf/swap | swaps two basic_filebuf objects | notes={{mark c++11}}}}
+{{dsc inc|cpp/io/basic_filebuf/dsc swap}}
-{{dcl list mem vdtor | cpp/io/basic_filebuf/~basic_filebuf | destructs a basic_filebuf object and closes the file if it is open}}
+{{dsc inc|cpp/io/basic_filebuf/dsc native_handle}}
-{{dcl list mem fun | cpp/io/basic_filebuf/is_open | checks if the associated file is open}}
+{{dsc inc|cpp/io/basic_filebuf/dsc ~basic_filebuf}}
-{{dcl list mem fun | cpp/io/basic_filebuf/open | opens a file and configures it as the associated character sequence}}
+{{dsc inc|cpp/io/basic_filebuf/dsc is_open}}
-{{dcl list mem fun | cpp/io/basic_filebuf/close | flushes the put area buffer and closes the associated file}}
+{{dsc inc|cpp/io/basic_filebuf/dsc open}}
-{{dcl list h1 | Protected member functions}}
+{{dsc inc|cpp/io/basic_filebuf/dsc close}}
-{{dcl list prot mem vfun | cpp/io/basic_filebuf/showmanyc | optionally provides the number of characters available for input from the file}}
+{{dsc h1|Protected member functions}}
-{{dcl list prot mem vfun | cpp/io/basic_filebuf/underflow | reads from the associated file}}
+{{dsc inc|cpp/io/basic_filebuf/dsc showmanyc}}
-{{dcl list prot mem vfun | cpp/io/basic_filebuf/uflow | reads from the associated file and advances the next pointer in the get area}}
+{{dsc inc|cpp/io/basic_filebuf/dsc underflow}}
-{{dcl list prot mem vfun | cpp/io/basic_filebuf/pbackfail | puts back the character in the get area, not affecting the associated file}}
+{{dsc inc|cpp/io/basic_filebuf/dsc uflow}}
-{{dcl list prot mem vfun | cpp/io/basic_filebuf/overflow | writes characters to the associated file from the put area}}
+{{dsc inc|cpp/io/basic_filebuf/dsc pbackfail}}
-{{dcl list prot mem vfun | cpp/io/basic_filebuf/setbuf | provides user-supplied buffer or turns this filebuf unbuffered}}
+{{dsc inc|cpp/io/basic_filebuf/dsc overflow}}
-{{dcl list prot mem vfun | cpp/io/basic_filebuf/seekoff | repositions the file position, using relative addressing}}
+{{dsc inc|cpp/io/basic_filebuf/dsc setbuf}}
-{{dcl list prot mem vfun | cpp/io/basic_filebuf/seekpos | repositions the file position, using absolute addressing}}
+{{dsc inc|cpp/io/basic_filebuf/dsc seekoff}}
-{{dcl list prot mem vfun | cpp/io/basic_filebuf/sync | writes characters to the associated file from the put area}}
+{{dsc inc|cpp/io/basic_filebuf/dsc seekpos}}
-{{dcl list prot mem vfun | cpp/io/basic_filebuf/imbue | changes the associated locale }}
+{{dsc inc|cpp/io/basic_filebuf/dsc sync}}
-{{dcl list end}}
+{{dsc inc|cpp/io/basic_filebuf/dsc imbue}}
+{{dsc end}}
 ===Non-member functions===
-{{dcl list begin}}
+{{dsc begin}}
-{{dcl list tfun | cpp/io/basic_filebuf/swap2 | title=std::swap{{dcl small|(std::basic_filebuf)}} | specializes the {{cpp|std::swap}} algorithm| notes={{mark c++11}}}}
+{{dsc inc|cpp/io/basic_filebuf/dsc swap2}}
-{{dcl list end}}
+{{dsc end}}
 {{cpp/io/basic_streambuf/inherit}}
+===Notes===
+{{feature test macro|__cpp_lib_fstream_native_handle|std=C++26|value=202306L|native handles support}}
+===See also===
+{{dsc begin}}
+{{dsc inc|cpp/io/c/dsc FILE}}
+{{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)

Public member functions
basic_filebuf::basic_filebuf
basic_filebuf::~basic_filebuf
basic_filebuf::operator= (C++11)
basic_filebuf::swap (C++11)
basic_filebuf::native_handle (C++26)
basic_filebuf::is_open
basic_filebuf::open
basic_filebuf::close
Protected member functions
basic_filebuf::showmanyc
basic_filebuf::underflow
basic_filebuf::uflow
basic_filebuf::pbackfail
basic_filebuf::overflow
basic_filebuf::setbuf
basic_filebuf::seekoff
basic_filebuf::seekpos
basic_filebuf::sync
basic_filebuf::imbue
Non-member functions
swap(std::basic_filebuf) (C++11)

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/io/basic filebuf"

Latest revision as of 14:55, 25 October 2024

Contents

[edit] Member types

[edit] Member functions

Public member functions

Protected member functions

[edit] Non-member functions

Inherited from std::basic_streambuf

Member types

Member functions

Locales

Positioning

Get area

Put area

Putback

Protected member functions

Locales

Positioning

Get area

Put area

Putback

[edit] Notes

[edit] See also

Navigation

Toolbox