ConnectClientInfoAble()

Arguments:

scoid

A server connection ID that identifies the client process that you want to get information about, or -1 to get information about the calling process. This client is typically a process that's made a connection to the server to try to access a resource. You can get it from the _msg_info argument to MsgReceivev() or MsgInfo().

info_pp

The address of a location where the function can store a pointer to a _client_info structure that the function can fill with information about the client, or NULL if the _client_info structure is not required. For more information, see ConnectClientInfoExt(). If this argument is not NULL, the ConnectClientInfoAble() function sets the _NTO_CI_UNABLE bit in the flags member if the client doesn't have all the indicated abilities.

flags

Zero or more of the following:

• _NTO_CLIENTINFO_GETGROUPS — get the supplementary group IDs
• _NTO_CLIENTINFO_GETTYPEID — results in the type identifier being returned immediately after the last returned supplementary group ID

abilities

An array of struct _client_able structures that specifies the abilities that the client must have; see below.

nable

The number of entries in the abilities array. Although QNX OS does not limit the number of entries, when best practices are applied there is usually only one (see the Description below).

Library:

libc

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

Description:

This call checks the requested abilities of the client identified by scoid, and if the info_pp is not NULL, also gets information about that client connection, allocates a buffer, stores the information in the buffer, and stores a pointer to the buffer in the location that info_pp points to. Use ClientInfoExtFree() to free this buffer.

A server uses this function to determine whether or not a client has the required abilities; see procmgr_ability(), and procmgr_ability_create(). The server should test if the client has a specific ability only when it receives a request to perform a task that requires this ability, and not any sooner. Ability tests result in system trace events being emitted. An ability test done in advance of when it's required can give an erroneous indication of a process's need for an ability. This can interfere with tools for generating security policies and result in system integrators granting abilities to processes that don't need them. If you test abilities only when they're really required, you'll find there almost always will be only one that's applicable at any point in time.

The ConnectClientInfoAble() function is a specialized version of ConnectClientInfo().

_client_able structure

The _client_able structure has at least the following members:

ability

The numeric identifier for the ability; either a PROCMGR_AID_* value (see procmgr_ability()), or an ability that the server created by calling procmgr_ability_create().

If the ID is a temporary one (i.e., it has PROCMGR_AID_UNCREATED ORed into it), ConnectClientInfoAble() looks it up again. If the ability has been created, ConnectClientInfoAble() replaces the temporary ID with the permanent one; otherwise it marks the ability as denied.

flags

The function sets this member to 1 if the client has the specified ability, or 0 if it doesn't.

range_lo

The lower limit on the range of the ability.

range_hi

The upper limit on the range of the ability.

Set the ability, range_lo, and range_hi members before calling ConnectClientInfoAble(); this function sets the flags member.

Returns:

0, or -1 if an error occurred (errno is set).

Errors:

EFAULT

A fault occurred when the kernel tried to access the buffers provided.

EINVAL

One of the following occured:

• The process doesn't have a connection scoid.
• Either _NTO_CLIENTINFO_GETGROUPS or _NTO_CLIENTINFO_GETTYPEID was set in flags and info_pp was NULL.

ENOMEM

The function couldn't allocate the memory for the _client_info structure.

E2BIG

The nable parameter exceeds the maximum number of entries in the abilities array.

Classification:

QNX OS