File Descriptors

Overview
Acknowledments
Installation
Headers
Reference

Overview

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;

Acknowledgments

The file descriptor Devices are based on work of Nicolai Josuttis ([Josuttis1] pp. 672-3 and [Josuttis2]).

Installation

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.

Headers

<boost/iostreams/device/file_descriptor.hpp>

Reference

Class file_descriptor_source

Description

Model of SeekableSource and Closable providing read-only access to a file through an operating system file descriptor.

Synopsis

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.

Class file_descriptor_sink

Description

Model of SeekableSink and Closable providing write-only access to a file through an operating system file descriptor.

Synopsis

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.

Class file_descriptor

Description

Model of SeekableDevice and Closable providing read-write access to a file through an operating system file descriptor.

Synopsis

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.


[1][ISO], Table 92.