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 Net IPC 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.

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, Net IPC 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 Net IPC 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.

[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.

Museum

Related Articles