File Descriptor Devices

# File Descriptors

Overview
Acknowledments
Installation
Headers
Reference

- Class `file_descriptor_source`
- Class `file_descriptor_sink`
- Class `file_descriptor`

## 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:

- 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-ending conversion.
- Wide-character streams are not supported.

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, bool close_on_exit = false );

        // Windows-only
        file_descriptor_sink( HANDLE hFile, bool close_on_exit = false );

        // Deprecated
        file_descriptor_sink( int fd, file_descriptor_flags );

        // Deprecated, Windows-only
        file_descriptor_sink( HANDLE hFile, file_descriptor_flags );

        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, bool close_on_exit = false );

        // Windows-only
        file_descriptor_sink( HANDLE hFile, bool close_on_exit = false );

        // Deprecated
        file_descriptor_sink( int fd, file_descriptor_flags );

        // Deprecated, Windows-only
        file_descriptor_sink( HANDLE hFile, file_descriptor_flags );

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.

Revised 02 Feb 2008

© 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)