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,
        error_code ec = other_error );

      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,
        error_code ec = other_error );

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

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, initialized from the appropriate arguments.

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 patiently identified requirements for portability and internationalization of error messages.

Revised 28 February, 2005

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)