0001 NDRX_LCF_XADMIN_ADD(3)
0002 ======================
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 ndrx_lcf_xadmin_add - Register *xadmin(8)* LCF command
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <lcf.h>
0014
0015 #include <nerror.h>
0016
0017 int ndrx_lcf_xadmin_add(ndrx_lcf_reg_xadmin_t *'xcmd');
0018
0019 Link with '-lnstd -lpthread -lrt -lm'
0020
0021 DESCRIPTION
0022 -----------
0023 This function is used to register *xadmin(8)* Latent Command Framework command.
0024 Once function is called, command appears under $ xadmin lcf group of functions.
0025 Function registration maps the administrative utility command string to actual
0026 command code which is published to configuration shared memory block. All details
0027 of the function are encoded in 'xcmd' parameter. This structure also includes
0028 'version' field which is used for forward/backward compatibility. Function registration
0029 with xadmin is purely only needed for xadmin user execution. For processes which
0030 performs the LCF command, this registration is not required. Instead processes
0031 requires *ndrx_lcf_func_add(3)* callbacks to be registered with. Callback to xadmin
0032 can be registered via Enduro/X plugin interface, i.e. use ndrx_plugin_init() entry
0033 point. See *ex_devguide(guides)* for plugin development.
0034
0035 *ndrx_lcf_reg_xadmin_t structure is declared as:*
0036
0037 -------------------------------------------------------------------------------
0038
0039 typedef struct
0040 {
0041 int version;
0042 char cmdstr[NDRX_LCF_ADMINCMD_MAX+1];
0043 int command;
0044 char helpstr[NDRX_LCF_ADMINDSCR_MAX+1];
0045 long dltflags;
0046 int dfltslot;
0047 } ndrx_lcf_reg_xadmin_t;
0048
0049 -------------------------------------------------------------------------------
0050
0051 Where *ndrx_lcf_reg_xadmin_t* fields shall be filled in following way:
0052
0053 'version' - Actual version is present in macros *NDRX_LCF_XCMD_VERSION* (currently it is *1*).
0054
0055 'cmdstr' - Is command string used in xadmin lcf COMMAND. It must be valid C style
0056 identifier. Max command string length is *32+1*.
0057
0058 'command' - This is actual command code. Must be value in range of
0059 *NDRX_LCF_CMD_MIN_CUST*..*NDRX_LCF_CMD_MAX_CUST*.
0060
0061 'helpstr' - This is help text appearing in $ xadmin help lcf. Max length of text
0062 is *128+1*.
0063
0064 'dltflags' - These are default bitwise flags used by command. These flags also affects
0065 the checking of mandatory arguments (*-A* and/or *-B*) to be required when command
0066 is issued. See value bellow.
0067
0068 'dfltslot' - Default slot number to which publish this command. May override by
0069 xadmin *-s* argument. Note that slot number must be lower than *NDRX_LCFMAX* env
0070 variable.
0071
0072
0073 DEFAULT FLAGS
0074 -------------
0075
0076 *NDRX_LCF_FLAG_ALL* - Apply command to all binaries in application instance, same
0077 as if xadmin lcf COMMAND *-a* flags would be set command.
0078
0079 *NDRX_LCF_FLAG_ARGA* - Argument *-A* is mandatory to have value.
0080
0081 *NDRX_LCF_FLAG_ARGB* - Argument *-B* is mandatory to have value.
0082
0083 *NDRX_LCF_FLAG_DOSTARTUP* - Perform the command at startup of the executable which
0084 attaches to existing shared memory segments. This is the same as if xadmin lcf COMMAND *-n*
0085 flag would be set.
0086
0087 *NDRX_LCF_FLAG_DOSTARTUPEXP* - Perform the command at startup of the executable which
0088 attaches to existing shared memory segments, only when command age is less than
0089 *NDRX_LCFCMDEXP* (default is *60* seconds). This is the same as if xadmin lcf COMMAND *-e*
0090 flag would be set.
0091
0092
0093 RETURN VALUE
0094 ------------
0095 On success, *ndrx_lcf_xadmin_add()* returns 0. On error, -1 is returned, with
0096 *Nerror* set to indicate the error.
0097
0098 ERRORS
0099 ------
0100 Note that *Nstrerror()* returns generic error message plus custom message
0101 with debug info from last function call.
0102
0103 *NEINVAL* 'xcmd->cmdstr' is empty, invalid flags specified. *command* field is out of
0104 range of the range. 'xcmd' is NULL. 'xcmd->cmdstr' is not valid identifier.
0105
0106 *NEVERSION* Invalid version specified in structure.
0107
0108 *NEEXISTS* Command with given 'xcmd->cmdstr' is already registered.
0109
0110 *NEMALLOC* Malloc failed.
0111
0112
0113 THREAD SAFETY
0114 -------------
0115 *ndrx_lcf_xadmin_add()* function is thread safe.
0116
0117 EXAMPLE
0118 -------
0119 See *atmitest/test081_lcf/custom_lcf.c* for sample code.
0120
0121 BUGS
0122 ----
0123 Report bugs to support@mavimax.com
0124
0125 SEE ALSO
0126 --------
0127 *ndrx_lcf_func_add(3)* *ndrx_lcf_publish(3)* *ex_devguide(guides)* *ex_env(5)*
0128 *xadmin(8)*
0129
0130 COPYING
0131 -------
0132 (C) Mavimax, Ltd
0133
