ConnectAttach(), ConnectAttach_r()

Updated: October 26, 2022

Establish a connection between a process and a channel

Synopsis:

#include <sys/neutrino.h>
#include <sys/netmgr.h>

int ConnectAttach( uint32_t nd,
                   pid_t pid,
                   int chid,
                   unsigned index,
                   int flags );

int ConnectAttach_r( uint32_t nd,
                     pid_t pid,
                     int chid,
                     unsigned index,
                     int flags );

Arguments:

nd
The node descriptor of the node (e.g., ND_LOCAL_NODE for the local node) on which the process that owns the channel is running; see Node descriptors,” below.
pid
The process ID of the owner of the channel. If pid is zero, the calling process is assumed.
chid
The channel ID, returned by ChannelCreate(), of the channel to connect to the process.
index
If _NTO_SIDE_CHANNEL is not set, the lowest acceptable connection ID. The ID returned by the function will then be a file descriptor greater than or equal to this value. If _NTO_SIDE_CHANNEL is set, the connection is created as a side channel, meaning the ID returned is from a different space than file descriptors. In this case, any other bits in index are ignored.
Note:

Having a connection ID in the file descriptor range can lead to unexpected behavior. Therefore, you should pass in _NTO_SIDE_CHANNEL for index when you create a connection. The C library creates connections at various times without _NTO_SIDE_CHANNEL (e.g., during open()); however, it's unlikely that any applications would want to call it this way.

Once the ID is created, there's no difference in the use of the messaging primitives on it.

flags
Flags that affect the connection; a bitwise OR of zero or more of the following:
  • _NTO_COF_CLOEXEC — close the connection when the calling process calls an exec*() function to start a new process.
  • _NTO_COF_INSECURE (QNX Neutrino 6.6 or later) — mark the connection as insecure. The kernel sets this flag on a connection if the client program replaces its process image (e.g., by calling exec*()) with a setuid or setgid binary. If this flag is set on a connection, calls to MsgDeliverEvent() with an event type of SIGEV_MEMORY or SIGEV_THREAD fail with an error of EACCES.

    In QNX Neutrino 7.0 and later, the server or client can set this flag if it doesn't trust the program at the other end of the connection, but only the kernel can clear it. Currently the flag stays set until the connection is detached.

  • _NTO_COF_NOEVENT (QNX Neutrino 7.0 or later) — prevent the server from sending sigevents over the channel to the client.
  • _NTO_COF_REG_EVENTS (QNX Neutrino 7.0.1 or later) — require that the connection use only registered events; reject the delivery of any sigevents that weren't registered as secure events with MsgRegisterEvent().
  • _NTO_COF_UNREG_EVENTS (QNX Neutrino 7.1 or later) — override the OS requirement that all sigevents be registered, allowing this connection to use registered and unregistered events.

    You can use procnto's -U option to allow all processes to use registered and unregistered events; _NTO_COF_UNREG_EVENTS lets you do this for a specific connection.

    Note: Both _NTO_COF_UNREG_EVENTS and procnto's -U option are temporary measures that weaken security. You should use them only while updating your code to use registered events.

Library:

libc

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

Description:

The ConnectAttach() and ConnectAttach_r() kernel calls establish a connection between the calling process and the channel specified by chid owned by the process specified by pid on the node specified by nd. Any function that passes a node descriptor can use either the value 0 or the constant ND_LOCAL_NODE to refer to the local node.

These functions are identical except in the way they indicate errors. See the Returns section for details.

Note: If a process wants other processes to communicate with it, it typically will register a name with name_attach() or resmgr_attach() to create a channel and associate a name with it, and the sender process uses name_open() or one of open() or open_ext() to locate that name and create a connection to it.

The return value is a connection ID, which is a small int representing the connection. The system returns the first available connection ID starting at the value specified by the index argument. Any thread in the calling process can use the MsgSend*() or MsgSendv*() functions to send messages or MsgSendPulse() to send pulses over the connection. The connection ID is used directly as a POSIX file descriptor (fd) when communicating with I/O Resource managers such as a filesystem manager.

We recommend that you OR _NTO_SIDE_CHANNEL into index, to create the connection as a side channel. In this case, the index argument is ignored, and the connection ID returned is the first available index in the _NTO_SIDE_CHANNEL space, which is different than the file descriptor space.

If you don't OR _NTO_SIDE_CHANNEL into index, this behavior might result:

If a client process creates multiple connections to the same channel, the system maintains a link count and shares internal kernel object resources for efficiency. The client should avoid using different flags (flags) when making multiple connections, or unexpected behavior could result.

Connections are owned by the process and may be used simultaneously by any thread in the process. You can detach a connection by calling ConnectDetach().

Note: Connections and connection IDs persist until you call ConnectDetach(), even if the other process dies.

The connection is strictly local (i.e., it doesn't resolve across the network) and is resolved on the first use of the connection ID.

Blocking states

These calls don't block.

Node descriptors

The nd (node descriptor) is a temporary numeric description of a remote 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()

Returns:

A connection ID (coid) that's used by the message primitives. If an error occurs:

Errors:

EAGAIN
Insufficent resources.
EINVAL
One of the following:
  • The value of index is outside the range of valid connection IDs. This error applies only to file descriptors, not side channels (there's no limit on the range for side channels).
  • The combination of bits in the flags argument is invalid.
EMFILE
One of the following occurred:
  • The process has no unused file descriptors.
  • The number of connections already owned by the process is greater than or equal to the limit specified for RLIMIT_NOCONN_NP (see setrlimit()).
  • No file descriptors greater than or equal to index are available.
If you aren't creating a side channel, the following also applies:
  • There was no acceptable connection ID less than RLIMIT_NOFILE.
ENOREMOTE
The node indicated by nd doesn't exist.
ENXIO
The process indicated by pid is no longer valid. It's going away, has core dumped, or become a zombie.
EPERM
The process that created the channel used the _NTO_CHF_PRIVATE flag to mark it as being private (see ChannelCreate() for more information), or the process doesn't have the necessary ability to connect (PROCMGR_AID_CHANNEL_CONNECT).
ESRCH
The process indicated by pid, or the channel indicated by chid, doesn't exist.

Classification:

QNX Neutrino

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