0001 NDRX_LCF_FUNC_ADD(3)
0002 ====================
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 ndrx_lcf_func_add - Register LCF command callback function
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <lcf.h>
0014
0015 #include <nerror.h>
0016
0017 int ndrx_lcf_func_add(ndrx_lcf_reg_func_t *'cfunc');
0018
0019 Link with '-lnstd -lpthread -lrt -lm'
0020
0021 DESCRIPTION
0022 -----------
0023 Function is used to add callback handler for LCF command. Command data and callback
0024 is configured in 'cfunc' argument structure. The commands for any process may be
0025 registered via Enduro/X plugin interface, see *ex_devguide(guides)*.
0026
0027 *Limited use of Enduro/X functions within callback*
0028
0029 LCF callback are activated at debug log points at any portion of Enduro/X code
0030 and also in user code if *tplog(3)* or TP_LOG() macros are used. Thus it is impossible
0031 to guaranty that current XATMI context will be able to do things like *tpcall(3)*,
0032 or some UBF buffer manipulations. As callbacks by them selves may be activated
0033 from such region. Or from some points where Enduro/X holds mutex locks. That might
0034 lead to deadlocks or incorrect/corrupted working further working of the process.
0035 To do some XATMI/UBF related works, it is recommended that new thread is started
0036 from callback function. Or other option is to set some global variable which later
0037 is processed by normal user code.
0038
0039 Following list of functions is safe to use from callbacks:
0040
0041 - Logging: *tplog(3)*, *tplogdump(3)*, *tplogdumpdiff(3)*, *TP_LOG()*, *TP_DUMP()*, *TP_DUMP_DIFF()*
0042
0043
0044 *ndrx_lcf_reg_func_t structure is declared as:*
0045
0046 -------------------------------------------------------------------------------
0047
0048 typedef struct
0049 {
0050 int version;
0051 int command;
0052 char cmdstr[NDRX_LCF_ADMINCMD_MAX+1];
0053 int (*pf_callback)(ndrx_lcf_command_t *cmd, long *p_flags);
0054 } ndrx_lcf_reg_func_t;
0055
0056 -------------------------------------------------------------------------------
0057
0058 Where *ndrx_lcf_reg_xadmin_t* fields shall be filled in following way:
0059
0060 'version' - Actual version is present in macros *NDRX_LCF_CCMD_VERSION* (currently it is *1*).
0061
0062 'command' - This is actual command code. Must be value in range of
0063 *NDRX_LCF_CMD_MIN_CUST*..*NDRX_LCF_CMD_MAX_CUST*.
0064
0065 'cmdstr' - Is command string used in xadmin lcf COMMAND. It must be valid C style
0066 identifier. Max command string length is *32+1*.
0067
0068 'pf_callback' - Callback function. It receives copy of shared memory command
0069 object present in 'cmd' variable. The callback function can return feedback code
0070 and feedback message. The values shall be loaded in 'cmd' variable fields (bellow)
0071 and corresponding flags *NDRX_LCF_FLAG_FBACK_CODE* and/or *NDRX_LCF_FLAG_FBACK_MSG*
0072 shall be set. In case of success callback shall return *0* which is accounted
0073 in shared memory statistics for given command.
0074
0075
0076 *ndrx_lcf_command_t structure is declared as:*
0077
0078 -------------------------------------------------------------------------------
0079
0080 typedef struct
0081 {
0082 int version;
0083 unsigned cmdversion;
0084 char cmdstr[NDRX_LCF_ADMINCMD_MAX+1];
0085 ndrx_stopwatch_t publtim;
0086 int command;
0087 char arg_a[PATH_MAX+1];
0088 char arg_b[NAME_MAX+1];
0089 long flags;
0090 char procid[NAME_MAX];
0091 int applied;
0092 int failed;
0093 int seen;
0094 long fbackcode;
0095 char fbackmsg[NDRX_LCF_FEEDBACK_BUF];
0096
0097 } ndrx_lcf_command_t;
0098
0099 -------------------------------------------------------------------------------
0100
0101 Where *ndrx_lcf_command_t* fields is filled in following way:
0102
0103 'version' - Version number which structure was posted.
0104
0105 'cmdversion' - Posting number (to detect that command is runnable).
0106
0107 'cmdstr' - Command string.
0108
0109 'publtim' - Command age in Enduro/X stopwatch time.
0110
0111 'command' - Command code published.
0112
0113 'arg_a' - Argument -A value passed in xadmin lcf COMMAND -A <VALUE>
0114
0115 'arg_b' - Argument -B value passed in xadmin lcf COMMAND -B <VALUE>
0116
0117 'flags' - Any *NDRX_LCF_FLAG* flags. Except *NDRX_LCF_FLAG_FBACK_CODE* or *NDRX_LCF_FLAG_FBACK_MSG*.
0118
0119 'procid' - Pid if *flags* contains *NDRX_LCF_FLAG_PID* (posting by pid)
0120 or Process name if *flags* contains *NDRX_LCF_FLAG_BIN* (posting by binary name).
0121 In regexp mode *NDRX_LCF_FLAG_DOREX* contains regexp expression.
0122
0123 'applied' - Number of processes applied command, this is up till execution in
0124 current binary. *NOTE* for performance reasons, this value is no synchronized between
0125 other processes.
0126
0127 'failed' - Number of processes failed to execute command, this is up till execution in
0128 current binary. *NOTE* for performance reasons, this value is no synchronized between
0129 other processes.
0130
0131 'seen' - Number of processes seen this command but not matched for execution, this is up till execution in
0132 current binary. *NOTE* for performance reasons, this value is no synchronized between
0133 other processes.
0134
0135 'fbackcode' - this field may be used by callback function to return the value to
0136 and store it in shared memory. Value is copied to shm in case if *p_flags* is
0137 set to *NDRX_LCF_FLAG_FBACK_CODE*. NOTE! value copy is not synchronized between
0138 processes and latest process (if several are doing feedback) will survive in
0139 results.
0140
0141 'fbackmsg' - this field may be used by callback function to return the value to
0142 and store it in shared memory. Value is copied to shm in case if *p_flags* is
0143 set to *NDRX_LCF_FLAG_FBACK_MSG*. Buffer size is *64*. The data returned must
0144 be zero terminated string. NOTE! value copy is not synchronized between
0145 processes and latest process (if several are doing feedback) will survive in
0146 results.
0147
0148 RETURN VALUE
0149 ------------
0150 On success, *ndrx_lcf_func_add()* returns 0. On error, -1 is returned, with
0151 *Nerror* set to indicate the error.
0152
0153 ERRORS
0154 ------
0155 Note that *Nstrerror()* returns generic error message plus custom message
0156 with debug info from last function call.
0157
0158 *NEINVAL* 'cfunc' is NULL. 'cfunc->cmdstr' is NULL. 'cfunc->pf_callback' is NULL.
0159
0160 *NEVERSION* Invalid version specified in structure.
0161
0162 *NEEXISTS* Callback for command code in 'cfunc->command' is already registered.
0163
0164 *NEMALLOC* Malloc failed.
0165
0166 THREAD SAFETY
0167 -------------
0168 *ndrx_lcf_func_add()* function is thread safe.
0169
0170 EXAMPLE
0171 -------
0172 See *atmitest/test081_lcf/custom_lcf.c* for sample code.
0173
0174 BUGS
0175 ----
0176 Report bugs to support@mavimax.com
0177
0178 SEE ALSO
0179 --------
0180 *ndrx_lcf_xadmin_add(3)* *ndrx_lcf_publish(3)* *ex_devguide(guides)* *ex_env(5)*
0181 *xadmin(8)*
0182
0183 COPYING
0184 -------
0185 (C) Mavimax, Ltd
0186
