Error Reporting

Introduction
Synopsis
Member functions
Non-member functions
    lookup_error_code
    system_message
Acknowledgements

Introduction

The boost/filesystem/path.hpp header provides various error reporting facilities, including class template basic_filesystem_error, publicly derived from std::exception. These facilities are 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
  {
    typedef int errno_type; // determined by C standard; POSIX defers to C standard
    typedef implementation-defined system_error_type;

    errno_type lookup_error_code( system_error_type sys_err_code );
    
    void system_message( system_error_type sys_err_code, std::string & target );

    template<class Path>
    class basic_filesystem_error : public std::exception
    {
    public:
      // compiler generates copy constructor and copy assignment

      typedef Path path_type;

      basic_filesystem_error( const std::string & what, system_error_type se );
      basic_filesystem_error( const std::string & what, const path & path1, system_error_type se );
      basic_filesystem_error( const std::string & what, const path & path1,
        const path & path2, system_error_type se );

      ~basic_filesystem_error() throw();

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

      system_error_type system_error() const;
      const path & path1() const;
      const path & path2() const;
    };

    typedef basic_filesystem_error<path> filesystem_error;
    typedef basic_filesystem_error<wpath> wfilesystem_error;

  } // namespace filesystem
} // namespace boost

For POSIX and Windows, system_error_type is int.

Member functions

Constructors

     basic_filesystem_error( const std::string & what, system_error_type se );
     basic_filesystem_error( const std::string & what, const path & path1, system_error_type se );
     basic_filesystem_error( const std::string & what, const path & path1,
        const path & path2, system_error_type se );

Effects: Constructs a basic_filesystem_error object, initialized from the appropriate arguments.

what

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

Returns: A string identifying the error, including 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.

system_error

system_error_type system_error() const;

Returns: The se argument to the constructor.

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.

Non-member functions

lookup_error_code

errno_type lookup_error_code( system_error_type sys_err_code );

Returns: A value corresponding to sys_err_code. Macros for errno_type values are defined in <boost/filesystem/cerrno.hpp>, and are described in [POSIX-01] under <errno.h>..

system_message

void system_message( system_error_type sys_err_code, std::string & target );

Effects: Appends an operating system message corresponding to sys_err_code to target.

Acknowledgements

Peter Dimov patiently identified requirements for portability and internationalization of error messages. He also suggested basing the portable error codes on POSIX.

Revised 21 June, 2005

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