ConnectClientInfoAble()

Updated: April 19, 2023

Get extended information about a client connection, including abilities

Synopsis:

#include <sys/neutrino.h>

struct _client_able {
    unsigned ability;
    unsigned flags;
    uint64_t range_lo;
    uint64_t range_hi;
};

int ConnectClientInfoAble( int scoid,
                           struct _client_info **info_pp,
                           const int flags,
                           struct _client_able abilities[],
                           const int nable );

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. For more information, see ConnectClientInfoExt(). 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; there should only be 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 gets information about a client connection identified by scoid, 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().

In QNX Neutrino 7.0 or later, 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
The process doesn't have a connection scoid.
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 Neutrino

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes