iocsh.h

C and C++ definitions of functions for IOC shell programming.

The iocsh API provides an interface for running commands in the shell of the IOC, as well as registering commands and variables for use in the shell. It consists of 4 functions for the former and 2 functions for the latter.

Command functions:

iocsh()
iocshLoad()
iocshCmd()
iocshRun()

Registration functions:

iocshRegister()
iocshRegisterVariable()

Defines

IOCSH_STATIC_FUNC

IOCSHFUNCDEF_HAS_USAGE

Typedefs

typedef void (*iocshCallFunc)(const iocshArgBuf *argBuf)

This typedef defines a function that is used as the first parameter of iocshRegister().

static void AsynGenericConfigCallFunc (const iocshArgBuf *args)
{
    AsynGenericConfig (args[0].sval, args[1].ival);
}

static void AsynGenericRegister(void)
{
    iocshRegister(&AsynGenericConfigFuncDef, AsynGenericConfigCallFunc);
}

Enums

enum iocshArgType

This typedef lists the values that can be used as argument data types when building the first parameter of iocshRegister().

static const iocshArg AsynGenericConfigArg0 = {
    // name
    "Port Name",
    // type
    iocshArgString,
};
static const iocshArg AsynGenericConfigArg1 = {
    // name
    "Number Devices",
    // type
    iocshArgInt,
};

Values:

enumerator iocshArgInt: The argument is converted to an integer value.

enumerator iocshArgDouble: The argument is converted to a double-precision floating point value.

enumerator iocshArgString

The argument is left as a string.

The memory used to hold the string is “owned” by iocsh and will be reused once the handler function returns.

enumerator iocshArgPdbbase: The argument must be pdbbase.

enumerator iocshArgArgv

An arbitrary number of arguments is expected.

Subsequent iocshArg structures will be ignored.

enumerator iocshArgPersistentString

A copy of the argument will be made and a pointer to the copy will be passed to the handler.

The called function should eventually release this copy by using the pointer as an argument to free().

enumerator iocshArgStringRecord

Equivalent to iocshArgString with a hint for tab completion that the argument is a record name.

Since: 7.0.8

enumerator iocshArgStringPath

Equivalent to iocshArgString with a hint for tab completion that the argument is a file system path.

Since: 7.0.8

Functions

void iocshRegister(const iocshFuncDef *piocshFuncDef, iocshCallFunc func)

Register a command with the IOC shell.

Parameters:

piocshFuncDef – [in] A pointer to a data structure that describes the command and its arguments. See the IOC Shell section of the Application Developer’s Guide for more information.
func – [in] A pointer to a function which is called by iocsh() when the command is encountered.

void iocshRegisterVariable(const iocshVarDef *piocshVarDef)

Parameters:: piocshVarDef –
Returns:: void

const iocshCmdDef *iocshFindCommand(const char *name)

Returns a struct of type iocshCmdDef whose element values are determined by the name parameter. This function calls the function registryFind, defined in Registry.h.

Parameters:: name –
Returns:: const iocshCmdDef*

const iocshVarDef *iocshFindVariable(const char *name)

Returns a struct of type iocshVarDef whose element values are determined by the name parameter. This function calls the function registryFind, defined in Registry.h.

Parameters:: name –
Returns:: const iocshVarDef*

void iocshFree(void)

Frees all memory allocated to registered commands and variables.

Returns:: void

int iocsh(const char *pathname)

Read and evaluate IOC shell commands from the given file.

Equivalent to:

iocshLoad(pathname, NULL) 

See also

iocshLoad()

int iocshCmd(const char *cmd)

Run a single IOC shell command.

Equivalent to:

iocshRun(cmd, NULL) 

See also

iocshRun()

int iocshLoad(const char *pathname, const char *macros)

Read and evaluate IOC shell commands from the given file.

Commands are read from the file until an exit command is encountered or end-of-file is reached.

A list of macros can be supplied as a parameter. These macros are treated as environment variables during execution of the file’s commands.

See also

iocsh()

Parameters:

pathname – [in] A string that represents the path to a file from which commands are read. If NULL, commands are read from the standard input.
macros – [in] NULL or a comma separated list of macro definitions. eg. "VAR1=x,VAR2=y"

Return values:

0 – on success
non-zero – on error
-1 – if the specified file can’t be opened

int iocshRun(const char *cmd, const char *macros)

Run a single IOC shell command.

A list of macros can be supplied as a parameter. These macros are treated as environment variables during execution of the command.

This function may be run from any thread, but many IOC shell commands may not be thread-safe.

See also

iocshCmd()

Parameters:

cmd – [in] Command string. eg. "echo \"something or other""
macros – [in] NULL or a comma separated list of macro definitions. eg. "VAR1=x,VAR2=y"

Return values:

0 – on success
non-zero – on error

int iocshSetError(int err)

Signal error from an IOC shell function.

Since: 7.0.3.1

Parameters:: err – 0 - success (no op), !=0 - error
Returns:: The err argument value.

void iocshEnvClear(const char *name)

Unsets macro values.

This function sets the values of all macros passed to either iocshLoad or iocshRun to NULL.

Parameters:: name –
Returns:: void

Variables

struct dbBase **iocshPpdbbase

union iocshArgBuf

#include <iocsh.h>

This union is used when building the func parameter of iocshRegister(). Each use should match the parameter iocshArgType of the parameters of the function being registered

static void AsynGenericConfigCallFunc (const iocshArgBuf *args)
{
    AsynGenericConfig (args[0].sval, args[1].ival);
}

Public Members

int ival

The value as an integer.

Corresponds to the iocshArgInt type.

double dval

The value as a double-precision floating point.

Corresponds to the iocshArgDouble type.

char *sval

The value as a string.

Corresponds to the iocshArgString and related types.

void *vval

The value as an untyped pointer.

Can be used with the iocshArgPdbbase type.

int ac

Number of arguments passed to the IOC shell command.

Provides the number of elements of the av array.

char **av: The arguments, as an array of strings.

struct iocshArgBuf::[anonymous] aval: The variadic arguments, for the iocshArgArgv type.

struct iocshVarDef

#include <iocsh.h>

This struct is used with the function iocshRegisterVariable. Each instance includes a name, a data type (see iocshArgType), and a pointer to the value.

Public Members

const char *name

iocshArgType type

void *pval

struct iocshArg

#include <iocsh.h>

Data types of function parameters for iocshRegister().

Example:

static const iocshArg AsynGenericConfigArg0 = {
    // name
    "Port Name",
    // type
    iocshArgString,
};
static const iocshArg AsynGenericConfigArg1 = {
    // name
    "Number Devices",
    // type
    iocshArgInt,
};
static const iocshArg* const AsynGenericConfigArgs[] = {
    &AsynGenericConfigArg0,
    &AsynGenericConfigArg1,
};

Public Members

const char *name: Used by the help command to print a synopsis for the command.

iocshArgType type: Data type of the argument.

struct iocshFuncDef

#include <iocsh.h>

Used with iocshRegister() to define the function that is being registered.

Example:

static const iocshFuncDef AsynGenericConfigFuncDef = {
    // name
    "AsynGenericConfig",
    // nargs
    2,
    // arg
    AsynGenericConfigArgs,
    // usage
    "Helpful message describing the command",
};

Public Members

const char *name: Name of the command or function.

int nargs

Number of entries in the array of pointers to argument descriptions.

If 0, arg can be NULL.

const iocshArg *const *arg

Array of pointers to structs of type iocshArg.

Can be NULL if nargs is 0.

const char *usage: Text displayed when using running help <command>.

struct iocshCmdDef

Public Members

iocshFuncDef const *pFuncDef

iocshCallFunc func