Boost Filesystem exception.hpp Header

# boost/filesystem/exception.hpp

Introduction
Synopsis
Member functions
Acknowledgements

## Introduction

The header provides class filesystem_error, publicly derived from std::runtime_error, which is used by functions in the Filesystem Library to report operational errors.

The design evolved based on user requests to ease portability and internationalization. See the Boost Error and Exception Handling guidelines.

## Synopsis

    namespace boost
    {
      namespace filesystem
      {
        enum error_code
        {
          no_error = 0,
          system_error,     // system generated error; if possible, is translated
                            // to one of the more specific errors below.
          other_error,      // library generated error
          security_error,   // includes access rights, permissions failures
          read_only_error,
          io_error,
          path_error,
          not_found_error,
          not_directory_error,
          busy_error,       // implies trying again might succeed
          already_exists_error,
          not_empty_error,
          is_directory_error,
          out_of_space_error,
          out_of_memory_error,
          out_of_resource_error
        };

        class filesystem_error : public std::exception
        {
        public:

          filesystem_error( const std::string & who,
            const std::string & message );

          filesystem_error( const std::string & who,
            const path & path1, const std::string & message );

          filesystem_error( const std::string & who,
            const path & path1, sys_err sys_err_code );

          filesystem_error( const std::string & who,
            const path & path1, const path & path2,
            sys_err sys_err_code );

          ~filesystem_error() throw();

          virtual const char * what() const throw();

          sys_err native_error() const;
          error_code error() const;
          const std::string & who() const;
          const path & path1() const;
          const path & path2() const;
        };
      } // namespace filesystem
    } // namespace boost

For POSIX and Windows, `sys_err` is `int`. For other operating systems, it is implementation defined.

## Member functions

### Constructors

>     filesystem_error( const std::string & who,
>       const std::string & message );

>     filesystem_error( const std::string & who,
>       const path & path1, const std::string & message );

>     filesystem_error( const std::string & who,
>       const path & path1, int sys_err_code );

>     filesystem_error( const std::string & who,
>       const path & path1, const path & path2,
>       int sys_err_code );

> Precondition: The `who` argument is in the form, as appropriate:

> - boost::filesystem::class-name::function-name for errors from public member functions
> - boost::filesystem::class-name for errors not identified with a particular member function.
> - boost::filesystem::function-name for errors from non-member functions.

> These forms are explicitly specified to ensure portability of user programs between library implementations.

> Effects: Constructs a filesystem_error object.

### what

> `virtual const char * what() const throw();`

> Returns: A string identifying the error, including who(), path1(), path2(), and related messages. If an error occurs in the preparation of the string, particularly in low-memory situations, an implementation is permitted to return a simpler static string.

### native_error

> `sys_err` `native_error() const;`

> Returns: The `sys_err_code` argument to the constructor, if any. Otherwise, 0.

### error

>     error_code error() const;

> Returns: `native_error()` translated to `error_code`. The translation is implementation-defined. For the POSIX and Windows implementations, see libs/filesystem/src/exception.cpp.

### who

>     const std::string & who() const;

> Returns: The `who` argument to the constructor. An implementation is permitted to return an empty string if an exception, for example, std::bad_alloc, occurs during processing.

### path1

>     const path & path1() const;

> Returns: The `path1` argument to the constructor, if any, otherwise `path()`. An implementation is permitted to return an empty path if an exception, for example, std::bad_alloc, occurs during processing.

### path2

>     const path & path2() const;

> Returns: The `path2` argument to the constructor, if any, otherwise `path()`. An implementation is permitted to return an empty path if an exception, for example, std::bad_alloc, occurs during processing.

## Acknowledgements

Peter Dimov patently identified requirements for portability and internationalization of error messages.

Revised 02 October, 2003

© Copyright Beman Dawes, 2002

Use, modification, and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)