Output stream buffer for unix file descriptors.
More...
#include <c++-gtk-utils/fdstream.h>
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.
◆ char_type
template<class charT , class Traits = std::char_traits<charT>>
◆ int_type
template<class charT , class Traits = std::char_traits<charT>>
◆ off_type
template<class charT , class Traits = std::char_traits<charT>>
◆ pos_type
template<class charT , class Traits = std::char_traits<charT>>
◆ traits_type
template<class charT , class Traits = std::char_traits<charT>>
◆ basic_fdoutbuf()
template<class charT , class Traits = std::char_traits<charT>>
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 default constructor of std::basic_streambuf throws. |
◆ ~basic_fdoutbuf()
template<class charT , class Traits = std::char_traits<charT>>
The destructor does not throw.
◆ attach_fd()
template<class charT , class Traits = std::char_traits<charT>>
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). |
◆ can_seek()
template<class charT , class Traits = std::char_traits<charT>>
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.
Since 1.2.6
◆ close_fd()
template<class charT , class Traits = std::char_traits<charT>>
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.
◆ get_fd()
template<class charT , class Traits = std::char_traits<charT>>
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
◆ overflow()
template<class charT , class Traits = std::char_traits<charT>>
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.
◆ seekoff()
template<class charT , class Traits = std::char_traits<charT>>
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 C++11 char16_t type and std::u32streampos for the C++11 char32_t type.) If the seek failed, pos_type(off_type(-1)) is returned.
Since 1.2.6
◆ seekpos()
template<class charT , class Traits = std::char_traits<charT>>
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 C++11 char16_t type and std::u32streampos for the C++11 char32_t type.) If the seek failed, pos_type(off_type(-1)) is returned.
Since 1.2.6
◆ set_buffered()
template<class charT , class Traits = std::char_traits<charT>>
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). |
Since 1.2.6
◆ sync()
template<class charT , class Traits = std::char_traits<charT>>
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.
◆ xsputn()
template<class charT , class Traits = std::char_traits<charT>>
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:
