Table of Contents

Name

linx_open - Create a LINX endpoint and give it a huntname.

Synopsis

#include <linx_types.h>
#include <linx.h>

LINX *linx_open(const char *name, uint32_t options, void *arg);

Description

A process uses linx_open() to create a LINX endpoint and give it a huntname. The call returns a handle to the LINX endpoint, to be used in subsequent LINX API calls. The handle is a pointer to an opaque structure, reciding in user space, with internal LINX data, e.g. a socket descriptor for underlying communication and pointers to kernel data. As part of the linx_open(3) call, any pending hunts for a huntname matching name are resolved, whether it is a local hunt or a hunt from any node connected via LINX.

name is the local part of the huntname to find this LINX endpoint. It is a null-terminated string, which in Linux may be of any length, but there may be restrictions due to other implementations, when communicating with other systems. name does not need to be unique in the system, but if two LINX endpoints have the same name, it is not specified which one is resolved when a linx_hunt(3) call is made that matches the name. From another LINX endpoints, use linx_hunt() with the huntname, followed by linx_receive() and linx_sender(), to get the binary identifier (spid) to be used to communicate with this LINX endpoint. The local LINX binary identifier (spid) for this endpoint can be fetched with linx_get_spid "()" but is usually not needed by the owner process.

options and arg are provided to facilitate future extensions and shall currently be set to 0 resp. NULL.

A LINX endpoint is closed (and its resources are freed) when it is closed by linx_close(3) or when the calling process exits.
If the process, owning the LINX endpoint, fork(2) , either the parent or the child __must__ close the LINX handle with linx_close(3) . This is because only one process may use a LINX endpoint and after a fork, both instances will have copies of the LINX handle. In any case the LINX endpoint will not be closed unless closed by both parent and child.

It is possible to retrieve the underlying socket descriptor from a LINX endpoint, with linx_get_descriptor(3) for use if needed, e.g. when an application wants to wait for state changes in multiple sockets.

Return Value

The linx_open() function returns a LINX handle, which is a pointer to an opaque LINX endpoint structure. If linx_open() fails, NULL is returned and errno is set.

Errors

EINVAL if name is NULL.

ENOBUFS or ENOMEM if there is not enough memory.

EPROTONOSUPPORT or EAFNOSUPPORT if linx(7) is not supported by the system.

ENFILE Not enough kernel memory to allocate a new LINX endpoint structure.

EMFILE Process file table overflow.

EACCES Permisson to create a LINX endpoint is denied.

Bugs/Limitations

None.

See Also

linx(7) , linx_close(3) , linx_hunt(3) , linx_get_descriptor(3) , linx_receive(3) , linx_send(3) , linx_sender(3) , fork(2)

Author

Enea LINX team

Copyright

Copyright (c) 2006-2007, Enea Software AB All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of Enea Software AB nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Table of Contents