iocsh.h

C and C++ defintions 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:

int iocsh (const char *pathname)

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

int iocshCmd (const char *cmd)

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

Registration functions:

void iocshRegister (const iocshFuncDef

* piocshFuncDef, iocshCallFunc func)

void epicsStdCall iocshRegisterVariable (const

iocshVarDef *piocshVarDef)

Defines

IOCSH_STATIC_FUNC

IOCSHFUNCDEF_HAS_USAGE

Typedefs

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

Enums

enum iocshArgType

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

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

Values:

enumerator iocshArgInt

enumerator iocshArgDouble

enumerator iocshArgString

enumerator iocshArgPdbbase

enumerator iocshArgArgv

enumerator iocshArgPersistentString

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)

This function is used to register a command with the IOC shell.

Parameters:

piocshFuncDef – A pointer to a data structure that describes the command and its arguments.
func – A pointer to a function which is called by iocsh() when the command is encountered.

Returns:

void

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)

This function is used to execute IOC shell commands from a file.

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

Equivalent to:

iocshLoad(pathname, NULL) 

Parameters:: pathname – A string that represents the path to a file from which commands are read.
Returns:: 0 on success, non-zero on error

int iocshCmd(const char *cmd)

This function is used to exectute a single IOC shell command.

Equivalent to:

iocshRun(cmd, NULL) 

Parameters:: cmd – A string that represents the command to be executed.
Returns:: 0 on success, non-zero on error

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

Read and evaluate IOC shell commands from the given file. A list of macros can be supplied as a parameter. These macros are treated as environment variables during exectution of the file’s commands.

Parameters:

pathname – A string that represents the path to a file from which commands are read.
macros – NULL or a comma separated list of macro definitions. eg. “VAR1=x,VAR2=y”

Returns:

0 on success, non-zero on error

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

Evaluate a single IOC shell command. A list of macros can be supplied as a parameter. These macros are treated as environment variables during exectution of the command.

Parameters:

cmd –

Command string. eg. “echo "something or other””

@param macros NULL or a comma separated list of macro definitions. eg. “VAR1=x,VAR2=y”

Returns:

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 paramter of iocshRegister(). Each use should match the parameter type 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

double dval

char *sval

void *vval

int ac

char **av

struct iocshArgBuf::[anonymous] aval

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>

This struct is used to indicate data types of function parameters for iocshRegister(). The name element is used by the help command to print a synopsis for the command. The type element describes the data type of the argument and takes a value from iocshArgType.

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

Public Members

const char *name

iocshArgType type

struct iocshFuncDef

#include <iocsh.h>

This struct is used with iocshRegister to define the function that is being registered.

name - the name of the command or function

nargs - the number of entries in the array of pointers to argument descriptions

arg - an array of pointers to structs of type iocshArg

static const iocshFuncDef AsynGenericConfigFuncDef
 = { "AsynGenericConfig", 2, AsynGenericConfigArgs };

Public Members

const char *name

int nargs

const iocshArg *const *arg

const char *usage

struct iocshCmdDef

Public Members

iocshFuncDef const *pFuncDef

iocshCallFunc func