procmgr_session(), procmgr_session_ext()

Updated: April 19, 2023

Provide process manager session support

Synopsis:

#include <sys/procmgr.h>

int procmgr_session( uint32_t nd,
                     pid_t sid,
                     int id,
                     unsigned event);

int procmgr_session_ext( uint32_t nd,
                         pid_t sid,
                         int xid,
                         int id,
                         unsigned event);

Arguments:

The interpretation of the arguments depends on the event.

nd
A node descriptor. This must currently be ND_LOCAL_NODE, or you'll get an error of ENOREMOTE.
sid
A session ID or process ID, depending on the event.
xid
(procmgr_session_ext() only) Extra information about the target session, depending on the event. If xid is 0, the argument is ignored.
id
A file descriptor, process group, or signal, depending on the event.
event
The event; one of:
  • PROCMGR_SESSION_TCSETSID
  • PROCMGR_SESSION_SETSID
  • PROCMGR_SESSION_SETPGRP
  • PROCMGR_SESSION_SIGNAL_PID
  • PROCMGR_SESSION_SIGNAL_PGRP
  • PROCMGR_SESSION_SIGNAL_LEADER

For more information, see below.

Library:

libc

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

Description:

The procmgr_session() function provides session support to character device terminal drivers in their resource managers, C library functions, and session management applications. The procmgr_session_ext() function is an extended version that lets you pass extra information for the target session, as described above. Calling procmgr_session() is the same as calling procmgr_session_ext() with an xid of 0.

The arguments that you provide need to match the event; some of these events require certain abilities (see procmgr_ability()) be enabled:

PROCMGR_SESSION_TCSETSID
Used by the tcsetsid() function to set the file descriptor, id, to be the controlling terminal for the session headed by the session leader, sid.
PROCMGR_SESSION_SETSID
Used by the setsid() function to create a new session with the calling process becoming the session leader. Pass zero for both sid and id arguments.

Required ability: PROCMGR_AID_PGRP

PROCMGR_SESSION_SETPGRP
Used by a character device resource manager to change the process group upon the request of a client calling the tcsetpgrp() function. Set the sid argument to the client's current session and the id argument to the new target process group for the client.

Required ability: PROCMGR_AID_SESSION

PROCMGR_SESSION_SIGNAL_PID, PROCMGR_SESSION_SIGNAL_PGRP, PROCMGR_SESSION_SIGNAL_LEADER
Used by a character device resource manager to drop a signal of the type specified as the id argument (generally a terminal/job control signal) on the appropriate member of the session specified by the sid argument.

Required ability: PROCMGR_AID_SESSION

If you call procmgr_session_ext() with an event of PROCMGR_SESSION_SIGNAL_PID, you can pass a thread ID for xid. If xid is greater than 0, and the thread with that ID is blocking the given signal, the function sets errno to EIO.

Returns:

0
Success.
-1
Failure (errno is set).

Classification:

QNX Neutrino

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