ConnectClientInfo(), ConnectClientInfo_r()

Updated: April 19, 2023

Get information about a client connection

Synopsis:

#include <sys/neutrino.h>

int ConnectClientInfo( int scoid,
                       struct _client_info * info
                       int ngroups );

int ConnectClientInfo_r( int scoid,
                         struct _client_info * info
                         int ngroups );

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
A pointer to a _client_info structure that the function can fill with information about the client. For more information, see below.
ngroups
The size of the caller's grouplist in the credential part of the _client_info structure, or 0 to query the number of supplementary groups. If you make it smaller than sysconf(_SC_NGROUPS_MAX), you might get information about only a subset of the groups.

Library:

libc

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

Description:

These calls get information about a client connection identified by scoid, and store it in the buffer that info points to.

The ConnectClientInfo() and ConnectClientInfo_r() functions are identical except in the way they indicate errors. See the Returns section for details.

A server uses these functions to determine whether or not a client has permission to access a resource. For example, in a resource manager, it would be called on an open() connection request.

_client_info structure

The _client_info structure has at least the following members:

uint32_t nd
The client's node descriptor, a temporary numeric description of a remote node; ND_LOCAL_NODE (or 0) is the descriptor for the local node. For more information, see the Qnet Networking chapter of the System Architecture guide.
To: Use this function:
Compare two nd objects ND_NODE_CMP()
Convert a nd to text netmgr_ndtostr()
Convert text to a nd netmgr_strtond()
pid_t pid
The client's process ID.
pid_t sid
Used internally by Qnet.
flags
  • _NTO_CI_BITS_64 (QNX Neutrino 7.0 or later) — the sender is using a 64-bit architecture.
  • _NTO_CI_BKGND_PGRP — the client's process group is in the background.
  • _NTO_CI_CHROOT (QNX Neutrino 7.0 or later) — chroot() has been applied to the client process.
  • _NTO_CI_ENDIAN_BIG — the client is on a big-endian machine.
  • _NTO_CI_FULL_GROUPS — indicates that the client information contains the full group list.
  • _NTO_CI_GROUPS_INFO_ONLY — indicates that the ngroups field in the _cred_info structure contains the number of groups, but the grouplist array has not been updated.
  • _NTO_CI_ORPHAN_PGRP — the client's process group has been orphaned.
  • _NTO_CI_SANDBOX (QNX Neutrino 7.0 or later) — the client process has been constrained to a sandbox.
  • _NTO_CI_STOPPED — the client is stopped.
  • _NTO_CI_UNABLE — the client doesn't have the required abilities; see ConnectClientInfoAble(), procmgr_ability(), and procmgr_ability_create().
struct _cred_info cred
A _cred_info structure that describes the user and group ID credentials of the sending process.

The ngroups argument to ConnectClientInfo() indicates the size of the grouplist array in the _cred_info structure. If the group array size is zero, the ngroups member of the _cred_info structure is set to the number of groups available.

Note: The grouplist array in this structure doesn't include the primary group ID (unless it was also added as a supplementary group).

Returns:

The only difference between these functions is the way they indicate errors:

ConnectClientInfo()
If an error occurs, the function returns -1 and sets errno. Any other value returned indicates success.
ConnectClientInfo_r()
EOK is returned on success. This function does NOT set errno. If an error occurs, the function can return any value in the Errors section.

Errors:

EFAULT
A fault occurred when the kernel tried to access the buffers provided.
EINVAL
Process doesn't have a connection scoid.

Classification:

QNX Neutrino

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