procmgr_ability

Synopsis:

#include <sys/procmgr.h>

int procmgr_ability_create( const char *name,
                            unsigned flags );

Arguments:

name

The name of the ability. The name should not match the name of a static ability (e.g., "chroot") as this will make it unusable in security policies. Instead, by convention, the name should consist of a service identifier followed by a capability identifier (e.g., "hw_ctrlr_xyz/reset_device"). The maximum length is 127 characters (PROCMGR_ABILITY_NAME_MAX).

flags

Flags that apply to the new ability; a bitwise OR of zero or more of the following:

PROCMGR_ADN_ROOT — the ability applies to processes that have an effective user ID of 0.
PROCMGR_ADN_NONROOT — the ability applies to processes that have an effective user ID other than 0.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The procmgr_ability_create() function creates a process-manager ability. A server can use this function to create the ability, and clients can use procmgr_ability_lookup() to look it up. The name argument is a string that uniquely identifies the ability, and the flags specify which privilege domains have the ability by default.

Note:

To create an ability, your process must have the able_create (PROCMGR_AID_ABLE_CREATE) ability enabled. For more information, see procmgr_ability().
Calling procmgr_ability_create() for an ability after the initial call that creates the ability does not change its permissions, and what's returned depends on the subsequent call's flags value:
- If flags does not specify a privilege domain that was included when the ability was created, an error is returned.
  For example, if an ability is created with the flags value PROCMGR_ADN_NONROOT, a subsequent call to create the same ability with a flags value that does not include PROCMGR_ADN_NONROOT returns an error.
- In all other cases, procmgr_ability_create() returns the requested ability ID but does not change permissions (equivalent to calling procmgr_ability_lookup()).
  For example, if an ability is created with the flags value PROCMGR_ADN_ROOT, a subsequent call to create the same ability with a flags value of both PROCMGR_ADN_ROOT and PROCMGR_ADN_NONROOT is successful. It returns the ability ID, but does not add PROCMGR_ADN_NONROOT as a default privilege domain.
There's no requirement for a call to procmgr_ability_create() to precede calls to procmgr_ability_lookup(). This avoids forcing any specific ordering of process initialization.

Returns:

A numeric ability identifier, which can then be used in a call to procmgr_ability() or to verify the abilities of a client, or a negative errno value if an error occurred.

Errors:

EEXIST: The privilege domains that were set for the ability when it was created include a domain (PROCMGR_ADN_ROOT or PROCMGR_ADN_NONROOT) that is not present in the current call.
EINVAL: The flags parameter is invalid.
ENOSPC: The maximum ability ID (65534) has been reached.
EPERM: The ability does not exist, or procmgr_ability_create() has not been called for the ability and the calling process does not have the able_create ability.

Classification:

QNX OS


Safety:
Cancellation point	No
Signal handler	Yes
Thread	Yes