[streambuf.virt.put]

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

## 31.6 Stream buffers [[stream.buffers]](stream.buffers#streambuf.virt.put)

### 31.6.3 Class template basic_streambuf [[streambuf]](streambuf#virt.put)

#### 31.6.3.5 Virtual functions [[streambuf.virtuals]](streambuf.virtuals#streambuf.virt.put)

#### 31.6.3.5.5 Put area [streambuf.virt.put]

[🔗](#lib:xsputn,basic_streambuf)

`streamsize xsputn(const char_type* s, streamsize n);
`

[1](#1)

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

*Effects*: Writes up to n characters to the output sequence as if
by repeated calls tosputc(c)[.](#1.sentence-1)

The characters written are obtained from successive elements of
the array whose first element is designated by s[.](#1.sentence-2)

Writing stops when either n characters have been written or
a call tosputc(c) would returntraits​::​eof()[.](#1.sentence-3)

It is unspecified whether the function calls overflow() when pptr() == epptr() becomes true or whether it achieves the same effects by other means[.](#1.sentence-4)

[2](#2)

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

*Returns*: The number of characters written[.](#2.sentence-1)

[🔗](#lib:overflow,basic_streambuf)

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

[3](#3)

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

*Effects*: Consumes some initial subsequence of the characters of the[*pending sequence*](#def:pending_sequence)[.](#3.sentence-1)

The pending sequence is defined as the concatenation of

- [(3.1)](#3.1)

the empty sequence if pbase() is null, otherwise thepptr() - pbase() characters beginning atpbase(), followed by

- [(3.2)](#3.2)

the empty sequence
iftraits​::​eq_int_type(c, traits​::​eof()) returnstrue, otherwise the sequence consisting of c[.](#3.sentence-2)

[4](#4)

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

*Preconditions*: Every overriding definition of this virtual function
obeys the following constraints:

- [(4.1)](#4.1)

  The effect of consuming a character on the associated output sequence is
specified[.](#4.1.sentence-1)[270](#footnote-270 "That is, for each class derived from a specialization of basic_­streambuf in this Clause ([stringbuf], [filebuf]), a specification of how consuming a character effects the associated output sequence is given. There is no requirement on a program-defined class.")

- [(4.2)](#4.2)

  Letr be the number of characters in the pending sequence not consumed[.](#4.2.sentence-1)
  Ifr is nonzero thenpbase() andpptr() are set so that:pptr() - pbase() == r and the r characters starting atpbase() are the associated output stream[.](#4.2.sentence-2)
  In case r is zero (all characters of the pending sequence have been consumed)
then eitherpbase() is set tonullptr,
orpbase() andpptr() are both set to the same non-null value[.](#4.2.sentence-3)

- [(4.3)](#4.3)

  The function may fail if either
appending some character to the associated output stream fails or
if it is unable to establishpbase() andpptr() according to the above rules[.](#4.3.sentence-1)

[5](#5)

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

*Returns*: traits​::​eof() or throws an exception
if the function fails[.](#5.sentence-1)

Otherwise,
returns some value other thantraits​::​eof() to indicate success[.](#5.sentence-2)[271](#footnote-271 "Typically, overflow returns c to indicate success, except when traits​::​eq_­int_­type(c, traits​::​eof()) returns true, in which case it returns traits​::​not_­eof(c).")

[6](#6)

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

*Default behavior*: Returnstraits​::​eof()[.](#6.sentence-1)

[7](#7)

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

*Remarks*: The member functionssputc() andsputn() call this function in case that
no room can be found in the put buffer enough to accommodate the
argument character sequence[.](#7.sentence-1)

[270)](#footnote-270)[270)](#footnoteref-270)

That is, for each class derived from a specialization ofbasic_streambuf in this Clause ([[stringbuf]](stringbuf "31.8.2 Class template basic_­stringbuf"), [[filebuf]](filebuf "31.10.3 Class template basic_­filebuf")),
a specification of how consuming a character effects the associated output sequence is given[.](#footnote-270.sentence-1)

There is no requirement on a program-defined class[.](#footnote-270.sentence-2)

[271)](#footnote-271)[271)](#footnoteref-271)

Typically,overflow returns c to indicate success, except whentraits​::​eq_int_type(c, traits​::​eof()) returnstrue,
in which case it returnstraits​::​not_eof(c)[.](#footnote-271.sentence-1)