NAME

flc_attach, flc_detach, flc_open, flc_read, flc_write -
FLIGHTLAB communications library

SYNOPSIS

#include "flcomms.h"

flc_attach(id,flags);

FLC_HANDLE handle = flc_open(name, size, magic, flags);

flc_read(handle, dst, size);
flc_write(handle, src, size);

flc_detach();

ARGUMENTS

DESCRIPTION

flc_attach(NULL, 0) Attaches to the main communications block. The id and flags parameters are for potential future enhancements; for now they should be NULL and 0, respectively. Returns 1 if OK, 0 on error.

flc_detach() Releases all data blocks and detaches from the master communications block.

flc_open Returns a handle to a data block. name should be the name of a Scope variable list without the leading `@' sign), or any other user-defined name. size should be the size in bytes of the data area. magic may be used for additional consistency checks: setting magic=0 disables the consistency checks.

flags should be a bitwise-OR combination of the following:

FLC_MODE_READ

Read-only access to the data block

FLC_MODE_WRITE

Write access to the data block. At most one process may have write access.

FLC_TYPE_INT

FLC_TYPE_LONG

FLC_TYPE_FLOAT

FLC_TYPE_DOUBLE

Used for homogenous data blocks. The data block must be an array of the indicated type or a C structure all of whose members are of the indicated type.

FLC_TYPE_MIXED

Used for other structure types.

The type flag is a hint to the FLCOMMS network monitor. Homogeneous data blocks will be serialized in a common format before transmission across the network, to enable communication between hosts with different byte orders and floating point formats. FLC_TYPE_MIXED data blocks will be transmitted without any serialization, so they may only be shared amongst hosts with the same architecture.

Note that Scope always uses FLC_TYPE_DOUBLE for variable lists.

flc_read and flc_write copy data from and to the shared memory block indicated by handle.

DIAGNOSTICS

flc_attach() returns 0 on error, 1 if OK.

flc_read() returns a pointer to an internal buffer holding a copy of the contents of the data block if successful, NULL otherwise.

flc_write() returns 1 on success, -1 on error.

In the case of an error, errno may be set to one of the following:

EINVAL

There is a size or magic number mismatch

EAGAIN

A call to flc_read timed out. This can happen if another process is currently writing to the data block.

ETIME

flc_attach may time out if the IPC resources have been incompletely initialized (or incompletely destroyed) and the creating process has crashed. In this case the best solution is to forcibly remove the shared memory segment and semaphore using flcomms -r and try again.

ENOSPC

E2BIG

One of the size limitations (see below) has been exceeded

EBUSY

An attempt was made to attach a data block in write mode while another process already has write access

EPERM

An attempt to write to a data block which was opened read-only

BUGS AND LIMITATIONS

• Maximum size of any individual data block: 2048 bytes
• Maximum number of data blocks: 126
• Maximum total size of the communications block: 64K

Note that the actual limits are in practice less than these upper bounds, due to memory allocation policies.

The error-reporting mechanism(s) leave much to be desired.

SEE ALSO

flcomms(1), netflc(3), ATTACH, APCTL, $FL_DIR/examples/flcomms