Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

Class object_name

boost::log::ipc::object_name — A system object name class.

Synopsis

// In header: <boost/log/utility/ipc/object_name.hpp>


class object_name {
public:

  // Name scopes. 
  enum scope { global, user, session, process_group };
  // construct/copy/destruct
  object_name() noexcept;
  object_name(object_name &&) noexcept;
  object_name(object_name const &);
  object_name(scope, const char *);
  object_name(scope, std::string const &);
  object_name & operator=(object_name &&) noexcept;
  object_name & operator=(object_name const &);

  // public member functions
  bool empty() const noexcept;
  std::size_t size() const noexcept;
  const char * c_str() const noexcept;
  void swap(object_name &) noexcept;

  // public static functions
  static object_name from_native(const char *);
  static object_name from_native(std::string const &);

  // friend functions
  friend void swap(object_name &, object_name &) noexcept;
  friend std::string to_string(object_name const &);
  friend bool operator==(object_name const &, object_name const &) noexcept;
  friend bool operator!=(object_name const &, object_name const &) noexcept;
  friend bool operator<(object_name const &, object_name const &) noexcept;
  friend bool operator>(object_name const &, object_name const &) noexcept;
  friend bool operator<=(object_name const &, object_name const &) noexcept;
  friend bool operator>=(object_name const &, object_name const &) noexcept;
  template<typename CharT, typename TraitsT> 
    friend std::basic_ostream< CharT, TraitsT > & 
    operator<<(std::basic_ostream< CharT, TraitsT > &, object_name const &);
};

Description

In order to identify a system-wide object such as a shared memory segment or a named synchronization primitive the object has to be given a name. The format of the name is specific to the operating system and the object_name class provides an abstraction for names of objects. It also provides means for scoping, which allows to avoid name clashes between different processes.

The object name is a UTF-8 encoded string. The portable object name should consist of the following characters:

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
a b c d e f g h i j k l m n o p q r s t u v w x y z
0 1 2 3 4 5 6 7 8 9 . _ -
[Note] Note

The character set corresponds to the POSIX Portable Filename Character Set (http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_278).

Use of other characters may result in non-portable system-specific behavior.

The name can have one of the following scopes:

  • global - objects within this scope are visible to any process on the system. In order to use this scope the process may need to have extended privileges. This scope is not available for Windows Store applications.

  • user - objects within this scope can be opened by processes running under the same user as the current process.

  • session - objects within this scope are visible to processes within the session of the current process. The definition of a session may vary between operating systems. On POSIX, a session is typically a group of processes attached to a single virtual terminal device. On Windows a session is started when a user logs into the system. There is also a separate session for Windows services.

  • process_group - objects within this scope are visible to processes within the process group of the current process. Currently, on Windows all processes running in the current session are considered members of the same process group. This may change in future.

The scopes are not overlapping. For instance, if an object is created in the global scope, the object cannot be opened with the same name but in user's scope.

Note that name scoping is not a security feature. On some systems any process on the system has technical capability to open objects within any scope. The scope is only used to help avoid name clashes between processes using object_name to identify objects.

object_name public construct/copy/destruct

  1. object_name() noexcept;

    Default constructor. The method creates an empty object name.

    Postconditions:

    empty() == true

  2. object_name(object_name && that) noexcept;

    Move constructor.

  3. object_name(object_name const & that);

    Copy constructor.

  4. object_name(scope ns, const char * str);

    Constructor from the object name

    Parameters:

    ns

    The scope of the object name

    str

    The object name, must not be NULL.

  5. object_name(scope ns, std::string const & str);

    Constructor from the object name

    Parameters:

    ns

    The scope of the object name

    str

    The object name

  6. object_name & operator=(object_name && that) noexcept;

    Move assignment

  7. object_name & operator=(object_name const & that);

    Copy assignment

object_name public member functions

  1. bool empty() const noexcept;

    Returns true if the object name is empty

  2. std::size_t size() const noexcept;

    Returns length of the name, in bytes

  3. const char * c_str() const noexcept;

    Returns the name string

  4. void swap(object_name & that) noexcept;

    Swaps the object name with another object name

object_name public static functions

  1. static object_name from_native(const char * str);

    Constructor from the native string.

    Parameters:

    str

    The object name string, must not be NULL. The string format is specific to the operating system.

  2. static object_name from_native(std::string const & str);

    Constructor from the native string.

    Parameters:

    str

    The object name string. The string format is specific to the operating system.

object_name friend functions

  1. friend void swap(object_name & left, object_name & right) noexcept;

    Swaps two object names

  2. friend std::string to_string(object_name const & name);

    Returns string representation of the object name

  3. friend bool operator==(object_name const & left, object_name const & right) noexcept;

    Equality operator

  4. friend bool operator!=(object_name const & left, object_name const & right) noexcept;

    Inequality operator

  5. friend bool operator<(object_name const & left, object_name const & right) noexcept;

    Less operator

  6. friend bool operator>(object_name const & left, object_name const & right) noexcept;

    Greater operator

  7. friend bool operator<=(object_name const & left, object_name const & right) noexcept;

    Less or equal operator

  8. friend bool operator>=(object_name const & left, object_name const & right) noexcept;

    Greater or equal operator

  9. template<typename CharT, typename TraitsT> 
      friend std::basic_ostream< CharT, TraitsT > & 
      operator<<(std::basic_ostream< CharT, TraitsT > & strm, 
                 object_name const & name);

    Stream ouput operator


PrevUpHomeNext