0001 TPBROADCAST(3)
0002 ==============
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tpbroadcast - Broadcast unsolicited messages to matched XATMI clients
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <atmi.h>
0014
0015 int tpbroadcast(char *'lmid', char *'usrname', char *'cltname', char *'data',
0016 long 'len', long 'flags');
0017
0018
0019 For XATMI client link with '-latmiclt -latmi -lubf -lnstd -lpthread -lrt -lm'
0020
0021 For XATMI server link with '-latmisrv|-latmisrvnomain|-latmisrvinteg -latmi
0022 -lubf -lnstd -lpthread -lrt -lm'
0023
0024 DESCRIPTION
0025 -----------
0026 Function is used for sending unsolicited message to multiple clients at once.
0027 The target clients can be matched by following options:
0028
0029 - 'lmid' Cluster node id to send the message to. If field is set to empty string
0030 (first byte 0x00) then any cluster node id is matched. If string value is given
0031 then numeric value is expected and is matched against the connected cluster nodes.
0032 Either local or remote. This field can be set to regular expression,
0033 in that case 'flags' should contain the 'TPREGEXMATCH'. Maximum
0034 statement length is *MAXTIDENT**2-1.
0035
0036 - 'usrname' is reserved for future use. Currently not supported.
0037
0038 - 'cltname' is process name (executable name) that should be matched. If 'cltname'
0039 is NULL or empty string, then it is matched. If string is given then exact executable
0040 is matched for delivery. If binary runs in multiple copies, all of them will
0041 receive notification. The field can be set to regular expression, in that case
0042 flags must contain 'TPREGEXMATCH'. The max length of 'cltname' string can be
0043 *MAXTIDENT**2-1.
0044
0045
0046 Any combination is possible between 'lmid' and 'cltname'. Any matched process that
0047 will fulfill the matching requirements will receive the message.
0048
0049 The data sent in broadcast is set in variable 'data' which is XATMI
0050 buffer allocated by *tpalloc(3)* (or auto buffer). The complementary 'len' is
0051 used only for buffer types which do not contain length descriptor internally (i.e.
0052 *CARRAY* buffer type).
0053
0054 The 'data' field can be NULL. In this situation matched client callbacks will be called,
0055 but no data will be sent to client.
0056
0057 In case when 'lmid' is matched on another node, then full broadcast request with
0058 all parameters are sent to remote machines '@TPBROADNNN' service (advertised by
0059 *tpbrdcstsv(8)*). When dispatched, the remote '@TPBROADNNN' will process the local
0060 matchings of the clients processes and will do the broadcast locally.
0061
0062 *Valid flags*
0063
0064 *TPNOBLOCK* Do not block on full client queue, instead return error.
0065
0066 *TPNOTIME* Do not timeout when waiting on full queue (*TPNOBLOCK* is not set).
0067
0068 *TPSIGRSTRT* Restart the system call in progress if interrupted by signal handler.
0069 This affects only underlaying mq_* function calls.
0070
0071 *TPREGEXMATCH* Match 'lmid' (cluster node id) and 'cltname' by assuming that
0072 these are regular expressions.
0073
0074
0075 RETURN VALUE
0076 ------------
0077 On success, *tpbroadcast()* return zero; on error, -1 is returned, with *tperrno*
0078 set to indicate the error.
0079
0080 ERRORS
0081 ------
0082 Note that *tpstrerror()* returns generic error message plus custom message with
0083 debug info from last function call. Note that Enduro/X does not analyze the errors
0084 returned by each individual delivery to the client process, thus the function will
0085 try to delivery to all of the clients the notification. If some of them were
0086 exited or for example client reply (delivery) queue was full and *TPNOBLOCK*
0087 was set or *TPNOTIME* was not set, then error is logged to Enduro/X 'ndrx' logger
0088 and ULOG, but *tpbroadcast(3)* will return success.
0089
0090 *TPEINVAL* Environment variables not configured, see *ex_env(5)* page, or invalid
0091 parameters have been passed to the function, for example 'clientid', 'lmtid' or
0092 'username' are set and they are invalid regular expressions (i.e. with *TPREGEXMATCH*
0093 set).
0094
0095 *TPESYSTEM* System failure occurred during serving. See logs i.e. user log,
0096 or debugs for more info.
0097
0098 *TPEOS* System failure occurred during serving. See logs i.e. user log,
0099 or debugs for more info.
0100
0101
0102 EXAMPLE
0103 -------
0104 See *atmitest/test039_tpbroadcast/atmiclt39.c* for sample code.
0105
0106 BUGS
0107 ----
0108 Report bugs to support@mavimax.com
0109
0110 SEE ALSO
0111 --------
0112 *tpsetunsol(3)* *tpnotify(3)* *tpchkunsol(3)* *tpinit(3)* *tpbrdcstsv(8)*
0113
0114 COPYING
0115 -------
0116 (C) Mavimax, Ltd
0117
