File Descriptor Devices

Overview

Acknowledments

Installation

Headers

Reference

• Class file_descriptor_source
• Class file_descriptor_sink
• Class file_descriptor

The classes file_descriptor_source, file_descriptor_sink and file_descriptor provide file access via operating system file descriptors. These Devices behave much like the File Wrappers basic_file_source, basic_file_sink and basic_file, with the following important differences:

• A file descriptor Device may be constructed from a file descriptor which is already open.
• The only buffering is provded by the Boost Iostreams Library.
• There is no automatic line-endings conversion.
• Wide-character streams are not supported.

Line-ending conversion is available using the Newline Filters. Wide-character versions of the file descriptor Devices may be defined as follows, using the template converter:

    #include <boost/iostreams/converter.hpp>
    #include <boost/iostreams/maped_file.hpp>

    typedef converter<file_descriptor_source>  wfile_descriptor_source;
    typedef converter<file_descriptor_sink>    wfile_descriptor_sink;

When a file descriptor Device is copied, the result represents the same underlying file descriptor. The underlying file descriptor is not duplicated.

Currently, file descriptor Devices do not work corectly with file descriptors opened in non-blocking mode.

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>

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

Synopsis

namespace boost { namespace iostreams {

class file_descriptor_source : public source { // Exposition only
public:
    file_descriptor_source( int fd, bool close = false );
    file_descriptor_source( const std::string& pathname, 
                            std::ios_base::open_mode mode = 
                                std::ios_base::in );
};

} } // End namespace boost::io

file_descriptor_source::file_descriptor_source

    file_descriptor_source( int fd, bool close = false);
    file_descriptor_source( const std::string& pathname, 
                            std::ios_base::open_mode mode = 
                                std::ios_base::in );

The first member constructs a file_descriptor_source to access the file with the given operating system file descriptor. If the second argument is true, the file descriptor is closed when the new file_descriptor_source — or one of its copies — is closed. The second member constructs a file_descriptor_source to access the file with the given pathname. The parameter mode has the same interpretation as (mode | std::ios_base::in) in std::basic_filebuf::open.^[1]

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

Synopsis

namespace boost { namespace iostreams {

class file_descriptor_sink : public sink { // Exposition only
public:
    file_descriptor_sink( int fd, bool close = false );  
    file_descriptor_sink( const std::string& pathname, 
                          std::ios_base::open_mode mode = 
                              std::ios_base::out );
};

} } // End namespace boost::io

file_descriptor_sink::file_descriptor_sink

    file_descriptor_sink( int fd, bool close = false );  
    file_descriptor_sink( const std::string& pathname, 
                          std::ios_base::open_mode mode = 
                              std::ios_base::out );

The first member constructs a file_descriptor_sink to access the file with the given operating system file descriptor. If the second argument is true, the file descriptor is closed when the new file_descriptor_sink — or one of its copies — is closed. The second member constructs a file_descriptor_sink to access the file with the given pathname. The parameter mode has the same interpretation as (mode | std::ios_base::out) in std::basic_filebuf::open.^[1]

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

Synopsis

namespace boost { namespace iostreams {

class file_descriptor : public Device<seekable> { // Exposition only
public:
    file_descriptor( int fd, bool close = false );   
    file_descriptor( const std::string& pathname, 
                     std::ios_base::open_mode mode = 
                         std::ios_base::in | std::ios_base::out );
};

} } // End namespace boost::io

file_descriptor::file_descriptor

    file_descriptor( int fd, bool close = false );
    file_descriptor( const std::string& pathname, 
                     std::ios_base::open_mode mode = 
                         std::ios_base::in | std::ios_base::out );

The first member constructs a file_descriptor to access the file with the given operating system file descriptor. If the second argument is true, the file descriptor is closed when the new file_descriptor — or one of its copies — is closed. The second member constructs a file_descriptor to access the file with the given pathname. The parameter mode has the same interpretation as in std::basic_filebuf::open.^[1]

^[1][ISO], Table 92.

Revised 20 May, 2004

© Copyright Jonathan Turkanis, 2004

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)