The classes file_descriptor_source
, file_descriptor_sink
and file_descriptor
provide file access via operating system file handles or file descriptors. These Devices behave much like the File Wrappers basic_file_source
, basic_file_sink
and basic_file
, with the following important differences:
When a file descriptor Device is copied, the result represents the same underlying file descriptor. The underlying file descriptor is not duplicated.
The classes file_descriptor
supports 64-bit seek offsets whenever they are supported by the underlying operating system or runtime library. Currently, file descriptor Devices may not work corectly with file descriptors opened in non-blocking mode.
Line-ending conversion can be provided, if desired, using the class newline_filter
. Wide-character versions of the file descriptor Devices may be defined as follows, using the template code_converter
:
#include <boost/iostreams/code_converter.hpp> #include <boost/iostreams/maped_file.hpp> typedef code_converter<file_descriptor_source> wfile_descriptor_source; typedef code_converter<file_descriptor_sink> wfile_descriptor_sink;
The file descriptor Devices are based on work of Nicolai Josuttis ([Josuttis1] pp. 672-3 and [Josuttis2]).
The file descriptor Devices depends on the source file <libs/iostreams/src/file_descriptor.cpp>
, which makes use of Windows or POSIX headers depending on the user's operating system. For installation instructions see Installation.
<boost/iostreams/device/file_descriptor.hpp>
file_descriptor_source
Model of SeekableSource and Closable providing read-only access to a file through an operating system file descriptor.
namespace boost { namespace iostreams { enum file_descriptor_flags { never_close_handle, close_handle }; class file_descriptor_source { public: typedef char char_type; typedef [implementation-defined] handle_type; typedef [implementation-defined] category; file_descriptor_source(); template<typename Path> file_descriptor_source( const Path& pathname, std::ios_base::open_mode mode = std::ios_base::in ); file_descriptor_source( int fd, file_descriptor_flags ); // Windows-only file_descriptor_source( HANDLE hFile, file_descriptor_flags ); // Deprecated file_descriptor_source( int fd, bool close_on_exit = false ); // Deprecated, Windows-only file_descriptor_source( HANDLE hFile, bool close_on_exit = false ); template<typename Path> void open( const Path& pathname, std::ios_base::open_mode mode = std::ios_base::in ); void open( int fd, file_descriptor_flags ); // Windows-only void open( HANDLE hFile, file_descriptor_flags ); // Deprecated void open( int fd, bool close_on_exit = false ); // Deprecated, Windows-only void open( HANDLE hFile, bool close_on_exit = false ); bool is_open() const; handle_type handle() const; }; } } // End namespace boost::io
file_descriptor_source::file_descriptor_source
file_descriptor_source(); template<typename Path> file_descriptor_source( const Path& pathname, std::ios_base::open_mode mode = std::ios_base::in ); file_descriptor_source( int fd, file_descriptor_flags ); // Windows-only file_descriptor_source( HANDLE hFile, file_descriptor_flags ); // Deprecated file_descriptor_source( int fd, bool close_on_exit = false ); // Deprecated, Windows-only file_descriptor_source( HANDLE hFile, bool close_on_exit = false );
The first member constructs an empty file_descriptor_source
.
The second member constructs a file_descriptor_source
to access the file with the given pathname. Path
should be either a string or a Boost.Filesystem path. The parameter mode
has the same interpretation as (mode | std::ios_base::in)
in std::basic_filebuf::open
.[1]
The third member constructs a file_descriptor_source
to access the file with the given operating system or runtime-library file descriptor.
If the second argument is close_handle
, the file descriptor is closed when the file_descriptor_source
being constructed — or one of its copies — is closed or destructed.
The fourth member is the same as the third, except that it accepts a Windows file handle instead of a file descriptor.
If the second argument is close_handle
, the file descriptor is closed when the file_descriptor_source
being constructed — or one of its copies — is closed or destructed.
The deprecated members are there to provide backwards compatability with old versions.
To use them you need to define BOOST_IOSTREAMS_USE_DEPRECATED
.
The descriptor is always closed by close
but only closed in destructors if close_on_exit
is true
.
file_descriptor_source::open
template<typename Path> void open( const Path& pathname, std::ios_base::open_mode mode = std::ios_base::in ); void open( int fd, file_descriptor_flags ); // Windows-only void open( HANDLE hFile, file_descriptor_flags ); // Deprecated void open( int fd, bool close_on_exit = false ); // Deprecated, Windows-only void open( HANDLE hFile, bool close_on_exit = false );
The parameters of open
the same as those of the corresponding constructors.
If the file descriptor already holds a file, it'll be closed
(unless opened or constructed with never_close_handle
).
file_descriptor_source::is_open
bool is_open() const;
Returns true
if the underlying file was opened successfully.
file_descriptor_source::handle
handle_type handle() const;
Returns the underlying OS file descriptor. On Windows, this is a HANDLE
. On other systems, it is an int
.
file_descriptor_sink
Model of SeekableSink and Closable providing write-only access to a file through an operating system file descriptor.
namespace boost { namespace iostreams { enum file_descriptor_flags { never_close_handle, close_handle }; class file_descriptor_sink { public: typedef char char_type; typedef [implementation-defined] handle_type; typedef [implementation-defined] category; file_descriptor_sink(); template<typename Path> file_descriptor_sink( const Path& pathname, std::ios_base::open_mode mode = std::ios_base::out ); file_descriptor_sink( int fd, file_descriptor_flags ); // Windows-only file_descriptor_sink( HANDLE hFile, file_descriptor_flags ); // Deprecated file_descriptor_sink( int fd, bool close_on_exit = false ); // Deprecated, Windows-only file_descriptor_sink( HANDLE hFile, bool close_on_exit = false ); template<typename Path> void open( const Path& pathname, std::ios_base::open_mode mode = std::ios_base::out ); void open( int fd, file_descriptor_flags ); // Windows-only void open( HANDLE hFile, file_descriptor_flags ); // Deprecated void open( int fd, bool close_on_exit = false ); // Deprecated, Windows-only void open( HANDLE hFile, bool close_on_exit = false ); bool is_open() const; handle_type handle() const; }; } } // End namespace boost::io
file_descriptor_sink::file_descriptor_sink
file_descriptor_sink(); template<typename Path> file_descriptor_sink( const Path& pathname, std::ios_base::open_mode mode = std::ios_base::out ); file_descriptor_sink( int fd, file_descriptor_flags ); // Windows-only file_descriptor_sink( HANDLE hFile, file_descriptor_flags ); // Deprecated file_descriptor_sink( int fd, bool close_on_exit = false ); // Deprecated, Windows-only file_descriptor_sink( HANDLE hFile, bool close_on_exit = false );
The first member constructs an empty file_descriptor_sink
.
The second member constructs a file_descriptor_sink
to access the file with the given pathname. Path
should be either a string or a Boost.Filesystem path. The parameter mode
has the same interpretation as (mode | std::ios_base::out)
in std::basic_filebuf::open
.[1]
The third member constructs a file_descriptor_sink
to access the file with the given operating system or runtime-library file descriptor.
If the second argument is close_handle
, the file descriptor is closed when the file_descriptor_sink
being constructed — or one of its copies — is closed or destructed.
The fourth member is the same as the third, except that it accepts a Windows file handle instead of a file descriptor.
If the second argument is close_handle
, the file descriptor is closed when the file_descriptor_sink
being constructed — or one of its copies — is closed or destructed.
The deprecated members are there to provide backwards compatability with old versions.
To use them you need to define BOOST_IOSTREAMS_USE_DEPRECATED
.
The descriptor is always closed by close
but only closed in destructors if close_on_exit
is true
.
file_descriptor_sink::open
template<typename Path> void open( const Path& pathname, std::ios_base::open_mode mode = std::ios_base::out ); void open( int fd, file_descriptor_flags ); // Windows-only void open( HANDLE hFile, file_descriptor_flags ); // Deprecated void open( int fd, bool close_on_exit = false ); // Deprecated, Windows-only void open( HANDLE hFile, bool close_on_exit = false );
The parameters of open
the same as those of the corresponding constructors.
If the file descriptor already holds a file, it'll be closed
(unless opened or constructed with never_close_handle
).
file_descriptor_sink::is_open
bool is_open() const;
Returns true
if the underlying file was opened successfully.
file_descriptor_sink::handle
handle_type handle() const;
Returns the underlying OS file descriptor. On Windows, this is a HANDLE
. On other systems, it is an int
.
file_descriptor
Model of SeekableDevice and Closable providing read-write access to a file through an operating system file descriptor.
namespace boost { namespace iostreams { enum file_descriptor_flags { never_close_handle, close_handle }; class file_descriptor { public: typedef char char_type; typedef [implementation-defined] handle_type; typedef [implementation-defined] category; file_descriptor(); template<typename Path> file_descriptor( const Path& pathname, std::ios_base::open_mode mode = std::ios_base::in | std::ios_base::out ); file_descriptor( int fd, file_descriptor_flags ); // Windows-only file_descriptor( HANDLE hFile, file_descriptor_flags ); // Deprecated file_descriptor( int fd, bool close_on_exit = false ); // Deprecated, Windows-only file_descriptor( HANDLE hFile, bool close_on_exit = false ); template<typename Path> void open( const Path& pathname, std::ios_base::open_mode mode = std::ios_base::in | std::ios_base::out ); void open( int fd, file_descriptor_flags ); // Windows-only void open( HANDLE hFile, file_descriptor_flags ); // Deprecated void open( int fd, bool close_on_exit = false ); // Deprecated, Windows-only void open( HANDLE hFile, bool close_on_exit = false ); bool is_open() const; handle_type handle() const; }; } } // End namespace boost::io
file_descriptor::file_descriptor
file_descriptor(); template<typename Path> file_descriptor( const Path& pathname, std::ios_base::open_mode mode = std::ios_base::in | std::ios_base::out ); file_descriptor( int fd, file_descriptor_flags ); // Windows-only file_descriptor( HANDLE hFile, file_descriptor_flags ); // Deprecated file_descriptor( int fd, bool close_on_exit = false ); // Deprecated, Windows-only file_descriptor( HANDLE hFile, bool close_on_exit = false );
The first member constructs an empty file_descriptor
.
The second member constructs a file_descriptor
to access the file with the given pathname. Path
should be either a string or a Boost.Filesystem path. The parameter mode
has the same interpretation as in std::basic_filebuf::open
.[1]
The third member constructs a file_descriptor
to access the file with the given operating system or runtime-library file descriptor.
If the second argument is close_handle
, the file descriptor is closed when the file_descriptor
being constructed — or one of its copies — is closed or destructed.
The fourth member is the same as the third, except that it accepts a Windows file handle instead of a file descriptor.
If the second argument is close_handle
, the file descriptor is closed when the new file_descriptor
— or one of its copies — is closed or destructed.
The deprecated members are there to provide backwards compatability with old versions.
To use them you need to define BOOST_IOSTREAMS_USE_DEPRECATED
.
The descriptor is always closed by close
but only closed in destructors if close_on_exit
is true
.
file_descriptor::open
template<typename Path> void open( const Path& pathname, std::ios_base::open_mode mode = std::ios_base::in | std::ios_base::out ); void open( int fd, file_descriptor_flags ); // Windows-only void open( HANDLE hFile, file_descriptor_flags ); // Deprecated void open( int fd, bool close_on_exit = false ); // Deprecated, Windows-only void open( HANDLE hFile, bool close_on_exit = false );
The parameters of open
the same as those of the corresponding constructors.
If the file descriptor already holds a file, it'll be closed
(unless opened or constructed with never_close_handle
).
file_descriptor::is_open
bool is_open() const;
Returns true
if the underlying file was opened successfully.
file_descriptor::handle
handle_type handle() const;
Returns the underlying OS file descriptor. On Windows, this is a HANDLE
. On other systems, it is an int
.
© Copyright 2008 CodeRage, LLC
© Copyright 2004-2007 Jonathan Turkanis
Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)