ConnectAttach(), ConnectAttach_r()

Establish a connection between a process and a channel

Synopsis:

#include <sys/neutrino.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 );

Library:

libc

Description:

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

These kernel calls establish a connection between the calling process and a channel (created by ChannelCreate()) 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. If pid is zero the calling process is assumed.

If flags contains _NTO_COF_CLOEXEC, the connection is closed when your process calls an exec*() function to start a new process.

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 either MsgSendv() 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 IO Resource managers such as a filesystem manager.

Connections being treated as file descriptors can lead to unexpected behaviour. Therefore, you should OR _NTO_SIDE_CHANNEL into index when you create a connection. This results in the connection ID being returned from a different space than file descriptors. The ID is greater than any valid file descriptor. Once created there's no difference in the use of the messaging primitives on this ID. 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. The following explains some behaviour that results if _NTO_SIDE_CHANNEL is left off: If file descriptor 0 is in use and file descriptor 1 isn't in use, when you call ConnectAttach() with 0 specified for index, a connection id of 1 is returned. Note that file descriptor 1 (i.e. connection id 1) is used as stdout which is what printf() writes to. So if your process makes any calls to printf(), NULL terminated character strings will be sent to the channel that you've connected to! Similar situations can happen with connection ids 0 (stdin) and 2 (stderr). Depending on how a child process is created, it may inherit the parent's file descriptors. Since connections are treated like file descriptors, a connection created by the parent without _NTO_SIDE_CHANNEL in index and without _NTO_COF_CLOEXEC in flags, causes a child process to inherit that connection during process creation. This inheritance is done during process creation by duplicating file descriptors. During duplication, an _IO_DUP message (the first 2 bytes are 0x115) is sent to the receiver on the other side of the connection. Note that the receiver won't be expecting this message!

If a process creates multiple connections to the same channel, the system maintains a link count and shares internal kernel object resources for efficiency.

Connections are owned by the process and may be used simultaneously by any thread in the process. A connection is detached by calling ConnectDetach(). If any threads are blocked on the channel (via MsgSendv()) at the time the connection is detached the send fails and returns with an error.

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.

uint32_t nd

The nd (node descriptor) is a magic cookie.

Returns:

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

ConnectAttach()

A connection ID that's used by the message primitives. If an error occurs, -1 is returned and errno is set.

ConnectAttach_r()

A connection ID that's used by the message primitives. This function does NOT set errno. If an error occurs, the negative of a value from the Errors section is returned.

Errors:

EAGAIN

All kernel connection objects are in use.

ESRCH

The node indicated by nd, the process indicated by pid, or the channel indicated by chid doesn't exist.

Classification:

QNX 6

See also:

ChannelCreate(), ConnectDetach(), execl(), execle(), execlp(), execlpe(), execv(), execve(), execvp(), execvpe(), MsgSendPulse(), MsgSendv(), netmgr_remote_nd()