HPUX ipcname[2]
ipcname(2) 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 NetIPC, 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
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
ipcname(2) ipcname(2)
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.
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 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 NetIPC 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.
SEE ALSO
ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2),
ipcgetnodename(2), ipclookup(2), ipcnamerase(2), ipcrecv(2),
ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2),
ipcshutdown(2), addopt(3N), initopt(3N), ipcerrmsg(3N),
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
ipcname(2) ipcname(2)
optoverhead(3N), readopt(3N).
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992