1 /* module-template.h 2 * This header contains macros that can be used to implement the 3 * plumbing of modules. 4 * 5 * File begun on 2007-07-25 by RGerhards 6 * 7 * Copyright 2007-2015 Adiscon GmbH. 8 * 9 * This file is part of the rsyslog runtime library. 10 * 11 * Licensed under the Apache License, Version 2.0 (the "License"); 12 * you may not use this file except in compliance with the License. 13 * You may obtain a copy of the License at 14 * 15 * http://www.apache.org/licenses/LICENSE-2.0 16 * -or- 17 * see COPYING.ASL20 in the source distribution 18 * 19 * Unless required by applicable law or agreed to in writing, software 20 * distributed under the License is distributed on an "AS IS" BASIS, 21 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 22 * See the License for the specific language governing permissions and 23 * limitations under the License. 24 */ 25 #ifndef MODULE_TEMPLATE_H_INCLUDED 26 #define MODULE_TEMPLATE_H_INCLUDED 1 27 28 #include "modules.h" 29 #include "obj.h" 30 #include "objomsr.h" 31 #include "threads.h" 32 33 /* macro to define standard output-module static data members 34 */ 35 #define DEF_MOD_STATIC_DATA \ 36 static __attribute__((unused)) rsRetVal (*omsdRegCFSLineHdlr)(uchar *pCmdName, int bChainingPermitted, \ 37 ecslCmdHdrlType eType, rsRetVal (*pHdlr)(), void *pData, void *pOwnerCookie); 38 39 #define DEF_OMOD_STATIC_DATA \ 40 DEF_MOD_STATIC_DATA \ 41 DEFobjCurrIf(obj) \ 42 static __attribute__((unused)) int bCoreSupportsBatching; 43 #define DEF_IMOD_STATIC_DATA \ 44 DEF_MOD_STATIC_DATA \ 45 DEFobjCurrIf(obj) 46 #define DEF_LMOD_STATIC_DATA \ 47 DEF_MOD_STATIC_DATA 48 #define DEF_PMOD_STATIC_DATA \ 49 DEFobjCurrIf(obj) \ 50 DEF_MOD_STATIC_DATA 51 #define DEF_SMOD_STATIC_DATA \ 52 DEFobjCurrIf(obj) \ 53 DEF_MOD_STATIC_DATA 54 #define DEF_FMOD_STATIC_DATA \ 55 DEFobjCurrIf(obj) \ 56 DEF_MOD_STATIC_DATA 57 58 59 /* Macro to define the module type. Each module can only have a single type. If 60 * a module provides multiple types, several separate modules must be created which 61 * then should share a single library containing the majority of code. This macro 62 * must be present in each module. -- rgerhards, 2007-12-14 63 * Note that MODULE_TYPE_TESTBENCH is reserved for testbenches, but 64 * declared in their own header files (because the rest does not need these 65 * defines). -- rgerhards, 2008-06-13 66 */ 67 #define MODULE_TYPE(x)\ 68 static rsRetVal modGetType(eModType_t *modType) \ 69 { \ 70 *modType = x; \ 71 return RS_RET_OK;\ 72 } 73 74 #define MODULE_TYPE_INPUT MODULE_TYPE(eMOD_IN) 75 #define MODULE_TYPE_OUTPUT MODULE_TYPE(eMOD_OUT) 76 #define MODULE_TYPE_PARSER MODULE_TYPE(eMOD_PARSER) 77 #define MODULE_TYPE_STRGEN MODULE_TYPE(eMOD_STRGEN) 78 #define MODULE_TYPE_FUNCTION MODULE_TYPE(eMOD_FUNCTION) 79 #define MODULE_TYPE_LIB \ 80 DEF_LMOD_STATIC_DATA \ 81 MODULE_TYPE(eMOD_LIB) 82 83 /* Macro to define whether the module should be kept dynamically linked. 84 */ 85 #define MODULE_KEEP_TYPE(x)\ 86 static rsRetVal modGetKeepType(eModKeepType_t *modKeepType) \ 87 { \ 88 *modKeepType = x; \ 89 return RS_RET_OK;\ 90 } 91 #define MODULE_TYPE_NOKEEP MODULE_KEEP_TYPE(eMOD_NOKEEP) 92 #define MODULE_TYPE_KEEP MODULE_KEEP_TYPE(eMOD_KEEP) 93 94 /* macro to define a unique module id. This must be able to fit in a void*. The 95 * module id must be unique inside a running rsyslogd application. It is used to 96 * track ownership of several objects. Most importantly, when the module is 97 * unloaded the module id value is used to find what needs to be destroyed. 98 * We currently use a pointer to modExit() as the module id. This sounds to be 99 * reasonable save, as each module must have this entry point AND there is no valid 100 * reason for twice this entry point being in memory. 101 * rgerhards, 2007-11-21 102 */ 103 #define STD_LOADABLE_MODULE_ID ((void*) modExit) 104 105 106 /* macro to implement the "modGetID()" interface function 107 * rgerhards 2007-11-21 108 */ 109 #define DEFmodGetID \ 110 static rsRetVal modGetID(void **pID) \ 111 { \ 112 *pID = STD_LOADABLE_MODULE_ID;\ 113 return RS_RET_OK;\ 114 } 115 116 /* macro to provide the v6 config system module name 117 */ 118 #define MODULE_CNFNAME(name) \ 119 static rsRetVal modGetCnfName(uchar **cnfName) \ 120 { \ 121 *cnfName = (uchar*) name; \ 122 return RS_RET_OK;\ 123 } 124 125 126 /* to following macros are used to generate function headers and standard 127 * functionality. It works as follows (described on the sample case of 128 * createInstance()): 129 * 130 * BEGINcreateInstance 131 * ... custom variable definitions (on stack) ... (if any) 132 * CODESTARTcreateInstance 133 * ... custom code ... (if any) 134 * ENDcreateInstance 135 */ 136 137 /* createInstance() 138 */ 139 #define BEGINcreateInstance \ 140 static rsRetVal createInstance(instanceData **ppData)\ 141 {\ 142 DEFiRet; /* store error code here */\ 143 instanceData *pData; /* use this to point to data elements */ 144 145 #define CODESTARTcreateInstance \ 146 if((pData = calloc(1, sizeof(instanceData))) == NULL) {\ 147 *ppData = NULL;\ 148 return RS_RET_OUT_OF_MEMORY;\ 149 } 150 151 #define ENDcreateInstance \ 152 *ppData = pData;\ 153 RETiRet;\ 154 } 155 156 /* freeInstance() 157 * This is the cleanup function for the module instance. It is called immediately before 158 * the module instance is destroyed (unloaded). The module should do any cleanup 159 * here, e.g. close file, free instantance heap memory and the like. Control will 160 * not be passed back to the module once this function is finished. Keep in mind, 161 * however, that other instances may still be loaded and used. So do not destroy 162 * anything that may be used by another instance. If you have such a ressource, you 163 * currently need to do the instance counting yourself. 164 */ 165 #define BEGINfreeInstance \ 166 static rsRetVal freeInstance(void* pModData)\ 167 {\ 168 DEFiRet;\ 169 instanceData *pData; 170 171 #define CODESTARTfreeInstance \ 172 pData = (instanceData*) pModData; 173 174 #define ENDfreeInstance \ 175 if(pData != NULL)\ 176 free(pData); /* we need to free this in any case */\ 177 RETiRet;\ 178 } 179 180 /* createWrkrInstance() 181 */ 182 #define BEGINcreateWrkrInstance \ 183 static rsRetVal createWrkrInstance(wrkrInstanceData_t **ppWrkrData, instanceData *pData)\ 184 {\ 185 DEFiRet; /* store error code here */\ 186 wrkrInstanceData_t *pWrkrData; /* use this to point to data elements */ 187 188 #define CODESTARTcreateWrkrInstance \ 189 if((pWrkrData = calloc(1, sizeof(wrkrInstanceData_t))) == NULL) {\ 190 *ppWrkrData = NULL;\ 191 return RS_RET_OUT_OF_MEMORY;\ 192 } \ 193 pWrkrData->pData = pData; 194 195 #define ENDcreateWrkrInstance \ 196 *ppWrkrData = pWrkrData;\ 197 RETiRet;\ 198 } 199 200 /* freeWrkrInstance */ 201 #define BEGINfreeWrkrInstance \ 202 static rsRetVal freeWrkrInstance(void* pd)\ 203 {\ 204 DEFiRet;\ 205 wrkrInstanceData_t *pWrkrData; 206 207 #define CODESTARTfreeWrkrInstance \ 208 pWrkrData = (wrkrInstanceData_t*) pd; 209 210 #define ENDfreeWrkrInstance \ 211 if(pWrkrData != NULL)\ 212 free(pWrkrData); /* we need to free this in any case */\ 213 RETiRet;\ 214 } 215 216 217 /* isCompatibleWithFeature() 218 */ 219 #define BEGINisCompatibleWithFeature \ 220 static rsRetVal isCompatibleWithFeature(syslogFeature __attribute__((unused)) eFeat)\ 221 {\ 222 rsRetVal iRet = RS_RET_INCOMPATIBLE; \ 223 224 #define CODESTARTisCompatibleWithFeature 225 226 #define ENDisCompatibleWithFeature \ 227 RETiRet;\ 228 } 229 230 231 /* beginTransaction() 232 * introduced in v4.3.3 -- rgerhards, 2009-04-27 233 */ 234 #define BEGINbeginTransaction \ 235 static rsRetVal beginTransaction(wrkrInstanceData_t __attribute__((unused)) *pWrkrData)\ 236 {\ 237 DEFiRet; 238 239 #define CODESTARTbeginTransaction /* currently empty, but may be extended */ 240 241 #define ENDbeginTransaction \ 242 RETiRet;\ 243 } 244 245 246 /* commitTransaction() 247 * Commits a transaction. Note that beginTransaction() must have been 248 * called before this entry point. It receives the full batch of messages 249 * to be processed in pParam parameter. 250 * introduced in v8.1.3 -- rgerhards, 2013-12-04 251 */ 252 #define BEGINcommitTransaction \ 253 static rsRetVal commitTransaction(wrkrInstanceData_t __attribute__((unused)) *const pWrkrData, \ 254 actWrkrIParams_t *const pParams, const unsigned nParams)\ 255 {\ 256 DEFiRet; 257 258 #define CODESTARTcommitTransaction /* currently empty, but may be extended */ 259 260 #define ENDcommitTransaction \ 261 RETiRet;\ 262 } 263 264 /* endTransaction() 265 * introduced in v4.3.3 -- rgerhards, 2009-04-27 266 */ 267 #define BEGINendTransaction \ 268 static rsRetVal endTransaction(wrkrInstanceData_t __attribute__((unused)) *pWrkrData)\ 269 {\ 270 DEFiRet; 271 272 #define CODESTARTendTransaction /* currently empty, but may be extended */ 273 274 #define ENDendTransaction \ 275 RETiRet;\ 276 } 277 278 279 /* doAction() 280 */ 281 #define BEGINdoAction \ 282 static rsRetVal doAction(void * pMsgData, wrkrInstanceData_t __attribute__((unused)) *pWrkrData)\ 283 {\ 284 uchar **ppString = (uchar **) pMsgData; \ 285 DEFiRet; 286 287 #define CODESTARTdoAction \ 288 /* ppString may be NULL if the output module requested no strings */ 289 290 #define ENDdoAction \ 291 RETiRet;\ 292 } 293 294 /* below is a variant of doAction where the passed-in data is not the common 295 * case of string. 296 */ 297 #define BEGINdoAction_NoStrings \ 298 static rsRetVal doAction(void * pMsgData, wrkrInstanceData_t __attribute__((unused)) *pWrkrData)\ 299 {\ 300 DEFiRet; 301 302 303 /* dbgPrintInstInfo() 304 * Extra comments: 305 * Print debug information about this instance. 306 */ 307 #define BEGINdbgPrintInstInfo \ 308 static rsRetVal dbgPrintInstInfo(void *pModData)\ 309 {\ 310 DEFiRet;\ 311 instanceData *pData = NULL; 312 313 #define CODESTARTdbgPrintInstInfo \ 314 pData = (instanceData*) pModData; \ 315 (void)pData; /* prevent compiler warning if unused! */ 316 317 #define ENDdbgPrintInstInfo \ 318 RETiRet;\ 319 } 320 321 322 /* parseSelectorAct() 323 * Extra comments: 324 * try to process a selector action line. Checks if the action 325 * applies to this module and, if so, processed it. If not, it 326 * is left untouched. The driver will then call another module. 327 * On exit, ppModData must point to instance data. Also, a string 328 * request object must be created and filled. A macro is defined 329 * for that. 330 * For the most usual case, we have defined a macro below. 331 * If more than one string is requested, the macro can be used together 332 * with own code that overwrites the entry count. In this case, the 333 * macro must come before the own code. It is recommended to be 334 * placed right after CODESTARTparseSelectorAct. 335 */ 336 #define BEGINparseSelectorAct \ 337 static rsRetVal parseSelectorAct(uchar **pp, void **ppModData, omodStringRequest_t **ppOMSR)\ 338 {\ 339 DEFiRet;\ 340 uchar *p;\ 341 instanceData *pData = NULL; 342 343 #define CODESTARTparseSelectorAct \ 344 assert(pp != NULL);\ 345 assert(ppModData != NULL);\ 346 assert(ppOMSR != NULL);\ 347 p = *pp; 348 349 #define CODE_STD_STRING_REQUESTparseSelectorAct(NumStrReqEntries) \ 350 CHKiRet(OMSRconstruct(ppOMSR, NumStrReqEntries)); 351 352 #define CODE_STD_FINALIZERparseSelectorAct \ 353 finalize_it: ATTR_UNUSED; /* semi-colon needed according to gcc doc! */\ 354 if(iRet == RS_RET_OK || iRet == RS_RET_OK_WARN || iRet == RS_RET_SUSPENDED) {\ 355 *ppModData = pData;\ 356 *pp = p;\ 357 } else {\ 358 /* cleanup, we failed */\ 359 if(*ppOMSR != NULL) {\ 360 OMSRdestruct(*ppOMSR);\ 361 *ppOMSR = NULL;\ 362 }\ 363 if(pData != NULL) {\ 364 freeInstance(pData);\ 365 } \ 366 } 367 368 #define ENDparseSelectorAct \ 369 RETiRet;\ 370 } 371 372 /* a special replacement macro for modules that do not support legacy config at all */ 373 #define NO_LEGACY_CONF_parseSelectorAct \ 374 static rsRetVal parseSelectorAct(uchar **pp ATTR_UNUSED, void **ppModData ATTR_UNUSED, \ 375 omodStringRequest_t **ppOMSR ATTR_UNUSED)\ 376 {\ 377 return RS_RET_LEGA_ACT_NOT_SUPPORTED;\ 378 } 379 380 /* newActInst() 381 * Extra comments: 382 * This creates a new instance of a the action that implements the call. 383 * This is part of the conf2 (rsyslog v6) config system. It is called by 384 * the core when an action object has been obtained. The output module 385 * must then verify parameters and create a new action instance (if 386 * parameters are acceptable) or return an error code. 387 * On exit, ppModData must point to instance data. Also, a string 388 * request object must be created and filled. A macro is defined 389 * for that. 390 * For the most usual case, we have defined a macro below. 391 * If more than one string is requested, the macro can be used together 392 * with own code that overwrites the entry count. In this case, the 393 * macro must come before the own code. It is recommended to be 394 * placed right after CODESTARTnewActInst. 395 */ 396 #define BEGINnewActInst \ 397 static rsRetVal newActInst(uchar __attribute__((unused)) *modName, \ 398 struct nvlst __attribute__((unused)) *lst, void **ppModData, \ 399 omodStringRequest_t **ppOMSR)\ 400 {\ 401 DEFiRet;\ 402 instanceData *pData = NULL; \ 403 *ppOMSR = NULL; 404 405 #define CODESTARTnewActInst \ 406 407 #define CODE_STD_STRING_REQUESTnewActInst(NumStrReqEntries) \ 408 CHKiRet(OMSRconstruct(ppOMSR, NumStrReqEntries)); 409 410 #define CODE_STD_FINALIZERnewActInst \ 411 finalize_it:\ 412 if(iRet == RS_RET_OK || iRet == RS_RET_SUSPENDED) {\ 413 *ppModData = pData;\ 414 } else {\ 415 /* cleanup, we failed */\ 416 if(*ppOMSR != NULL) {\ 417 OMSRdestruct(*ppOMSR);\ 418 *ppOMSR = NULL;\ 419 }\ 420 if(pData != NULL) {\ 421 freeInstance(pData);\ 422 } \ 423 } 424 425 #define ENDnewActInst \ 426 RETiRet;\ 427 } 428 429 430 /* newInpInst() 431 * This is basically the equivalent to newActInst() for creating input 432 * module (listener) instances. 433 */ 434 #define BEGINnewInpInst \ 435 static rsRetVal newInpInst(struct nvlst *lst)\ 436 {\ 437 DEFiRet; 438 439 #define CODESTARTnewInpInst \ 440 441 #define CODE_STD_FINALIZERnewInpInst 442 443 #define ENDnewInpInst \ 444 RETiRet;\ 445 } 446 447 448 449 /* newParserInst() 450 * This is basically the equivalent to newActInst() for creating parser 451 * module (listener) instances. 452 */ 453 #define BEGINnewParserInst \ 454 static rsRetVal newParserInst(struct nvlst *lst, void *pinst)\ 455 {\ 456 instanceConf_t *inst; \ 457 DEFiRet; 458 459 #define CODESTARTnewParserInst \ 460 461 #define CODE_STD_FINALIZERnewParserInst 462 463 #define ENDnewParserInst \ 464 if(iRet == RS_RET_OK) \ 465 *((instanceConf_t**)pinst) = inst; \ 466 RETiRet;\ 467 } 468 469 470 /* freeParserInst */ 471 #define BEGINfreeParserInst \ 472 static rsRetVal freeParserInst(void* pi)\ 473 {\ 474 DEFiRet;\ 475 instanceConf_t *pInst; 476 477 #define CODESTARTfreeParserInst\ 478 pInst = (instanceConf_t*) pi; 479 480 #define ENDfreeParserInst\ 481 if(pInst != NULL)\ 482 free(pInst);\ 483 RETiRet;\ 484 } 485 486 /* tryResume() 487 * This entry point is called to check if a module can resume operations. This 488 * happens when a module requested that it be suspended. In suspended state, 489 * the engine periodically tries to resume the module. If that succeeds, normal 490 * processing continues. If not, the module will not be called unless a 491 * tryResume() call succeeds. 492 * Returns RS_RET_OK, if resumption succeeded, RS_RET_SUSPENDED otherwise 493 * rgerhard, 2007-08-02 494 */ 495 #define BEGINtryResume \ 496 static rsRetVal tryResume(wrkrInstanceData_t __attribute__((unused)) *pWrkrData)\ 497 {\ 498 DEFiRet; 499 500 #define CODESTARTtryResume \ 501 assert(pWrkrData != NULL); 502 503 #define ENDtryResume \ 504 RETiRet;\ 505 } 506 507 508 /* initConfVars() - initialize pre-v6.3-config variables 509 */ 510 #define BEGINinitConfVars \ 511 static rsRetVal initConfVars(void)\ 512 {\ 513 DEFiRet; 514 515 #define CODESTARTinitConfVars 516 517 #define ENDinitConfVars \ 518 RETiRet;\ 519 } 520 521 522 /* queryEtryPt() 523 */ 524 #define BEGINqueryEtryPt \ 525 DEFmodGetID \ 526 static rsRetVal queryEtryPt(uchar *name, rsRetVal (**pEtryPoint)())\ 527 {\ 528 DEFiRet; 529 530 #define CODESTARTqueryEtryPt \ 531 if((name == NULL) || (pEtryPoint == NULL)) {\ 532 return RS_RET_PARAM_ERROR;\ 533 } \ 534 *pEtryPoint = NULL; 535 536 #define ENDqueryEtryPt \ 537 if(iRet == RS_RET_OK)\ 538 if(*pEtryPoint == NULL) { \ 539 dbgprintf("entry point '%s' not present in module\n", name); \ 540 iRet = RS_RET_MODULE_ENTRY_POINT_NOT_FOUND;\ 541 } \ 542 RETiRet;\ 543 } 544 545 /* the following definition is the standard block for queryEtryPt for all types 546 * of modules. It should be included in any module, and typically is so by calling 547 * the module-type specific macros. 548 */ 549 #define CODEqueryEtryPt_STD_MOD_QUERIES \ 550 if(!strcmp((char*) name, "modExit")) {\ 551 *pEtryPoint = modExit;\ 552 } else if(!strcmp((char*) name, "modGetID")) {\ 553 *pEtryPoint = modGetID;\ 554 } else if(!strcmp((char*) name, "getType")) {\ 555 *pEtryPoint = modGetType;\ 556 } else if(!strcmp((char*) name, "getKeepType")) {\ 557 *pEtryPoint = modGetKeepType;\ 558 } 559 560 /* the following definition is the standard block for queryEtryPt for output 561 * modules WHICH DO NOT SUPPORT TRANSACTIONS. 562 */ 563 #define CODEqueryEtryPt_STD_OMOD_QUERIES \ 564 CODEqueryEtryPt_STD_MOD_QUERIES \ 565 else if(!strcmp((char*) name, "doAction")) {\ 566 *pEtryPoint = doAction;\ 567 } else if(!strcmp((char*) name, "dbgPrintInstInfo")) {\ 568 *pEtryPoint = dbgPrintInstInfo;\ 569 } else if(!strcmp((char*) name, "freeInstance")) {\ 570 *pEtryPoint = freeInstance;\ 571 } else if(!strcmp((char*) name, "parseSelectorAct")) {\ 572 *pEtryPoint = parseSelectorAct;\ 573 } else if(!strcmp((char*) name, "isCompatibleWithFeature")) {\ 574 *pEtryPoint = isCompatibleWithFeature;\ 575 } else if(!strcmp((char*) name, "tryResume")) {\ 576 *pEtryPoint = tryResume;\ 577 } 578 579 /* the following definition is the standard block for queryEtryPt for output 580 * modules using the transaction interface. 581 */ 582 #define CODEqueryEtryPt_STD_OMODTX_QUERIES \ 583 CODEqueryEtryPt_STD_MOD_QUERIES \ 584 else if(!strcmp((char*) name, "beginTransaction")) {\ 585 *pEtryPoint = beginTransaction;\ 586 } else if(!strcmp((char*) name, "commitTransaction")) {\ 587 *pEtryPoint = commitTransaction;\ 588 } else if(!strcmp((char*) name, "dbgPrintInstInfo")) {\ 589 *pEtryPoint = dbgPrintInstInfo;\ 590 } else if(!strcmp((char*) name, "freeInstance")) {\ 591 *pEtryPoint = freeInstance;\ 592 } else if(!strcmp((char*) name, "parseSelectorAct")) {\ 593 *pEtryPoint = parseSelectorAct;\ 594 } else if(!strcmp((char*) name, "isCompatibleWithFeature")) {\ 595 *pEtryPoint = isCompatibleWithFeature;\ 596 } else if(!strcmp((char*) name, "tryResume")) {\ 597 *pEtryPoint = tryResume;\ 598 } 599 600 /* standard queries for output module interface in rsyslog v8+ */ 601 #define CODEqueryEtryPt_STD_OMOD8_QUERIES \ 602 else if(!strcmp((char*) name, "createWrkrInstance")) {\ 603 *pEtryPoint = createWrkrInstance;\ 604 } else if(!strcmp((char*) name, "freeWrkrInstance")) {\ 605 *pEtryPoint = freeWrkrInstance;\ 606 } 607 608 /* the following definition is queryEtryPt block that must be added 609 * if an output module supports the transactional interface. 610 * rgerhards, 2009-04-27 611 */ 612 #define CODEqueryEtryPt_TXIF_OMOD_QUERIES \ 613 else if(!strcmp((char*) name, "beginTransaction")) {\ 614 *pEtryPoint = beginTransaction;\ 615 } else if(!strcmp((char*) name, "endTransaction")) {\ 616 *pEtryPoint = endTransaction;\ 617 } 618 619 620 /* the following definition is a queryEtryPt block that must be added 621 * if a non-output module supports "isCompatibleWithFeature". 622 * rgerhards, 2009-07-20 623 */ 624 #define CODEqueryEtryPt_IsCompatibleWithFeature_IF_OMOD_QUERIES \ 625 else if(!strcmp((char*) name, "isCompatibleWithFeature")) {\ 626 *pEtryPoint = isCompatibleWithFeature;\ 627 } 628 629 630 /* the following definition is the standard block for queryEtryPt for INPUT 631 * modules. This can be used if no specific handling (e.g. to cover version 632 * differences) is needed. 633 */ 634 #define CODEqueryEtryPt_STD_IMOD_QUERIES \ 635 CODEqueryEtryPt_STD_MOD_QUERIES \ 636 else if(!strcmp((char*) name, "runInput")) {\ 637 *pEtryPoint = runInput;\ 638 } else if(!strcmp((char*) name, "willRun")) {\ 639 *pEtryPoint = willRun;\ 640 } else if(!strcmp((char*) name, "afterRun")) {\ 641 *pEtryPoint = afterRun;\ 642 } 643 644 645 /* the following block is to be added for modules that support the v2 646 * config system. The config name is also provided. 647 */ 648 #define CODEqueryEtryPt_STD_CONF2_QUERIES \ 649 else if(!strcmp((char*) name, "beginCnfLoad")) {\ 650 *pEtryPoint = beginCnfLoad;\ 651 } else if(!strcmp((char*) name, "endCnfLoad")) {\ 652 *pEtryPoint = endCnfLoad;\ 653 } else if(!strcmp((char*) name, "checkCnf")) {\ 654 *pEtryPoint = checkCnf;\ 655 } else if(!strcmp((char*) name, "activateCnf")) {\ 656 *pEtryPoint = activateCnf;\ 657 } else if(!strcmp((char*) name, "freeCnf")) {\ 658 *pEtryPoint = freeCnf;\ 659 } \ 660 CODEqueryEtryPt_STD_CONF2_CNFNAME_QUERIES 661 662 /* the following block is to be added for modules that support v2 663 * module global parameters [module(...)] 664 */ 665 #define CODEqueryEtryPt_STD_CONF2_setModCnf_QUERIES \ 666 else if(!strcmp((char*) name, "setModCnf")) {\ 667 *pEtryPoint = setModCnf;\ 668 } \ 669 670 /* the following block is to be added for output modules that support the v2 671 * config system. The config name is also provided. 672 */ 673 #define CODEqueryEtryPt_STD_CONF2_OMOD_QUERIES \ 674 else if(!strcmp((char*) name, "newActInst")) {\ 675 *pEtryPoint = newActInst;\ 676 } \ 677 CODEqueryEtryPt_STD_CONF2_CNFNAME_QUERIES 678 679 680 /* the following block is to be added for input modules that support the v2 681 * config system. The config name is also provided. 682 */ 683 #define CODEqueryEtryPt_STD_CONF2_IMOD_QUERIES \ 684 else if(!strcmp((char*) name, "newInpInst")) {\ 685 *pEtryPoint = newInpInst;\ 686 } \ 687 CODEqueryEtryPt_STD_CONF2_CNFNAME_QUERIES 688 689 690 /* the following block is to be added for modules that require 691 * pre priv drop activation support. 692 */ 693 #define CODEqueryEtryPt_STD_CONF2_PREPRIVDROP_QUERIES \ 694 else if(!strcmp((char*) name, "activateCnfPrePrivDrop")) {\ 695 *pEtryPoint = activateCnfPrePrivDrop;\ 696 } 697 698 /* the following block is to be added for modules that support 699 * their config name. This is required for the rsyslog v6 config 700 * system, especially for outout modules which do not require 701 * the new set of begin/end config settings. 702 */ 703 #define CODEqueryEtryPt_STD_CONF2_CNFNAME_QUERIES \ 704 else if(!strcmp((char*) name, "getModCnfName")) {\ 705 *pEtryPoint = modGetCnfName;\ 706 } 707 708 /* the following definition is the standard block for queryEtryPt for LIBRARY 709 * modules. This can be used if no specific handling (e.g. to cover version 710 * differences) is needed. 711 */ 712 #define CODEqueryEtryPt_STD_LIB_QUERIES \ 713 CODEqueryEtryPt_STD_MOD_QUERIES 714 715 /* the following definition is the standard block for queryEtryPt for PARSER 716 * modules. This can be used if no specific handling (e.g. to cover version 717 * differences) is needed. 718 */ 719 #define CODEqueryEtryPt_STD_PMOD_QUERIES \ 720 CODEqueryEtryPt_STD_MOD_QUERIES \ 721 else if(!strcmp((char*) name, "parse")) {\ 722 *pEtryPoint = parse;\ 723 } else if(!strcmp((char*) name, "GetParserName")) {\ 724 *pEtryPoint = GetParserName;\ 725 } 726 727 /* the following definition is the standard block for queryEtryPt for PARSER 728 * modules obeying the v2+ config interface. 729 */ 730 #define CODEqueryEtryPt_STD_PMOD2_QUERIES \ 731 CODEqueryEtryPt_STD_MOD_QUERIES \ 732 else if(!strcmp((char*) name, "parse2")) {\ 733 *pEtryPoint = parse2;\ 734 } else if(!strcmp((char*) name, "GetParserName")) {\ 735 *pEtryPoint = GetParserName;\ 736 } else if(!strcmp((char*) name, "newParserInst")) {\ 737 *pEtryPoint = newParserInst;\ 738 } else if(!strcmp((char*) name, "freeParserInst")) {\ 739 *pEtryPoint = freeParserInst;\ 740 } \ 741 CODEqueryEtryPt_STD_CONF2_CNFNAME_QUERIES 742 743 744 745 /* the following definition is the standard block for queryEtryPt for rscript function 746 * modules. This can be used if no specific handling (e.g. to cover version 747 * differences) is needed. 748 */ 749 #define CODEqueryEtryPt_STD_FMOD_QUERIES \ 750 CODEqueryEtryPt_STD_MOD_QUERIES \ 751 else if(!strcmp((char*) name, "getFunctArray")) {\ 752 *pEtryPoint = getFunctArray;\ 753 } 754 755 /* the following definition is the standard block for queryEtryPt for Strgen 756 * modules. This can be used if no specific handling (e.g. to cover version 757 * differences) is needed. 758 */ 759 #define CODEqueryEtryPt_STD_SMOD_QUERIES \ 760 CODEqueryEtryPt_STD_MOD_QUERIES \ 761 else if(!strcmp((char*) name, "strgen")) {\ 762 *pEtryPoint = strgen;\ 763 } else if(!strcmp((char*) name, "GetName")) {\ 764 *pEtryPoint = GetStrgenName;\ 765 } 766 767 /* modInit() 768 * This has an extra parameter, which is the specific name of the modInit 769 * function. That is needed for built-in modules, which must have unique 770 * names in order to link statically. Please note that this is always only 771 * the case with modInit() and NO other entry point. The reason is that only 772 * modInit() is visible form a linker/loader point of view. All other entry 773 * points are passed via rsyslog-internal query functions and are defined 774 * static inside the modules source. This is an important concept, as it allows 775 * us to support different interface versions within a single module. (Granted, 776 * we do not currently have different interface versions, so we can not put 777 * it to a test - but our firm believe is that we can do all abstraction needed...) 778 * 779 * Extra Comments: 780 * initialize the module 781 * 782 * Later, much more must be done. So far, we only return a pointer 783 * to the queryEtryPt() function 784 * TODO: do interface version checking & handshaking 785 * iIfVersRequetsed is the version of the interface specification that the 786 * caller would like to see being used. ipIFVersProvided is what we 787 * decide to provide. 788 * rgerhards, 2007-11-21: see modExit() comment below for important information 789 * on the need to initialize static data with code. modInit() may be called on a 790 * cached, left-in-memory copy of a previous incarnation. 791 */ 792 #define BEGINmodInit(uniqName) \ 793 rsRetVal __attribute__((unused)) modInit##uniqName(int iIFVersRequested __attribute__((unused)), \ 794 int *ipIFVersProvided, rsRetVal (**pQueryEtryPt)(), rsRetVal (*pHostQueryEtryPt)(uchar*, rsRetVal (**)()), \ 795 modInfo_t __attribute__((unused)) *pModInfo);\ 796 rsRetVal __attribute__((unused)) modInit##uniqName(int iIFVersRequested __attribute__((unused)), \ 797 int *ipIFVersProvided, rsRetVal (**pQueryEtryPt)(), rsRetVal (*pHostQueryEtryPt)(uchar*, rsRetVal (**)()), \ 798 modInfo_t __attribute__((unused)) *pModInfo)\ 799 {\ 800 DEFiRet; \ 801 rsRetVal (*pObjGetObjInterface)(obj_if_t *pIf); 802 803 #define CODESTARTmodInit \ 804 assert(pHostQueryEtryPt != NULL);\ 805 iRet = pHostQueryEtryPt((uchar*)"objGetObjInterface", &pObjGetObjInterface); \ 806 if((iRet != RS_RET_OK) || (pQueryEtryPt == NULL) || (ipIFVersProvided == NULL) || \ 807 (pObjGetObjInterface == NULL)) { \ 808 return (iRet == RS_RET_OK) ? RS_RET_PARAM_ERROR : iRet; \ 809 } \ 810 /* now get the obj interface so that we can access other objects */ \ 811 CHKiRet(pObjGetObjInterface(&obj)); 812 813 /* do those initializations necessary for legacy config variables */ 814 #define INITLegCnfVars \ 815 initConfVars(); 816 817 #define ENDmodInit \ 818 finalize_it:\ 819 *pQueryEtryPt = queryEtryPt;\ 820 RETiRet;\ 821 } 822 823 824 /* now come some check functions, which enable a standard way of obtaining feature 825 * information from the core. feat is the to-be-tested feature and featVar is a 826 * variable that receives the result (0-not support, 1-supported). 827 * This must be a macro, so that it is put into the output's code. Otherwise, we 828 * would need to rely on a library entry point, which is what we intend to avoid ;) 829 * rgerhards, 2009-04-27 830 */ 831 #define INITChkCoreFeature(featVar, feat) \ 832 { \ 833 rsRetVal MACRO_Ret; \ 834 rsRetVal (*pQueryCoreFeatureSupport)(int*, unsigned); \ 835 int bSupportsIt; \ 836 featVar = 0; \ 837 MACRO_Ret = pHostQueryEtryPt((uchar*)"queryCoreFeatureSupport", &pQueryCoreFeatureSupport); \ 838 if(MACRO_Ret == RS_RET_OK) { \ 839 /* found entry point, so let's see if core supports it */ \ 840 CHKiRet((*pQueryCoreFeatureSupport)(&bSupportsIt, feat)); \ 841 if(bSupportsIt) \ 842 featVar = 1; \ 843 } else if(MACRO_Ret != RS_RET_ENTRY_POINT_NOT_FOUND) { \ 844 ABORT_FINALIZE(MACRO_Ret); /* Something else went wrong, what is not acceptable */ \ 845 } \ 846 } 847 848 849 850 /* definitions for host API queries */ 851 #define CODEmodInit_QueryRegCFSLineHdlr \ 852 CHKiRet(pHostQueryEtryPt((uchar*)"regCfSysLineHdlr", &omsdRegCFSLineHdlr)); 853 854 855 /* modExit() 856 * This is the counterpart to modInit(). It destroys a module and makes it ready for 857 * unloading. It is similiar to freeInstance() for the instance data. Please note that 858 * this entry point needs to free any module-global data structures and registrations. 859 * For example, the CfSysLineHandlers a module has registered need to be unregistered 860 * here. This entry point is only called immediately before unloading of the module. So 861 * it is likely to be destroyed. HOWEVER, the caller may decide to keep the module cached. 862 * So a module must never assume that it is actually destroyed. A call to modInit() may 863 * happen immediately after modExit(). So a module can NOT assume that static data elements 864 * are being re-initialized by the loader - this must always be done by module code itself. 865 * It is suggested to do this in modInit(). - rgerhards, 2007-11-21 866 */ 867 #define BEGINmodExit \ 868 static rsRetVal modExit(void)\ 869 {\ 870 DEFiRet; 871 872 #define CODESTARTmodExit 873 874 #define ENDmodExit \ 875 RETiRet;\ 876 } 877 878 879 /* beginCnfLoad() 880 * This is a function tells an input module that a new config load begins. 881 * The core passes in a handle to the new module-specific module conf to 882 * the module. -- rgerards, 2011-05-03 883 */ 884 #define BEGINbeginCnfLoad \ 885 static rsRetVal beginCnfLoad(modConfData_t **ptr, __attribute__((unused)) rsconf_t *pConf)\ 886 {\ 887 modConfData_t *pModConf; \ 888 DEFiRet; 889 890 #define CODESTARTbeginCnfLoad \ 891 if((pModConf = calloc(1, sizeof(modConfData_t))) == NULL) {\ 892 *ptr = NULL;\ 893 return RS_RET_OUT_OF_MEMORY;\ 894 } 895 896 #define ENDbeginCnfLoad \ 897 *ptr = pModConf;\ 898 RETiRet;\ 899 } 900 901 902 /* setModCnf() 903 * This function permits to set module global parameters via the v2 config 904 * interface. It may be called multiple times, but parameters must not be 905 * set in a conflicting way. The module must use its current config load 906 * context when processing the directives. 907 * Note that lst may be NULL, especially if the module is loaded via the 908 * legacy config system. The module must check for this. 909 * NOTE: This entry point must only be implemented if module global 910 * parameters are actually required. 911 */ 912 #define BEGINsetModCnf \ 913 static rsRetVal setModCnf(struct nvlst *lst)\ 914 {\ 915 DEFiRet; 916 917 #define CODESTARTsetModCnf 918 919 #define ENDsetModCnf \ 920 RETiRet;\ 921 } 922 923 924 /* endCnfLoad() 925 * This is a function tells an input module that the current config load ended. 926 * It gets a last chance to make changes to its in-memory config object. After 927 * this call, the config object must no longer be changed. 928 * The pModConf pointer passed into the module must no longer be used. 929 * rgerards, 2011-05-03 930 */ 931 #define BEGINendCnfLoad \ 932 static rsRetVal endCnfLoad(modConfData_t *ptr)\ 933 {\ 934 modConfData_t __attribute__((unused)) *pModConf = (modConfData_t*) ptr; \ 935 DEFiRet; 936 937 #define CODESTARTendCnfLoad 938 939 #define ENDendCnfLoad \ 940 RETiRet;\ 941 } 942 943 944 /* checkCnf() 945 * Check the provided config object for errors, inconsistencies and other things 946 * that do not work out. 947 * NOTE: no part of the config must be activated, so some checks that require 948 * activation can not be done in this entry point. They must be done in the 949 * activateConf() stage, where the caller must also be prepared for error 950 * returns. 951 * rgerhards, 2011-05-03 952 */ 953 #define BEGINcheckCnf \ 954 static rsRetVal checkCnf(modConfData_t *ptr)\ 955 {\ 956 modConfData_t __attribute__((unused)) *pModConf = (modConfData_t*) ptr; \ 957 DEFiRet; 958 959 #define CODESTARTcheckCnf 960 961 #define ENDcheckCnf \ 962 RETiRet;\ 963 } 964 965 966 /* activateCnfPrePrivDrop() 967 * Initial config activation, before dropping privileges. This is an optional 968 * entry points that should only be implemented by those module that really need 969 * it. Processing should be limited to the minimum possible. Main activation 970 * should happen in the normal activateCnf() call. 971 * rgerhards, 2011-05-06 972 */ 973 #define BEGINactivateCnfPrePrivDrop \ 974 static rsRetVal activateCnfPrePrivDrop(modConfData_t *ptr)\ 975 {\ 976 modConfData_t *pModConf = (modConfData_t*) ptr; \ 977 DEFiRet; 978 979 #define CODESTARTactivateCnfPrePrivDrop 980 981 #define ENDactivateCnfPrePrivDrop \ 982 RETiRet;\ 983 } 984 985 986 /* activateCnf() 987 * This activates the provided config, and may report errors if they are detected 988 * during activation. 989 * rgerhards, 2011-05-03 990 */ 991 #define BEGINactivateCnf \ 992 static rsRetVal activateCnf(modConfData_t *ptr)\ 993 {\ 994 modConfData_t __attribute__((unused)) *pModConf = (modConfData_t*) ptr; \ 995 DEFiRet; 996 997 #define CODESTARTactivateCnf 998 999 #define ENDactivateCnf \ 1000 RETiRet;\ 1001 } 1002 1003 1004 /* freeCnf() 1005 * This is a function tells an input module that it must free all data 1006 * associated with the passed-in module config. 1007 * rgerhards, 2011-05-03 1008 */ 1009 #define BEGINfreeCnf \ 1010 static rsRetVal freeCnf(void *ptr)\ 1011 {\ 1012 modConfData_t *pModConf = (modConfData_t*) ptr; \ 1013 DEFiRet; 1014 1015 #define CODESTARTfreeCnf 1016 1017 #define ENDfreeCnf \ 1018 if(pModConf != NULL)\ 1019 free(pModConf); /* we need to free this in any case */\ 1020 RETiRet;\ 1021 } 1022 1023 1024 /* runInput() 1025 * This is the main function for input modules. It is used to gather data from the 1026 * input source and submit it to the message queue. Each runInput() instance has its own 1027 * thread. This is handled by the rsyslog engine. It needs to spawn off new threads only 1028 * if there is a module-internal need to do so. 1029 */ 1030 #define BEGINrunInput \ 1031 static rsRetVal runInput(thrdInfo_t __attribute__((unused)) *pThrd)\ 1032 {\ 1033 DEFiRet; 1034 1035 #define CODESTARTrunInput \ 1036 dbgSetThrdName((uchar*)__FILE__); /* we need to provide something better later */ 1037 1038 #define ENDrunInput \ 1039 RETiRet;\ 1040 } 1041 1042 1043 /* willRun() 1044 * This is a function that will be replaced in the longer term. It is used so 1045 * that a module can tell the caller if it will run or not. This is to be replaced 1046 * when we introduce input module instances. However, these require config syntax 1047 * changes and I may (or may not... ;)) hold that until another config file 1048 * format is available. -- rgerhards, 2007-12-17 1049 * returns RS_RET_NO_RUN if it will not run (RS_RET_OK or error otherwise) 1050 */ 1051 #define BEGINwillRun \ 1052 static rsRetVal willRun(void)\ 1053 {\ 1054 DEFiRet; 1055 1056 #define CODESTARTwillRun 1057 1058 #define ENDwillRun \ 1059 RETiRet;\ 1060 } 1061 1062 1063 /* afterRun() 1064 * This function is called after an input module has been run and its thread has 1065 * been terminated. It shall do any necessary cleanup. 1066 * This is expected to evolve into a freeInstance type of call once the input module 1067 * interface evolves to support multiple instances. 1068 * rgerhards, 2007-12-17 1069 */ 1070 #define BEGINafterRun \ 1071 static rsRetVal afterRun(void)\ 1072 {\ 1073 DEFiRet; 1074 1075 #define CODESTARTafterRun 1076 1077 #define ENDafterRun \ 1078 RETiRet;\ 1079 } 1080 1081 1082 /* doHUP() 1083 * This function is optional. Currently, it is available to output plugins 1084 * only, but may be made available to other types of plugins in the future. 1085 * A plugin does not need to define this entry point. If if does, it gets 1086 * called when a HUP at the action level is to be done. A plugin should register 1087 * this function so that it can close files, connection or other ressources 1088 * on HUP - if it can be assume the user wanted to do this as a part of HUP 1089 * processing. Note that the name "HUP" has historical reasons, it stems back 1090 * to the infamous SIGHUP which was sent to restart a syslogd. We still retain 1091 * that legacy, but may move this to a different signal. 1092 * rgerhards, 2008-10-22 1093 */ 1094 #define CODEqueryEtryPt_doHUP \ 1095 else if(!strcmp((char*) name, "doHUP")) {\ 1096 *pEtryPoint = doHUP;\ 1097 } 1098 #define BEGINdoHUP \ 1099 static rsRetVal doHUP(instanceData __attribute__((unused)) *pData)\ 1100 {\ 1101 DEFiRet; 1102 1103 #define CODESTARTdoHUP 1104 1105 #define ENDdoHUP \ 1106 RETiRet;\ 1107 } 1108 1109 1110 /* doHUPWrkr() 1111 * This is like doHUP(), but on an action worker level. 1112 * rgerhards, 2015-03-25 1113 */ 1114 #define CODEqueryEtryPt_doHUPWrkr \ 1115 else if(!strcmp((char*) name, "doHUPWrkr")) {\ 1116 *pEtryPoint = doHUPWrkr;\ 1117 } 1118 #define BEGINdoHUPWrkr \ 1119 static rsRetVal doHUPWrkr(wrkrInstanceData_t __attribute__((unused)) *pWrkrData)\ 1120 {\ 1121 DEFiRet; 1122 1123 #define CODESTARTdoHUPWrkr 1124 1125 #define ENDdoHUPWrkr \ 1126 RETiRet;\ 1127 } 1128 1129 1130 /* SetShutdownImmdtPtr() 1131 * This function is optional. If defined by an output plugin, it is called 1132 * each time the action is invoked to set the "ShutdownImmediate" pointer, 1133 * which is used during termination to indicate the action should shutdown 1134 * as quickly as possible. 1135 */ 1136 #define CODEqueryEtryPt_SetShutdownImmdtPtr \ 1137 else if(!strcmp((char*) name, "SetShutdownImmdtPtr")) {\ 1138 *pEtryPoint = SetShutdownImmdtPtr;\ 1139 } 1140 #define BEGINSetShutdownImmdtPtr \ 1141 static rsRetVal SetShutdownImmdtPtr(instanceData __attribute__((unused)) *pData, int *pPtr)\ 1142 {\ 1143 DEFiRet; 1144 1145 #define CODESTARTSetShutdownImmdtPtr 1146 1147 #define ENDSetShutdownImmdtPtr \ 1148 RETiRet;\ 1149 } 1150 1151 1152 /* parse() - main entry point of parser modules (v1 config interface) 1153 */ 1154 #define BEGINparse \ 1155 static rsRetVal parse(smsg_t *pMsg)\ 1156 {\ 1157 DEFiRet; 1158 1159 #define CODESTARTparse \ 1160 assert(pMsg != NULL); 1161 1162 #define ENDparse \ 1163 RETiRet;\ 1164 } 1165 1166 1167 /* parse2() - main entry point of parser modules (v2+ config interface) 1168 */ 1169 #define BEGINparse2 \ 1170 static rsRetVal parse2(instanceConf_t *const pInst, smsg_t *pMsg)\ 1171 {\ 1172 DEFiRet; 1173 1174 #define CODESTARTparse2 \ 1175 assert(pInst != NULL);\ 1176 assert(pMsg != NULL); 1177 1178 #define ENDparse2 \ 1179 RETiRet;\ 1180 } 1181 1182 1183 /* strgen() - main entry point of parser modules 1184 * Note that we do NOT use size_t as this permits us to store the 1185 * values directly into optimized heap structures. 1186 * ppBuf is the buffer pointer 1187 * pLenBuf is the current max size of this buffer 1188 * pStrLen is an output parameter that MUST hold the length 1189 * of the generated string on exit (this is cached) 1190 */ 1191 #define BEGINstrgen \ 1192 static rsRetVal strgen(smsg_t *const pMsg, actWrkrIParams_t *const iparam) \ 1193 {\ 1194 DEFiRet; 1195 1196 #define CODESTARTstrgen \ 1197 assert(pMsg != NULL); 1198 1199 #define ENDstrgen \ 1200 RETiRet;\ 1201 } 1202 1203 1204 1205 /* getFunctArray() - main entry point of parser modules 1206 * Note that we do NOT use size_t as this permits us to store the 1207 * values directly into optimized heap structures. 1208 * ppBuf is the buffer pointer 1209 * pLenBuf is the current max size of this buffer 1210 * pStrLen is an output parameter that MUST hold the length 1211 * of the generated string on exit (this is cached) 1212 */ 1213 #define BEGINgetFunctArray \ 1214 static rsRetVal getFunctArray(int *const version, const struct scriptFunct**const functArray) \ 1215 {\ 1216 DEFiRet; 1217 1218 #define CODESTARTgetFunctArray 1219 1220 #define ENDgetFunctArray \ 1221 RETiRet;\ 1222 } 1223 1224 1225 /* function to specify the parser name. This is done via a single command which 1226 * receives a ANSI string as parameter. 1227 */ 1228 #define PARSER_NAME(x) \ 1229 static rsRetVal GetParserName(uchar **ppSz)\ 1230 {\ 1231 *ppSz = UCHAR_CONSTANT(x);\ 1232 return RS_RET_OK;\ 1233 } 1234 1235 1236 1237 /* function to specify the strgen name. This is done via a single command which 1238 * receives a ANSI string as parameter. 1239 */ 1240 #define STRGEN_NAME(x) \ 1241 static rsRetVal GetStrgenName(uchar **ppSz)\ 1242 {\ 1243 *ppSz = UCHAR_CONSTANT(x);\ 1244 return RS_RET_OK;\ 1245 } 1246 1247 #endif /* #ifndef MODULE_TEMPLATE_H_INCLUDED */ 1248 1249 /* vim:set ai: 1250 */ 1251