Cgu::basic_fdoutbuf< charT, Traits > Class Template Reference
fdstreams

Output stream buffer for unix file descriptors. More...

`#include <c++-gtk-utils/fdstream.h>`

Inheritance diagram for Cgu::basic_fdoutbuf< charT, Traits >:

## Public Types

typedef charT | char_type
typedef Traits | traits_type
typedef traits_type::int_type | int_type
typedef traits_type::pos_type | pos_type
typedef traits_type::off_type | off_type

## Public Member Functions

| basic_fdoutbuf (const basic_fdoutbuf &)=delete
basic_fdoutbuf & | operator= (const basic_fdoutbuf &)=delete
| basic_fdoutbuf (int fd_=-1, bool manage_=true)
virtual | ~basic_fdoutbuf ()
void | attach_fd (int fd_, bool manage_=true)
bool | close_fd ()
int | get_fd () const
void | set_buffered (bool buffered)
bool | can_seek () const

## Protected Member Functions

virtual int | sync ()
virtual int_type | overflow (int_type)
virtual std::streamsize | xsputn (const char_type *, std::streamsize)
virtual pos_type | seekoff (off_type off, std::ios_base::seekdir way, std::ios_base::openmode m=std::ios_base::in|std::ios_base::out)
virtual pos_type | seekpos (pos_type p, std::ios_base::openmode m=std::ios_base::in|std::ios_base::out)

## Detailed Description

### template<class charT, class Traits = std::char_traits<charT>>
class Cgu::basic_fdoutbuf< charT, Traits >

Output stream buffer for unix file descriptors.

See Also
  fdstreams

This class provides an output stream buffer for unix file descriptors. It does the buffering for the basic_fdostream stream class.

## Member Typedef Documentation

template<class charT , class Traits = std::char_traits<charT>>

typedef charT Cgu::basic_fdoutbuf< charT, Traits >::char_type

template<class charT , class Traits = std::char_traits<charT>>

typedef traits_type::int_type Cgu::basic_fdoutbuf< charT, Traits >::int_type

template<class charT , class Traits = std::char_traits<charT>>

typedef traits_type::off_type Cgu::basic_fdoutbuf< charT, Traits >::off_type

template<class charT , class Traits = std::char_traits<charT>>

typedef traits_type::pos_type Cgu::basic_fdoutbuf< charT, Traits >::pos_type

template<class charT , class Traits = std::char_traits<charT>>

typedef Traits Cgu::basic_fdoutbuf< charT, Traits >::traits_type

## Constructor & Destructor Documentation

template<class charT , class Traits = std::char_traits<charT>>

Cgu::basic_fdoutbuf< charT, Traits >::basic_fdoutbuf | ( | const basic_fdoutbuf< charT, Traits > & |  | ) |

delete

This class cannot be copied. The copy constructor is deleted.

template<class charT , class Traits = std::char_traits<charT>>

Cgu::basic_fdoutbuf< charT, Traits >::basic_fdoutbuf | ( | int | fd_ = `-1`,
|  | bool | manage_ = `true`
| ) |  |

As this constructor has default argument values, it is also a default constructor. fdstreams do not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.

Parameters

  fd_ | The file descriptor to be attached to the streambuffer, or -1 to attach it latter with the attach_fd() method.
  manage_ | Whether the streambuffer should manage the file descriptor (that is, close it in its destructor or when a new file descriptor is attached).

Exceptions

  std::bad_alloc

  This constructor will throw std::bad_alloc if fd_ >= 0, memory is exhausted and the system throws on such exhaustion (unless the library has been installed using the --with-glib-memory-slices-compat or --with-glib-memory-slices-no-compat configuration option, in which case glib will terminate the program if it is unable to obtain memory from the operating system). No other exception will be thrown unless the constructor of std::basic_streambuf throws.

template<class charT , class Traits = std::char_traits<charT>>

virtual Cgu::basic_fdoutbuf< charT, Traits >::~basic_fdoutbuf | ( |  | ) |

virtual

The destructor does not throw.

## Member Function Documentation

template<class charT , class Traits = std::char_traits<charT>>

void Cgu::basic_fdoutbuf< charT, Traits >::attach_fd | ( | int | fd_,
|  | bool | manage_ = `true`
| ) |  |

Attach a new file descriptor to the streambuffer (and close any file descriptor at present managed by it). If output buffering was previously switched off, it is switched back on again. fdstreams do not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.

Parameters

  fd_ | The new file descriptor to be attached to the streambuffer.
  manage_ | Whether the streambuffer should manage the new file descriptor (that is, close it in its destructor or when a further file descriptor is attached).

Exceptions

  std::bad_alloc

  This method will throw std::bad_alloc if fd_ >= 0, output buffering had previously been switched off, memory is exhausted and the system throws on such exhaustion (unless the library has been installed using the --with-glib-memory-slices-compat or --with-glib-memory-slices-no-compat configuration option, in which case glib will terminate the program if it is unable to obtain memory from the operating system).

template<class charT , class Traits = std::char_traits<charT>>

bool Cgu::basic_fdoutbuf< charT, Traits >::can_seek | ( |  | ) | const

This method indicates whether the output device concerned supports random access, so that a call to seekoff() or seekpos() can succeed. This method does not throw. fdstreams do not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.

Returns
  true if random access is supported, otherwise false. The result is only meaningful if a file descriptor has been attached to this streambuffer.

template<class charT , class Traits = std::char_traits<charT>>

bool Cgu::basic_fdoutbuf< charT, Traits >::close_fd | ( |  | ) |

Close the file descriptor at present attached to the streambuffer (if any). This method does not throw. fdstreams do not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.

Returns
  From version 1.2.6, 'true' if the close succeeded, 'false' if an error arose (including in a case where no descriptor has been attached or it has already been closed). Prior to version 1.2.6, this method had void return type.

template<class charT , class Traits = std::char_traits<charT>>

int Cgu::basic_fdoutbuf< charT, Traits >::get_fd | ( |  | ) | const

inline

Get the file descriptor at present attached to the streambuffer (if any). This method does not throw. fdstreams do not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.

Returns
  The file descriptor at present attached to the streambuffer, or -1 if none has been attached

template<class charT , class Traits = std::char_traits<charT>>

basic_fdoutbuf& Cgu::basic_fdoutbuf< charT, Traits >::operator= | ( | const basic_fdoutbuf< charT, Traits > & |  | ) |

delete

This class cannot be copied. The assignment operator is deleted.

template<class charT , class Traits = std::char_traits<charT>>

virtual int_type Cgu::basic_fdoutbuf< charT, Traits >::overflow | ( | int_type |  | ) |

protectedvirtual

This method will not throw unless std::basic_streambuf<>::sputc() throws, which it would not do on any sane implementation. This means that the output functions of stream objects which have this streambuffer as a member will not throw unless the underlying functions of the std::basic_ostream class throw, which they would not normally do unless they have been required to do so on failbit, badbit or eofbit being set by an explicit call to the exceptions() method of that class. fdstreams do not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.

template<class charT , class Traits = std::char_traits<charT>>

virtual pos_type Cgu::basic_fdoutbuf< charT, Traits >::seekoff | ( | off_type | off,
|  | std::ios_base::seekdir | way,
|  | std::ios_base::openmode | m = `std::ios_base::in|std::ios_base::out`
| ) |  |

protectedvirtual

This method provides random access on output devices that support it, so supporting the tellp() and seekp() methods of the basic_fdostream class. Any output buffer will be flushed. This method does not throw, but if it returns pos_type(off_type(-1)) to indicate failure, it will cause the seekp() or tellp() methods of the relevant stream class to throw std::ios_base::failure if such an exception has been required by an explicit call to the exceptions() method of that class (but not otherwise). fdstreams do not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.

Parameters

  off | The offset to be applied to the 'way' argument when seeking. It is a signed integer type, and on wide character streams is dimensioned as the number of wchar_t units not the number of bytes (that is, it is bytes/sizeof(char_type)).
  way | The file position to which the 'off' argument is to be applied (either std::ios_base::beg, std::ios_base::cur or std::ios_base::end).
  m | The required read/write status of the file descriptor attached to this streambuffer for this method to attempt a seek. As this is an output streambuffer, the argument should have the std::ios_base::out bit set. Provided that bit is set, it doesn't matter if others are also set.

Returns
  If the seek succeeds, a std::char_traits<T>::pos_type object representing the new stream position of the streambuffer after the seek. (This type is std::streampos for narrow character (char) streams, std::wstreampos for wide character (wchar_t) streams, std::u16streampos for the char16_t type and std::u32streampos for the char32_t type.) If the seek failed, pos_type(off_type(-1)) is returned.

template<class charT , class Traits = std::char_traits<charT>>

virtual pos_type Cgu::basic_fdoutbuf< charT, Traits >::seekpos | ( | pos_type | p,
|  | std::ios_base::openmode | m = `std::ios_base::in|std::ios_base::out`
| ) |  |

protectedvirtual

This method provides random access on output devices that support it, so supporting the seekp() method of the basic_fdostream class. It is equivalent to seekoff(off_type(p), std::ios_base::beg, m). Any output buffer will be flushed. This method does not throw, but if it returns pos_type(off_type(-1)) to indicate failure, it will cause the seekp() method of the relevant stream class to throw std::ios_base::failure if such an exception has been required by an explicit call to the exceptions() method of that class (but not otherwise). fdstreams do not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.

Parameters

  p | The absolute position to which the seek is to be made, obtained by a previous call to seekoff() or to this method.
  m | The required read/write status of the file descriptor attached to this streambuffer for this method to attempt a seek. As this is an output stream buffer, the argument should have the std::ios_base::out bit set. Provided that bit is set, it doesn't matter if others are also set.

Returns
  If the seek succeeds, a std::char_traits<T>::pos_type object representing the new stream position of the streambuffer after the seek. (This type is std::streampos for narrow character (char) streams, std::wstreampos for wide character (wchar_t) streams, std::u16streampos for the char16_t type and std::u32streampos for the char32_t type.) If the seek failed, pos_type(off_type(-1)) is returned.

template<class charT , class Traits = std::char_traits<charT>>

void Cgu::basic_fdoutbuf< charT, Traits >::set_buffered | ( | bool | buffered | ) |

Stops output buffering if 'buffered' is false, or reverts to buffering if buffering has previously been switched off and 'buffered' is true. Buffering is on by default for any newly created fdoutbuf object and any newly attached file descriptor. If buffering is turned off, all characters at present in the buffers which are stored for output are flushed. This method has no effect if no file descriptor has yet been attached to this streambuffer. Switching output buffering off is similar in effect to setting the std::ios_base::unitbuf flag in the relevant fdostream object, but is slightly more efficient. fdstreams do not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.

Parameters

  buffered | 'false' if buffering is to be turned off, 'true' if it is to be turned back on.

Exceptions

  std::bad_alloc

  This method will throw std::bad_alloc if 'buffered' is true, output buffering had previously been switched off, memory is exhausted and the system throws on such exhaustion (unless the library has been installed using the --with-glib-memory-slices-compat or --with-glib-memory-slices-no-compat configuration option, in which case glib will terminate the program if it is unable to obtain memory from the operating system).

template<class charT , class Traits = std::char_traits<charT>>

virtual int Cgu::basic_fdoutbuf< charT, Traits >::sync | ( |  | ) |

protectedvirtual

This method will not throw. fdstreams do not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.

template<class charT , class Traits = std::char_traits<charT>>

virtual std::streamsize Cgu::basic_fdoutbuf< charT, Traits >::xsputn | ( | const char_type * | ,
|  | std::streamsize |
| ) |  |

protectedvirtual

This method will not throw. This means that the output functions of stream objects which have this streambuffer as a member will not throw unless the underlying functions of the std::basic_ostream class throw, which they would not normally do unless they have been required to do so on failbit, badbit or eofbit being set by an explicit call to the exceptions() method of that class. fdstreams do not offer concurrent access from multiple threads to the same stream object, and if that is required users should provide their own synchronisation.

The documentation for this class was generated from the following file:

- fdstream.h