Series 300 and 800 Only

NAME

ipclookup() − obtains a destination descriptor

SYNOPSIS

#include <sys/ns_ipc.h>

void ipclookup (socketname,nlen,nodename,nodelen,flags,destdesc,protocol,
                 socketkind,result);
char *socketname,*nodename;
ns_int_t nlen,nodelen,*flags,*destdesc,*protocol,*socketkind,*result;

DESCRIPTION

The ipclookup call is used to obtain a destination descriptor for a named call socket.  When supplied with valid socket and node names, it looks up the call socket in the socket registry at the node specified in the nodename parameter and returns a destination descriptor that can be used by subsequent NetIPC calls to locate the call socket.  When used in an ipcconnect call, for example, a destination descriptor can provide the information necessary to direct a connection request to the proper node and call socket and thus initiate a connection. 
 
Compared to the telephone system, invoking ipclookup is analogous to calling directory assistance: the NetIPC process "calls the operator" ( ipclookup ) and gives him/her a "name" (socketname parameter) and a "location" (nodename parameter).  The node name can be a "city" (node), "state" (domain), and a "country" (organization name), just the "city" and the "state," only the "city," or no location at all.  The omitted parts, or all, of the location will be defaulted.  Once the name is found, the operator returns a "telephone number" (destdesc) to the caller. 
 
When a process attempts to look up a socket name in the appropriate socket registry, the name must be there or an NSR_NAME_NOT_FOUND (code 37) error will be returned to the calling process.  When two processes are running concurrently, it may be difficult to ensure that a socket name is placed in the socket registry prior to being "looked up" by another process.  This problem is referred to as a race condition because the two processes are "racing" to see which one will access the socket registry first.
 
In order to avoid a race situation, the process that calls ipclookup can test for a NSR_NAME_NOT_FOUND (code 37) error in the call’s result parameter.  If this error is returned, the process can try again by entering a loop and repeating the ipclookup call for a specified number of times.  The process should also call sleep to suspend execution for an interval and then repeat the ipclookup call.  (Refer to the HP-UX Reference Manual for more information on sleep(3c). 
 
This routine can be linked into a program by giving the -lnsipc option to cc(1) or ld(1).  ). 

PARAMETERS

socketname (input parameter) The name of the call socket to be "looked up." Upper and lower case characters are not considered distinct. 

nlen (input parameter) The length of the socket name in characters.  Maximum length is 16 characters. 

nodename (input parameter) The ASCII-coded name that that identifies the node where the socket specified in the socketname parameter resides.  Default: You may omit the organization, organization and domain, or all parts of the node name.  When organization or organization and domain are omitted, they will default to the local organization and/or domain.  If the entire parameter is omitted, the node name will default to the local node. 

nodelen (input parameter) The length in bytes of the nodename parameter.  If zero is specified, NetIPC will search the local node’s socket registry.  (See the nodename parameter above for more information.) 

flags (input parameter) This parameter is reserved for future use.  All bits must be clear (not set).  Refer to the NetIPC programmer’s manual for your system for a complete description of this parameter. 

destdesc (output parameter) Destination descriptor.  Refers to the descriptor which indicates the location of the named call socket.  May be used in subsequent NetIPC calls. 

protocol (output parameter) Identifies the protocol module with which the "looked up" socket is associated.  Zero (0) is always returned to this parameter. 

socketkind (output parameter) Identifies the socket’s type.  May be used in an ipccreate call to create a socket of the appropriate type. 

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

RETURNS

None.  Errors are returned in the result parameter. 

AUTHOR

HP. 

SEE ALSO

ipcconnect(2), ipccreate(2), sleep(3c). 

DIAGNOSTICS

[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