Series 300 and 800 Only

NAME

ipcname() − associates a name with a call socket or destination call socket

SYNOPSIS

#include <sys/ns_ipc.h>

void ipcname (descriptor,socketname,nlen,result);
ns_int_t descriptor,nlen,*result;
char *socketname;

DESCRIPTION

ipcname associates a name with a call socket and adds this information to the local node’s socket registry.  Like a telephone directory that associates names with telephone numbers, the socket registry associates names with protocol addresses.  NetIPC must be provided with these addresses before it can establish a connection to the corresponding call socket. 
 
The name a process associates with a call socket must be known to its peer process so that the peer process may look up the name with an ipclookup call.  This may 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 NetIPC and must be unique to your node (i.e., it cannot be simultaneously associated with two descriptors.) For example, if a call socket is assigned the name "Liz" with a call to ipcname, a subsequent call with "Liz" will result in an error.  You can ensure that the name you assign to a call socket is unique by using the random name generating feature of ipcname.  (See the dlen parameter below for more information.)  A name can be reused only if it not currently being used, but a call socket may be listed under multiple names. 
 
Under most circumstances, ipcname should be called with a name and the call socket descriptor that refers to a call socket owned by the calling process.  If the call completes sucessfully, the call socket will be listed in the socket registry at the local node.  ipclookup can be called by another process to "look up" the socket name in the local node’s socket registry. 
 
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.  Because "long distance" look-ups take longer than local look-ups, it may be helpful to use ipcname to name destination call sockets.  When a process names a destination call socket, the name of the call socket 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. 
 
Another advantage of naming destination call sockets is gaining the ability to redirect requests. Consider an application with four processes at four different nodes: a "client" process, a "director" process, and two "service" processes, one at node A and one at node B. (The two service processes can provide some service to the client process.) The director process can call ipclookup with call sockets owned by the service processes, name the resulting destination descriptors, and then use these names to transparently direct the client process to the service process at node A or node B.  For example, if the client process directs its ipclookup to the director process and node A goes down, the director process can call ipclookup with a call socket owned by node B’s service process, name the destination descriptor, and direct the client process to node B. 
 
Using ipcname to name a destination call socket is less reliable than looking up the socket name at the remote node because destination descriptors, like telephone numbers, can become outdated.  As a precaution, you should periodically refresh locally stored destination descriptors. 
 
You cannot use ipcname to name VC sockets. 
 
This routine can be linked into a program by giving the -lnsipc option to cc(1) or ld(1). 

PARAMETERS

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

socketname (input/output parameter) The ASCII-coded name to be associated with the descriptor.  Upper and lower case characters are not considered distinct.  NetIPC 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, NetIPC will return a random, eight-byte name in the socketname parameter.  The eight-byte length is not returned in the nlen parameter. 

result (output parameter) The error code returned; zero or NSR_NO_ERROR if no error.  See "Diagnostis" below for more information. 

RETURNS

None.  Errors are returned in the result parameter. 

AUTHOR

Hewlett Packard Company. 

SEE ALSO

ipclookup(2), ipcnamerase(2). 

DIAGNOSITCS

[NSR_NO_ERROR] The call was successful. 

[NSR_xxxx] Refer to the errors listed in the NetIPC programmer’s manual for your system. 

Hewlett-Packard Company  —  May 11, 2021