Table of Contents

Name

linx_attach() - Attach to and supervise a LINX endpoint
linx_detach() - Detach from an attached LINX endpoint

Synopsis

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

LINX_OSATTREF linx_attach(LINX *linx, union LINX_SIGNAL **sig, LINX_SPID spid);

int linx_detach(LINX *linx, LINX_OSATTREF *attref);

Description

linx_attach() is used to supervise another LINX endpoint. When the other endpoint is closed (or an intermediate connection is closed), an attach signal will be sent back to the requesting LINX endpoint, linx, as a death notification. If a signal buffer is provided, sig is not NULL, this signal buffer is used. Otherwise a default signal with signal number LINX_OS_ATTACH_SIG will be created. The linx_attach() call consumes the signal buffer, transferring the buffer ownership, and sets the sig pointer to LINX_NIL. The buffer is consumed also if an error occurs.

linx_detach() is used to detach from an attached LINX endpoint. This is not allowed (errno EINVAL) if the attach signal already has been received from the supervised LINX endpoint. The attref pointer is set to LINX_ILLEGAL_ATTREF by the call, to ensure it will not be used again.

linx is the handle to the LINX endpoint

spid is the identifier of the other LINX endpoint that linx shall attach to.

sig is either NULL or a signal buffer that the user wants to use instead of the default signal LINX_OS_ATTACH_SIG.

attref is the LINX_OSATTREF attach reference, previously obtained from linx_attach().

If linx is not a valid LINX endpoint, i.e. created with linx_open(3) then abort(3) is called.

Return Value

linx_attach() returns an attach reference (LINX_OSATTREF) when successful. This attach reference can be used to cancel the attachment (detach) after the attachment is done. linx_detach() returns 0 on success.

On failure, linx_attach() returns LINX_ILLEGAL_ATTREF and linx_detach() returns -1. errno will in both calls be set.

Errors

EINVAL if, where applicable, sig, spid or attref are invalid.

EBADF, ENOTSOCK if the underlying LINX endpoint structure contains an invalid descriptor, or a descriptor which is not a socket descriptor.

Bugs/Limitations

None.

Example

In this example the server attaches to the client and tells the client to exit and waits for the attach signal. 


Server:
#include <linx.h>
#define CLIENT_DONE 0x1234
int
main (int argc, char *argv[]) 
{
  LINX *linx;
  LINX_SPID client;
  union LINX_SIGNAL *sig;
  /* Create a LINX endpoint with huntname "attacher" */
  linx = linx_open("attacher", NULL, 0);
  /* Hunt for the client */
  linx_hunt(linx, "client", NULL);
  /* Receive hunt signal */
  linx_receive(linx, &sig, LINX_OS_HUNT_SIG);
  /* Retrive the clients spid */
  client = linx_sender(linx, &sig)
  /* Free the hunt signal */
  linx_free_buf(linx, &sig);
  /* Attach to the client */
  linx_attach(linx, client, NULL);
  /* Create "done" signal */
  sig = linx_alloc (linx, sizeof(LINX), CLIENT_DONE);
  /* Send "done" signal to client */
  linx_send(linx, &sig, client);
  /* Wait for the attach signal */
  linx_receive(linx, &sig, LINX_OS_ATTACH_SIG);
  /* Close the LINX endpoint */
  linx_close(linx);
  return 0;
}
Client:
#include <linx.h>
int
main (int argc, char *argv[])
{
  LINX *linx;
  union LINX_SIGNAL *sig;
  
  /* Open a LINX endpoint with huntname "client" */
  linx = linx_open("client", NULL, 0);
  /* Wait for server to send "done" signal */
  linx_receive(linx, &sig, CLIENT_DONE);
  /* Close the LINX endpoint - this will trigger the attach */
  linx_close(linx);
  return 0;
}

See Also

linx(7) , linx_attach(3) , linx_close(3) , linx_detach(3) , linx_hunt(3) , linx_send(3)

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