HPUX ipclookup[2]
ipclookup(2) ipclookup(2)
NAME
ipclookup - obtain a NetIPC destination descriptor
SYNOPSIS
#include <sys/ns_ipc.h>
void ipclookup(
const char *socketname,
ns_int_t nlen,
const char *nodename,
ns_int_t nodelen,
ns_int_t *flags,
ns_int_t *destdesc,
ns_int_t *protocol,
ns_int_t *socketkind,
ns_int_t *result);
DESCRIPTION
ipclookup() is used to obtain a destination descriptor for a named
call socket. When supplied with valid socket and node names,
ipclookup() 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. A destination descriptor is required by the ipcconnect()
call to provide the information necessary to direct a connection
request to the proper node and call socket and thus initiate a
connection.
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 error
is 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 accesses the socket
registry first.
In order to avoid a race situation, the process that calls ipclookup()
can test for a NSR_NAME_NOT_FOUND 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 (see sleep(3C), then repeat the ipclookup()
call.
Parameters
socketname (input parameter) The name of the call socket to
be ``looked up''. Uppercase and lowercase
characters are treated as equivalent.
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
ipclookup(2) ipclookup(2)
nlen (input parameter) The length of the socketname
parameter 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:
organization, organization and domain, or all
parts of the node name can be omitted. When
organization or organization and domain are
omitted, they default to the local organization
and/or domain. If the entire parameter is
omitted, the node name defaults to the local node.
nodelen (input parameter) The length in bytes of the
nodename parameter. If zero is specified, NetIPC
searches the local node's socket registry (see
nodename parameter above for more information).
flags (input parameter) This parameter is reserved for
future use. All bits must be clear (not set).
destdesc (output parameter) Destination descriptor. Refers
to the descriptor that indicates the location of
the named call socket. Can be used in subsequent
NetIPC calls.
protocol (output parameter) This parameter is reserved for
future use. Zero (0) is always returned in this
parameter.
socketkind (output parameter) Identifies the socket's type.
Can be used in an ipccreate() call to create a
socket of the appropriate type.
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_BOUNDS_VIO] A parameter address is invalid.
[NSR_FLAGS] The value in the flags parameter in
invalid.
[NSR_PROTOCOL] The protocol of the socket specified by
socketname is not supported by the local
system.
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
ipclookup(2) ipclookup(2)
[NSR_NLEN] The value in the nodelen parameter is
not valid.
[NSR_NODE_NAME_SYNTAX] The string pointed to by nodename is
invalid.
[NSR_NO_NODE] nodename is unknown to the local host.
[NSR_NO_MEMORY] Sufficient system memory is not
available to execute this call at this
time.
[NSR_PATH_REPORT] The path report could not be
interpreted.
[NSR_NAME_NOT_FOUND] The specified socketname was not found
in the socket registry.
[NSR_CANT_CONTACT_SERVER] The ipclookup() request could not be
sent to the remote socket registry
server.
[NSR_NO_REG_RESPONSE] No response was received from the remote
socket registry server.
[NSR_VERSION] The reply from the remote socket
registry indicates a version error
occurred.
[NSR_BAD_REG_MSG] A corrupt reply message was received
from the remote socket registry server.
[NSR_NO_FILE_AVAIL] No file table entries are available.
[NSR_NO_DESC_AVAIL] The process exceeded the system-defined
number of file and socket descriptors
that can be open at a time (see
getrlimit(2)).
AUTHOR
ipclookup() was developed by HP.
SEE ALSO
getrlimit(2), ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2),
ipcgetnodename(2), ipcname(2), ipcnamerase(2), ipcrecv(2),
ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2),
ipcshutdown(2), addopt(3N), initopt(3N), ipcerrmsg(3N),
optoverhead(3N), readopt(3N), sleep(3C).
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992