ipcname(2)

NAME

ipcname − associate a name with a call socket or destination descriptor

SYNOPSIS

#include <sys/ns_ipc.h>

void ipcname(

ns_int_t descriptor,
const char *socketname,
ns_int_t nlen,
ns_int_t *result);

DESCRIPTION

ipcname() associates a name with a call socket and adds this information to the local node’s socket registry. The name a process associates with a call socket must be known to its peer process so that the peer process can look up the name with an ipclookup() call. This can be accomplished by hard-coding the name into both processes or by passing the name from one process to another.

The name associated with a call socket can be user-defined or randomly generated by Net IPC, and must be unique to your node (i.e., it cannot be simultaneously associated with two descriptors). For example, if a call to ipcname() assigns the name Liz to a call socket, a subsequent call with Liz results in an error. To ensure that the name being assigned to a call socket is unique, use the random name generating feature of ipcname() (see the nlen parameter below for more information). A call socket can be listed under multiple names.

ipcname() always enters its listings into the local node’s socket registry. ipclookup(), by contrast, can look up socket names at both the local node and at a remote node. Since “long distance” look-ups take longer than local look-ups, it may be helpful to use ipcname() to name a destination descriptor associated with a remotely named call socket. When a process names a destination descriptor, the name of the destination descriptor is placed in the local socket registry (the socket registry at the node where the calling process resides). This allows other processes to look up the name in the local socket registry rather than calling ipclookup() to look up the name in a socket registry at a remote node where the call socket resides.

Using ipcname() to name a destination descriptor is less reliable than looking up the socket name at the remote node because destination descriptors can become outdated. As a precaution, locally stored destination descriptors should be refreshed periodically.

ipcname() cannot be used to name VC sockets.

PARAMETERS

descriptor (input parameter) The descriptor that references the call socket to be named. Can be a call socket descriptor or a destination descriptor.

socketname (input/output parameter) The ASCII-coded name to be associated with the descriptor. Uppercase and lowercase characters are treated as equivalent. Net IPC can also return a randomly-generated name in this parameter (see the nlen parameter).

nlen (input parameter) The length in characters of the socketname parameter. Maximum length is 16 characters. If zero is specified, Net IPC returns a random, eight-byte name in the socketname parameter. The eight-byte length is not returned in the nlen parameter.

result (output parameter) See ERRORS below.

RETURN VALUE

None. Errors are returned in the result parameter.

ERRORS

[NSR_NO_ERROR] The call was successful.

[NSR_CANT_NAME_VC] The descriptor parameter corresponds to a VC socket and naming of VC sockets is not allowed.

[NSR_DESC] The descriptor parameter does not correspond to a Net IPC socket.

[NSR_NLEN] The value specified in the nlen parameter is invalid.

[NSR_DUP_NAME] The specified socketname already exists in the local socket registry.

[NSR_NO_MEMORY] Sufficient system memory is not available to execute this call at this time.

[NSR_BOUNDS_VIO] The output parameter address is invalid.

AUTHOR

ipcname() was developed by HP.

Museum

Related Articles