cppdraft_translate/cppdraft/filebuf/virtuals.md

[filebuf.virtuals]

# 31 Input/output library [[input.output]](./#input.output)

## 31.10 File-based streams [[file.streams]](file.streams#filebuf.virtuals)

### 31.10.3 Class template basic_filebuf [[filebuf]](filebuf#virtuals)

#### 31.10.3.5 Overridden virtual functions [filebuf.virtuals]

[🔗](#lib:showmanyc,basic_filebuf)

`streamsize showmanyc() override;
`

[1](#1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11392)

*Effects*: Behaves the same asbasic_streambuf​::​showmanyc() ([[streambuf.virtuals]](streambuf.virtuals "31.6.3.5 Virtual functions"))[.](#1.sentence-1)

[2](#2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11398)

*Remarks*: An
implementation may provide an overriding definition for this function
signature if it can determine whether more characters can be read from the input
sequence[.](#2.sentence-1)

[🔗](#lib:underflow,basic_filebuf)

`int_type underflow() override;
`

[3](#3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11412)

*Effects*: Behaves according to the description ofbasic_streambuf<charT, traits>​::​underflow(),
with the specialization that a sequence of characters is read from the input
sequence as if by reading from the associated file
into an internal buffer (extern_buf)
and then as if by doing:char extern_buf[XSIZE];char* extern_end;
charT intern_buf[ISIZE];
charT* intern_end;
codecvt_base::result r = a_codecvt.in(state, extern_buf, extern_buf+XSIZE, extern_end,
 intern_buf, intern_buf+ISIZE, intern_end);

This shall be done in such a way that the class can recover the
position
(fpos_t)
corresponding to each character betweenintern_buf andintern_end[.](#3.sentence-2)

If the value ofr indicates thata_codecvt.in() ran out of space inintern_buf,
retry with a largerintern_buf[.](#3.sentence-3)

[🔗](#lib:uflow,basic_filebuf)

`int_type uflow() override;
`

[4](#4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11453)

*Effects*: Behaves according to the description ofbasic_streambuf<charT, traits>​::​uflow(),
with the specialization that a sequence of characters is read from the input
with the same method as used byunderflow[.](#4.sentence-1)

[🔗](#lib:pbackfail,basic_filebuf)

`int_type pbackfail(int_type c = traits::eof()) override;
`

[5](#5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11468)

*Effects*: Puts back the character designated by c to the input
sequence, if possible, in one of three ways:

- [(5.1)](#5.1)

  Iftraits​::​eq_int_type(c, traits​::​eof()) returnsfalse and
if the function makes a putback position available
and iftraits​::​eq(to_char_type(c), gptr()[-1]) returnstrue,
decrements the next pointer for the input sequence,gptr()[.](#5.1.sentence-1)
  Returns:c[.](#5.1.sentence-2)

- [(5.2)](#5.2)

  Iftraits​::​eq_int_type(c, traits​::​eof()) returnsfalse and
if the function makes a putback position available
and if the function is permitted to assign to the putback position,
decrements the next pointer for the input sequence,
and stores c there[.](#5.2.sentence-1)
  Returns:c[.](#5.2.sentence-2)

- [(5.3)](#5.3)

  Iftraits​::​eq_int_type(c, traits​::​eof()) returnstrue,
and if either the input sequence has a putback position available or
the function makes a putback position available,
decrements the next pointer for the input sequence,gptr()[.](#5.3.sentence-1)
  Returns:traits​::​not_eof(c)[.](#5.3.sentence-2)

[6](#6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11518)

*Returns*: As specified above, ortraits​::​eof() to indicate failure[.](#6.sentence-1)

[7](#7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11524)

*Remarks*: Ifis_open() == false,
the function always fails[.](#7.sentence-1)

[8](#8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11530)

The function does not put back a character directly to the input sequence[.](#8.sentence-1)

[9](#9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11533)

If the function can succeed in more than one of these ways, it is
unspecified which way is chosen[.](#9.sentence-1)

The function can alter the number of putback positions available as a result of any call[.](#9.sentence-2)

[🔗](#lib:overflow,basic_filebuf)

`int_type overflow(int_type c = traits::eof()) override;
`

[10](#10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11545)

*Effects*: Behaves according to the description ofbasic_streambuf<charT, traits>​::​overflow(c),
except that the behavior of “consuming characters” is performed by first
converting as if by:charT* b = pbase();
charT* p = pptr();
charT* end;char xbuf[XSIZE];char* xbuf_end;
codecvt_base::result r = a_codecvt.out(state, b, p, end, xbuf, xbuf+XSIZE, xbuf_end); and then

- [(10.1)](#10.1)

  If r == codecvt_base​::​error then fail[.](#10.1.sentence-1)

- [(10.2)](#10.2)

  If r == codecvt_base​::​noconv then output characters fromb up to (and not including) p[.](#10.2.sentence-1)

- [(10.3)](#10.3)

  If r == codecvt_base​::​partial then output to the file characters fromxbuf up to xbuf_end, and repeat using characters fromend to p[.](#10.3.sentence-1)
  If output fails, fail (without repeating)[.](#10.3.sentence-2)

- [(10.4)](#10.4)

  Otherwise output from xbuf to xbuf_end, and fail if output fails[.](#10.4.sentence-1)
  At this point if b != p and b == end (xbuf isn't large
enough) then increase XSIZE and repeat from the beginning[.](#10.4.sentence-2)

Then establishes an observable checkpoint ([[intro.abstract]](intro.abstract "4.1.2 Abstract machine"))[.](#10.sentence-2)

[11](#11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11574)

*Returns*: traits​::​not_eof(c) to indicate success, andtraits​::​eof() to indicate failure[.](#11.sentence-1)

Ifis_open() == false,
the function always fails[.](#11.sentence-2)

[🔗](#lib:setbuf,basic_filebuf)

`basic_streambuf* setbuf(char_type* s, streamsize n) override;
`

[12](#12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11591)

*Effects*: Ifsetbuf(0, 0) is called on a stream before any I/O has occurred on that stream, the
stream becomes unbuffered[.](#12.sentence-1)

Otherwise the results are implementation-defined[.](#12.sentence-2)

“Unbuffered” means thatpbase() andpptr() always return null
and output to the file should appear as soon as possible[.](#12.sentence-3)

[🔗](#lib:seekoff,basic_filebuf)

`pos_type seekoff(off_type off, ios_base::seekdir way,
                 ios_base::openmode which
                   = ios_base::in | ios_base::out) override;
`

[13](#13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11615)

*Effects*: Letwidth denotea_codecvt.encoding()[.](#13.sentence-1)

Ifis_open() == false,
oroff != 0 && width <= 0,
then the positioning operation fails[.](#13.sentence-2)

Otherwise, ifway != basic_ios​::​cur oroff != 0,
and if the last operation was output,
then update the output sequence and write any unshift sequence[.](#13.sentence-3)

Next, seek to the new position: ifwidth > 0,
callfseek(file, width * off, whence),
otherwise callfseek(file, 0, whence)[.](#13.sentence-4)

[14](#14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11639)

*Returns*: A newly constructedpos_type object that stores the resultant
stream position, if possible[.](#14.sentence-1)

If the positioning operation fails, or
if the object cannot represent the resultant stream position,
returnspos_type(off_type(-1))[.](#14.sentence-2)

[15](#15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11650)

*Remarks*: “The last operation was output” means either
the last virtual operation was overflow or
the put buffer is non-empty[.](#15.sentence-1)

“Write any unshift sequence” means,
ifwidth is less than zero then calla_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end) and output the resulting unshift sequence[.](#15.sentence-2)

The function determines one of three values for the
argument whence, of typeint,
as indicated in Table [147](#tab:filebuf.seekoff "Table 147: seekoff effects")[.](#15.sentence-3)

Table [147](#tab:filebuf.seekoff) — seekoff effects [[tab:filebuf.seekoff]](./tab:filebuf.seekoff)  

| [🔗](#tab:filebuf.seekoff-row-1)<br>**way Value** | **stdio Equivalent** |
| --- | --- |
| [🔗](#tab:filebuf.seekoff-row-2)<br>basic_ios​::​beg | SEEK_SET |
| [🔗](#tab:filebuf.seekoff-row-3)<br>basic_ios​::​cur | SEEK_CUR |
| [🔗](#tab:filebuf.seekoff-row-4)<br>basic_ios​::​end | SEEK_END |

[🔗](#lib:seekpos,basic_filebuf)

`pos_type seekpos(pos_type sp,
                 ios_base::openmode which
                   = ios_base::in | ios_base::out) override;
`

[16](#16)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11682)

Alters the file position, if possible, to correspond to the position
stored in sp (as described below)[.](#16.sentence-1)

Altering the file position performs as follows:

| [1.](#16.1) | if (om & ios_base​::​out) != 0, then update the output sequence and write any unshift sequence; |
| --- | --- |
| [2.](#16.2) | set the file position to sp as if by a call to fsetpos; |
| [3.](#16.3) | if (om & ios_base​::​in) != 0, then update the input sequence; |

where om is the open mode passed to the last call toopen()[.](#16.sentence-2)

The operation fails ifis_open() returns false[.](#16.sentence-3)

[17](#17)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11705)

If sp is an invalid stream position, or if the function positions
neither sequence, the positioning operation fails[.](#17.sentence-1)

If sp has not been obtained by a previous successful call to one of
the positioning functions
(seekoff orseekpos)
on the same file the effects are undefined[.](#17.sentence-2)

[18](#18)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11715)

*Returns*: sp on success[.](#18.sentence-1)

Otherwise returnspos_type(off_type(-1))[.](#18.sentence-2)

[🔗](#lib:sync,basic_filebuf)

`int sync() override;
`

[19](#19)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11729)

*Effects*: If a put area exists, callsfilebuf​::​overflow to write the characters to the file,
then flushes the file as if by calling fflush(file)[.](#19.sentence-1)

If a get area exists, the effect is implementation-defined[.](#19.sentence-2)

[🔗](#lib:imbue,basic_filebuf)

`void imbue(const locale& loc) override;
`

[20](#20)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11745)

*Preconditions*: If the file is not positioned at its beginning and the encoding of the current
locale as determined bya_codecvt.encoding() is state-dependent ([[locale.codecvt.virtuals]](locale.codecvt.virtuals "28.3.4.2.5.3 Virtual functions"))
then that facet is the same as
the corresponding facet of loc[.](#20.sentence-1)

[21](#21)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11754)

*Effects*: Causes characters inserted or extracted after this call
to be converted according to loc until another call ofimbue[.](#21.sentence-1)

[22](#22)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L11760)

*Remarks*: This may require reconversion of previously converted characters[.](#22.sentence-1)

This in turn may require the implementation to be able to reconstruct
the original contents of the file[.](#22.sentence-2)