bdls_filepermissions

Detailed Description

Enumerate the file-system permission bits used across bdl.

Outline

• Purpose
• Classes
• Description
  • Enumerators
  • Usage
    • Example 1: Composing and Validating Permissions

Purpose

Enumerate the file-system permission bits used across bdl.

Classes

• bdls::FilePermissions: namespace for a std::filesystem::perms-style enum

See also

bdls_filesystemutil, balb_pipecontrolchannel

Description

This component provides a struct, bdls::FilePermissions, that scopes a bit-mask enum, Enum, modelled on std::filesystem::perms [https://en.cppreference.com/w/cpp/filesystem/perms]. The enumerators describe the standard Unix file-system permission bits (owner, group, and others read/write/execute triples, plus the "set uid", "set gid", and sticky bits) with numeric values that match the traditional Unix octal representation. This component also provides two static predicates for validating an int bit mask against the set of defined bits.

This component is intended to be used by other components that accept a permission bit mask as an int argument. Taking an int (rather than the enumeration type) lets callers pass either a familiar octal literal (for example 0666) or a bitwise-OR of bdls::FilePermissions enumerators. The consuming component is expected to validate its argument by calling one of the isValid* predicates.

Enumerators

The Enum values are:

 Enumerator          Value  Meaning
 ----------------- --------  ----------------------------------------------
 k_NONE                  0  No permissions.
 k_OWNER_READ         0400  Owner has read permission.
 k_OWNER_WRITE        0200  Owner has write permission.
 k_OWNER_EXEC         0100  Owner has execute permission.
 k_OWNER_ALL          0700  Owner has read, write, and execute permission.
 k_GROUP_READ         0040  Group has read permission.
 k_GROUP_WRITE        0020  Group has write permission.
 k_GROUP_EXEC         0010  Group has execute permission.
 k_GROUP_ALL          0070  Group has read, write, and execute permission.
 k_OTHERS_READ        0004  Others have read permission.
 k_OTHERS_WRITE       0002  Others have write permission.
 k_OTHERS_EXEC        0001  Others have execute permission.
 k_OTHERS_ALL         0007  Others have read, write, and execute perm.
 k_ALL                0777  Owner, group, and others all have full perms.
 k_SET_UID           04000  Set-user-ID on execution.
 k_SET_GID           02000  Set-group-ID on execution.
 k_STICKY_BIT        01000  Sticky bit.
 k_MASK              07777  Union of every defined bit.

Usage

This section illustrates intended use of this component.

Example 1: Composing and Validating Permissions

A component (for instance, balb::PipeControlChannel) may accept an int permission bit mask. A caller can build such a mask by OR-ing together enumerators of bdls::FilePermissions. Suppose we want a file readable and writable by the owner and readable by the owning group:

 int perms = bdls::FilePermissions::k_OWNER_READ  |
             bdls::FilePermissions::k_OWNER_WRITE |
             bdls::FilePermissions::k_GROUP_READ;
 assert(0640 == perms);

The consuming component may validate the mask before using it. To reject a mask that contains any bit outside the traditional 9-bit rwx set (that is, to reject k_SET_UID, k_SET_GID, and k_STICKY_BIT), use isValidBaseBits:

 assert( bdls::FilePermissions::isValidBaseBits(0640));
 assert(!bdls::FilePermissions::isValidBaseBits(0640 |
                               bdls::FilePermissions::k_SET_UID));

To accept any combination of defined bits, use isValid:

 assert( bdls::FilePermissions::isValid(0640 |
                               bdls::FilePermissions::k_SET_UID));
 assert(!bdls::FilePermissions::isValid(1 << 15));