LinuxCNC Documentation

SYNOPSIS

#include <hal.h>

typedef int (*hal_query_cb)(hal_query_t *query, void *arg);

int hal_get_s(hal_query_t *query, hal_query_cb callback, void *arg);
int hal_getref_s(hal_query_t *query);

ARGUMENTS

query

The query structure containing the data to search for and returns all data found.

callback

The callback function to invoke when the data has been found or NULL if no callback is required.

arg

A user defined pointer to a user defined data structure. The arg pointer is passed verbatim to the callback function.

DESCRIPTION

The hal_get_s() function will retrieve the value of a signal, including its data reference. The query structure should be set to zero before the call, except for the fields noted here.

The query.name must be set to the name of the signal you want to get.

You can further limit the search by setting query.sig.type to the HAL type you want to find. If the signal is found, but has a different type, then -EEXIST is returned.

The callback is called with all fields set appropriately, including value and data reference. You must to demultiplex the query.sig.value according to the query.sig.type field.

The hal_getref_s() function will only retrieve the data reference of the signal. No callback is used and no value is retrieved. All query fields, expect query.sig.value are set upon return. The hal_getref_s() function is preferable if you do not need the actual signal, like testing for existence.

If found, both hal_get_s() and hal_getref_s() set the query.name field to the actual live signal name. Also, both functions set query.qtype to HAL_QTYPE_SIGNAL.

RETURN VALUE

Both functions return zero (0) on success. The return value of the callback is returned if it got called. A negative errno code is returned if any problem is detected:

-EFAULT

The shared memory was not mapped.
-EINVAL

An invalid argument was passed.
-ENOENT

The signal does not exist.
-EEXIST

The signal exists but is of different type (hal_get_s() only).
-EIO

The internal data pointer is missing.
-EBADF

An invalid type was detected.

EXAMPLES

int have_s(const char *signame)
{
    hal_query_t query = {};
    query.name = signame;
    int rv = hal_getref_s(&query);

    if(-ENOENT == rv)
        return 0;  // Does not exist

    if(0 == rv)
        return 1;  // Does exist

    return rv;     // An error occured
}
int print_s_val(const char *signame)
{
    hal_query_t query = {};
    query.name = signame;

    int rv = hal_get_s(&query, NULL, NULL);

    if(-ENOENT == rv) {
        printf("%s: not found\n", signame);
    } else if(0 != rv) {
        return rv;  // Let upstream handle any errors
    }

    printf("%s (%s): ", signame, query.sig.writers ? "driven" : "not driven");

    switch(query.sig.type) {
    case HAL_BOOL: printf("%s\n",  query.sig.value.b ? "true" : "false"); break;
    case HAL_REAL: printf("%f\n",  query.sig.value.r); break;
    case HAL_SINT: printf("%ld\n", query.sig.value.s); break;
    case HAL_UINT: printf("%lu\n", query.sig.value.u); break;
    default: printf("unsupported value type %d\n", (int)query.sig.type); break;
    }

    return 0;
}

SEE ALSO

hal_query_t(3), hal_set_s(3)