0001 NDRX_LCF_PUBLISH(3)
0002 ===================
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 ndrx_lcf_publish - Publish LCF command to shared memory
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <lcf.h>
0014
0015 #include <nerror.h>
0016
0017 int ndrx_lcf_publish(int 'slot', ndrx_lcf_command_t *'cmd');
0018
0019 Link with '-lnstd -lpthread -lrt -lm'
0020
0021 DESCRIPTION
0022 -----------
0023 This function is alternative of use of "$ xadmin lcf COMMAND", which is recommended
0024 way of administrating LCF commands. ndrx_lcf_publish() receives slot number in 'slot'
0025 argument. The initialized command data is received in 'cmd'. The Function performs
0026 validation of 'cmd' and 'slot'.
0027
0028 *ndrx_lcf_command_t structure is declared as:*
0029
0030 -------------------------------------------------------------------------------
0031
0032 typedef struct
0033 {
0034 int version;
0035 unsigned cmdversion;
0036 char cmdstr[NDRX_LCF_ADMINCMD_MAX+1];
0037 ndrx_stopwatch_t publtim;
0038 int command;
0039 char arg_a[PATH_MAX+1];
0040 char arg_b[NAME_MAX+1];
0041 long flags;
0042 char procid[NAME_MAX];
0043 int applied;
0044 int failed;
0045 int seen;
0046 long fbackcode;
0047 char fbackmsg[NDRX_LCF_FEEDBACK_BUF];
0048
0049 } ndrx_lcf_command_t;
0050
0051 -------------------------------------------------------------------------------
0052
0053 Where *ndrx_lcf_command_t* fields is filled in following way:
0054
0055 'version' - Version number which structure was posted.
0056
0057 'cmdversion' - ignored for input (internal counter used).
0058
0059 'cmdstr' - Command string being published. This is for reference only. Max string
0060 length is *32+1*.
0061
0062 'publtim' - ignored for input.
0063
0064 'command' - Command code published. Function does not verify the actually is command
0065 exists, as targeted binaries which do not have the callback for the command, will
0066 ignore the command.
0067
0068 'arg_a' - Argument -A value for the command.
0069
0070 'arg_b' - Argument -B value for the command.
0071
0072 'flags' - Any *NDRX_LCF_FLAG* flags. Except *NDRX_LCF_FLAG_FBACK_CODE* or *NDRX_LCF_FLAG_FBACK_MSG*.
0073 see bellow.
0074
0075 'procid' - Pid if *flags* contains *NDRX_LCF_FLAG_PID* (posting by pid)
0076 or Process name if *flags* contains *NDRX_LCF_FLAG_BIN* (posting by binary name).
0077 In regexp mode *NDRX_LCF_FLAG_DOREX* contains regexp expression.
0078
0079 'applied' - Must be set to *0*.
0080
0081 'failed' - Must be set to *0*.
0082
0083 'seen' - Must be set to *0*.
0084
0085 'fbackcode' - Must contain *0*.
0086
0087 'fbackmsg' - Must be empty string i.e. first byte *0x00*.
0088
0089
0090 FLAGS
0091 -----
0092
0093 *NDRX_LCF_FLAG_PID* - 'cmd->procid' contains PID or PID regexp.
0094
0095 *NDRX_LCF_FLAG_BIN* - 'cmd->procid' contains binary name or regexp.
0096
0097 *NDRX_LCF_FLAG_ALL* - Apply command to all binaries in application instance, same
0098 as if xadmin lcf COMMAND *-a* flags would be set command.
0099
0100 *NDRX_LCF_FLAG_ARGA* - Argument *-A* is set.
0101
0102 *NDRX_LCF_FLAG_ARGB* - Argument *-B* is set.
0103
0104 *NDRX_LCF_FLAG_DOSTARTUP* - Perform the command at startup of the executable which
0105 attaches to existing shared memory segments. This is the same as if xadmin lcf COMMAND *-n*
0106 flag would be set.
0107
0108 *NDRX_LCF_FLAG_DOSTARTUPEXP* - Perform the command at startup of the executable which
0109 attaches to existing shared memory segments, only when command age is less than
0110 *NDRX_LCFCMDEXP* (default is *60* seconds). This is the same as if xadmin lcf COMMAND *-e*
0111 flag would be set.
0112
0113 *NDRX_LCF_FLAG_DOREX* - 'cmd->procid' contains regular expression of pid or binary
0114 name.
0115
0116
0117 RETURN VALUE
0118 ------------
0119 On success, *ndrx_lcf_publish()* returns 0. On error, -1 is returned, with
0120 *Nerror* set to indicate the error.
0121
0122 ERRORS
0123 ------
0124 Note that *Nstrerror()* returns generic error message plus custom message
0125 with debug info from last function call.
0126
0127 *NEINVAL* 'cmd' is NULL. Invalid flags passed. Feedback fields are not reset to 0/empty.
0128 'cmd->cmdstr' is empty. String fields longer than field size ('cmdstr', 'arg_a',
0129 'arg_b', 'procid', 'fbackmsg'). Field 'cmd->applied' and/or 'cmd->failed' and/or 'cmd->seen'
0130 is not set to *0*. 'slot' value less than *0*.
0131
0132 *NEVERSION* Invalid version specified in structure.
0133
0134 *NESUPPORT* LCF framework is not initialized.
0135
0136 *NELIMIT* Slot number in 'slot' number is greater than available number of slots defined
0137 by *NDRX_LCFMAX* env variable (see *ex_env(5)*).
0138
0139 *NESYSTEM* Failed to lock semaphore for write.
0140
0141 *NEMALLOC* Malloc failed.
0142
0143
0144 THREAD SAFETY
0145 -------------
0146 *ndrx_lcf_publish()* function is thread safe.
0147
0148 EXAMPLE
0149 -------
0150 See *xadmin/cmd_lcf.c* for sample code.
0151
0152 BUGS
0153 ----
0154 Report bugs to support@mavimax.com
0155
0156 SEE ALSO
0157 --------
0158 *ndrx_lcf_func_add(3)* *ndrx_lcf_xadmin_add(3)* *ex_devguide(guides)* *ex_env(5)*
0159 *xadmin(8)*
0160
0161 COPYING
0162 -------
0163 (C) Mavimax, Ltd
0164
