Annotation of embedaddon/libpdel/tmpl/tmpl.3, revision 1.1
1.1 ! misho 1: .\" Copyright (c) 2001-2002 Packet Design, LLC.
! 2: .\" All rights reserved.
! 3: .\"
! 4: .\" Subject to the following obligations and disclaimer of warranty,
! 5: .\" use and redistribution of this software, in source or object code
! 6: .\" forms, with or without modifications are expressly permitted by
! 7: .\" Packet Design; provided, however, that:
! 8: .\"
! 9: .\" (i) Any and all reproductions of the source or object code
! 10: .\" must include the copyright notice above and the following
! 11: .\" disclaimer of warranties; and
! 12: .\" (ii) No rights are granted, in any manner or form, to use
! 13: .\" Packet Design trademarks, including the mark "PACKET DESIGN"
! 14: .\" on advertising, endorsements, or otherwise except as such
! 15: .\" appears in the above copyright notice or in the software.
! 16: .\"
! 17: .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
! 18: .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
! 19: .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
! 20: .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
! 21: .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
! 22: .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
! 23: .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
! 24: .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
! 25: .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
! 26: .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
! 27: .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
! 28: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
! 29: .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
! 30: .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
! 31: .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
! 32: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
! 33: .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
! 34: .\" THE POSSIBILITY OF SUCH DAMAGE.
! 35: .\"
! 36: .\" Author: Archie Cobbs <archie@freebsd.org>
! 37: .\"
! 38: .\" $Id: tmpl.3,v 1.13 2004/06/02 17:24:38 archie Exp $
! 39: .\"
! 40: .Dd April 22, 2002
! 41: .Dt TMPL 3
! 42: .Os
! 43: .Sh NAME
! 44: .Nm tmpl
! 45: .Nd templates
! 46: .Sh LIBRARY
! 47: PDEL Library (libpdel, \-lpdel)
! 48: .Sh SYNOPSIS
! 49: .Ft "struct tmpl *"
! 50: .Fn tmpl_create "FILE *input" "int *num_errors" "const char *mtype"
! 51: .Ft "struct tmpl *"
! 52: .Fn tmpl_create_mmap "const char *path" "int *num_errors" "const char *mtype"
! 53: .Ft void
! 54: .Fn tmpl_destroy "struct tmpl **tmplp"
! 55: .Ft "struct tmpl_ctx *"
! 56: .Fn tmpl_ctx_create "void *arg" "const char *mtype" "tmpl_handler_t *handler" "tmpl_errfmtr_t *errfmtr"
! 57: .Ft "void *"
! 58: .Fn tmpl_ctx_get_arg "struct tmpl_ctx *ctx"
! 59: .Ft "const char *"
! 60: .Fn tmpl_ctx_get_mtype "struct tmpl_ctx *ctx"
! 61: .Ft "const char *"
! 62: .Fn tmpl_ctx_get_var "struct tmpl_ctx *ctx" "const char *name"
! 63: .Ft "int"
! 64: .Fn tmpl_ctx_set_var "struct tmpl_ctx *ctx" "const char *name" "const char *value"
! 65: .Ft "char *"
! 66: .Fn tmpl_list_handler "struct tmpl_ctx *ctx" "const struct tmpl_func *userfuncs" "u_int uflen" "char **errmsgp" "int argc" "char **argv"
! 67: .Ft void
! 68: .Fn tmpl_ctx_destroy "struct tmpl_ctx **ctxp"
! 69: .Ft int
! 70: .Fn tmpl_execute "struct tmpl *tmpl" "struct tmpl_ctx *ctx" "FILE *output" "int flags"
! 71: .Ft int
! 72: .Fn tmpl_execute_func "struct tmpl_ctx *ctx" "FILE *output" "char **errmsgp" "int argc" "char **argv" "int flags"
! 73: .Ft void
! 74: .Fn tmpl_ctx_reset "struct tmpl_ctx *ctx"
! 75: .Sh DESCRIPTION
! 76: .\"
! 77: .Ss Overview
! 78: .\"
! 79: The
! 80: .Nm tmpl
! 81: library supports programmatic generation of output
! 82: based on input from
! 83: .Nm tmpl
! 84: template files.
! 85: Output is generated by parsing and then executing a tmpl file.
! 86: .Pp
! 87: The tmpl file simply contains the desired output, with invocations
! 88: of various tmpl functions, denoted by the
! 89: .Dq @
! 90: character, interspersed.
! 91: Tmpl functions take zero or more arguments, where each argument can
! 92: be either a doubly-quoted string or another, nested tmpl function.
! 93: .Pp
! 94: When executed, the output of a tmpl file is simply the contents of the
! 95: file, with each tmpl function replaced by the value returned by that function.
! 96: Several functions, including control flow constructs, are built-in,
! 97: and compile-time and run-time user defined functions are supported.
! 98: .Pp
! 99: Here is a simple example tmpl input file:
! 100: .Pp
! 101: .Bd -literal -compact -offset 3n
! 102: I'm going to count to three:
! 103:
! 104: @set("i", "1")
! 105: @while(@le(@get("i"), "3"))
! 106: @get("i")
! 107: @set("i", @add(@get("i"), "1"))
! 108: @endwhile
! 109:
! 110: Done.
! 111: .Ed
! 112: .Pp
! 113: If this template were executed, the output would be:
! 114: .Bd -literal -offset 3n
! 115: I'm going to count to three:
! 116:
! 117:
! 118:
! 119: 1
! 120:
! 121: 2
! 122:
! 123: 3
! 124:
! 125:
! 126:
! 127: Done.
! 128: .Ed
! 129: .Pp
! 130: While the example above uses only built-in functions, user-defined functions
! 131: written in C may be invoked in the same way.
! 132: .\"
! 133: .Sh Parsing
! 134: .\"
! 135: This section describes the precise rules that govern how
! 136: .Nm tmpl
! 137: files are parsed.
! 138: .Pp
! 139: A tmpl file is parsed by scanning for special function calls.
! 140: A function call is an at sign ('@') followed by a contiguous sequence
! 141: of letters, digits, and underscores, followed by matching parentheses
! 142: containing zero or more function arguments.
! 143: The text between functions calls is ignored (it doesn't even have to
! 144: be text).
! 145: .Pp
! 146: Function arguments may be either other nested function calls (the argument
! 147: to the outer function is the result of the inner function invocation),
! 148: or constant literal strings in double quotes (the argument is the
! 149: value of the string).
! 150: Therefore, all function arguments begin with either an at sign or
! 151: a double quote character.
! 152: Function arguments are separated by commas and may have surrounding
! 153: whitespace, which is ignored.
! 154: .Pp
! 155: Constant literal strings are enclosed in double quotes and respect the
! 156: usual C backslash escapes.
! 157: .Pp
! 158: Built-in functions (see below) that take zero arguments do not require
! 159: parentheses, but parentheses may be included for separation purposes.
! 160: .Pp
! 161: A parsed tmpl file is represented by a
! 162: .Li "struct tmpl" .
! 163: .\"
! 164: .Sh Execution
! 165: .\"
! 166: .Pp
! 167: The parsing of a tmpl file and its execution are separate steps.
! 168: Once a tmpl file has been parsed, it may be executed several times.
! 169: Execution requires a
! 170: .Em context ,
! 171: represented by a
! 172: .Li "struct tmpl_ctx" ,
! 173: and generates output which is written to an output stream.
! 174: .Pp
! 175: When the template is executed, the text between function calls is
! 176: copied to the output stream without modification, while the function
! 177: calls are replaced with their values, which are strings.
! 178: Functions are evaluated as they are encountered during execution.
! 179: .Pp
! 180: The
! 181: .Nm tmpl
! 182: library includes several built-in functions, including
! 183: special control flow functions that control input processing.
! 184: The user code may also implement custom functions.
! 185: .Pp
! 186: User functions may return
! 187: .Dv NULL
! 188: and set
! 189: .Va errno
! 190: to indicate an error; they may also set an error string (if
! 191: no error string is set,
! 192: .Xr strerror 3
! 193: is used to generate one).
! 194: When such an error occurs, the function does not return at all.
! 195: Instead, an error message is propagated up to the outer-most function call.
! 196: The error message is reformatted by an optional user-supplied error
! 197: formatter function, and then the formatted message is written
! 198: to the output stream.
! 199: .\"
! 200: .Sh Built-in Functions
! 201: .\"
! 202: The built-in functions are listed below.
! 203: In these definitions, the numeric value of a string is the result
! 204: of parsing it with
! 205: .Xr strtol 3 ,
! 206: and a string is considered "true" if it has a numeric value other than zero.
! 207: .Pp
! 208: .Bl -hang -compact -width "xx"
! 209: .It Em "Control flow"
! 210: .Bl -hang -width "xx"
! 211: .It Li "@while(x) ... @endwhile"
! 212: .Pp
! 213: The text in between is repeated as long as the argument supplied to
! 214: .Li "@while()"
! 215: is true.
! 216: .It Li "@loop(x) ... @endloop"
! 217: .Pp
! 218: The text in between is repeated N times, where N is the numerical value
! 219: of the argument passed to
! 220: .Li "@loop()" .
! 221: .It Li "@loopindex(x)"
! 222: .Pp
! 223: Takes zero or one argument; returns the loop index (counting from zero)
! 224: of the loop that is N loops out from the innermost containing loop, where
! 225: N is the numerical value of the argument, or -1 if no such loop exists.
! 226: If the argument is omitted it is assumed to be zero.
! 227: .It Li "@if(x) ... [ @elif(y) ... ] [ @else ... ] @endif"
! 228: .Pp
! 229: Conditional execution depending on the truth value of the argument to
! 230: .Li "@if()" .
! 231: Zero or more
! 232: .Li "@elif()"
! 233: blocks may be followed by zero or one
! 234: .Li "@else"
! 235: block.
! 236: An
! 237: .Li "@endif"
! 238: is always required.
! 239: .It Li "@break()"
! 240: .Pp
! 241: Break out of the innermost enclosing
! 242: .Li "@loop"
! 243: or
! 244: .Li "@while" .
! 245: .It Li "@continue()"
! 246: .Pp
! 247: Continue with the next iteration of the nearest enclosing
! 248: .Li "@loop"
! 249: or
! 250: .Li "@while" .
! 251: .It Li "@return()"
! 252: .Pp
! 253: Return from within a run-time function.
! 254: .It Li "@eval(x)
! 255: .Pp
! 256: Parses the argument as a template, executes it, and returns the resulting
! 257: output.
! 258: .El
! 259: .Pp
! 260: .It Em "Run-time variables and functions"
! 261: .Bl -hang -width "xx"
! 262: .It Li "@set(name, value)"
! 263: .Pp
! 264: Sets the run-time variable named by the first argument to have the
! 265: value equal to the second argument.
! 266: All run-time variables are global and exist as long as the associated
! 267: execution context exists.
! 268: .It Li "@get(name)"
! 269: .Pp
! 270: Returns the value of the run-time variable named by the first argument,
! 271: or the empty string if the variable is not set.
! 272: .It Li "@define(name) ... @enddef"
! 273: .Pp
! 274: Defines a run-time function.
! 275: The text in between is executed whenever @name(...) is invoked.
! 276: During this execution, the variables
! 277: .Fa argc
! 278: and
! 279: .Fa arg0 ,
! 280: .Fa arg1 ,
! 281: \&... are set to the function argument count and arguments, respectively;
! 282: .Fa arg0
! 283: is always equal to the name of the function.
! 284: All run-time functions are global and exist as long as the associated
! 285: execution context exists.
! 286: .It Li "@invoke()
! 287: .Pp
! 288: Invokes a function.
! 289: The function to be invoked and its arguments are described by the
! 290: run-time variables
! 291: .Fa argc
! 292: and
! 293: .Fa arg0 ,
! 294: .Fa arg1 ,
! 295: \&...
! 296: as above.
! 297: So
! 298: .Fa arg0
! 299: is the function name and
! 300: .Fa arg0 ,
! 301: .Fa arg1 ,
! 302: \&...
! 303: are the function arguments.
! 304: @invoke() itself does not take any arguments.
! 305: .El
! 306: .Pp
! 307: .It Em "Evaluators"
! 308: .Bl -hang -width "xx"
! 309: .It Li "@equal(x, y)"
! 310: .Pp
! 311: Returns "1" if x and y are identical, otherwise "0".
! 312: .It Li "@not(x)"
! 313: .Pp
! 314: Returns "1" if x is false, otherwise "0".
! 315: .It Li "@and(...)"
! 316: .Pp
! 317: Returns "1" if all of the arguments are true, otherwise "0".
! 318: .It Li "@or(...)"
! 319: .Pp
! 320: Returns "1" if any of the arguments is true, otherwise "0".
! 321: .It Li "@add(...)"
! 322: .Pp
! 323: Returns the sum of the arguments.
! 324: .It Li "@sub(x, ...)"
! 325: .Pp
! 326: Returns the second and subsequent arguments subtracted from the first.
! 327: .It Li "@mul(...)"
! 328: .Pp
! 329: Returns the product of the arguments.
! 330: .It Li "@div(x, y)"
! 331: .Pp
! 332: Returns the first argument divided by the second.
! 333: .It Li "@mod(x, y)"
! 334: .Pp
! 335: Returns the first argument modulo the second.
! 336: .It Li "@lt(x, y)"
! 337: .Pp
! 338: Returns "1" if the first argument is less than the second, otherwise "0".
! 339: .It Li "@le(x, y)"
! 340: .Pp
! 341: Returns "1" if the first argument is less than or equal to the second,
! 342: otherwise "0".
! 343: .It Li "@gt(x, y)"
! 344: .Pp
! 345: Returns "1" if the first argument is greater than the second, otherwise "0".
! 346: .It Li "@ge(x, y)"
! 347: .Pp
! 348: Returns "1" if the first argument is greater than or equal to the second,
! 349: otherwise "0".
! 350: .El
! 351: .Pp
! 352: .It Em "String functions"
! 353: .Bl -hang -width "xx"
! 354: .It Li "@cat(...)"
! 355: .Pp
! 356: Returns the concatenation of all of the arguments.
! 357: .It Li "@@()"
! 358: .Pp
! 359: Returns "@".
! 360: .It Li "@error(arg)
! 361: .Pp
! 362: Returns the argument formatted using the caller-supplied error formatter.
! 363: .It Li "@htmlencode(arg)
! 364: .Pp
! 365: Encodes the argument with HTML escapes and returns the result.
! 366: .It Li "@urlencode(arg)
! 367: .Pp
! 368: Encodes the argument with URL escapes and returns the result.
! 369: .El
! 370: .Pp
! 371: .It Em "I/O functions"
! 372: .Bl -hang -width "xx"
! 373: .It Li "@flush()
! 374: .Pp
! 375: Flushes the output stream.
! 376: .It Li "@output(arg)
! 377: .Pp
! 378: Outputs the argument directly to the output stream. That is,
! 379: if this function is invoked from within a user-defined function,
! 380: the argument goes directly to the template output rather than
! 381: being concatenated to the return value of the function.
! 382: .El
! 383: .Pp
! 384: .El
! 385: .\"
! 386: .Sh API
! 387: .\"
! 388: .Fn tmpl_create
! 389: parses input from
! 390: .Fa input
! 391: and creates and returns a new template object,
! 392: which uses
! 393: .Xr typed_mem 3
! 394: type
! 395: .Fa mtype .
! 396: If
! 397: .Fa num_errors
! 398: is not
! 399: .Dv NULL ,
! 400: then the number of parse errors detected is stored in
! 401: .Fa "*num_errors" .
! 402: A parse error is an occurrence of the
! 403: .Dq @
! 404: character that is not the beginning of a well-formed
! 405: .Nm
! 406: function invocation.
! 407: .Pp
! 408: .Fn tmpl_create_mmap
! 409: parses the contents of the file named
! 410: .Fa path ,
! 411: using
! 412: .Xr mmap 2
! 413: internally to avoid having to store the entire file in memory.
! 414: This results in less memory being used; however, if the file's contents
! 415: are changed then subsequent invocations of
! 416: .Fn tmpl_execute
! 417: may give garbled output.
! 418: .Pp
! 419: .Fn tmpl_destroy
! 420: destroys a template object.
! 421: Upon return,
! 422: .Fa "*tmplp"
! 423: will be set to
! 424: .Dv NULL .
! 425: If
! 426: .Fa "*tmplp"
! 427: is already
! 428: .Dv NULL
! 429: when
! 430: .Fn tmpl_destroy
! 431: is invoked, nothing happens.
! 432: .Pp
! 433: .Fn tmpl_ctx_create
! 434: creates a new template execution context.
! 435: .Fa mtype
! 436: is the
! 437: .Xr typed_mem 3
! 438: type used not only for the execution context object itself, but also
! 439: for all strings generated during execution.
! 440: In particular, all strings returned by user functions must be stored
! 441: in buffers allocated with this type.
! 442: The
! 443: .Fa arg
! 444: is a user cookie ignored by the
! 445: .Nm tmpl
! 446: functions.
! 447: The parameters
! 448: .Fa arg
! 449: and
! 450: .Fa mtype
! 451: may be retrieved with
! 452: .Fn tmpl_ctx_get_arg
! 453: and
! 454: .Fn tmpl_ctx_get_mtype ,
! 455: respectively.
! 456: .Pp
! 457: .Fa handler
! 458: and
! 459: .Fa errfmtr
! 460: point to functions having these types:
! 461: .Pp
! 462: .Bd -literal -compact -offset 3n
! 463: typedef char *tmpl_handler_t(struct tmpl_ctx *ctx, char **errmsgp,
! 464: int argc, char **argv);
! 465: typedef char *tmpl_errfmtr_t(struct tmpl_ctx *ctx, const char *errmsg);
! 466: .Ed
! 467: .Pp
! 468: .Fn handler
! 469: returns the result of invoking the function described by
! 470: .Fa argc
! 471: and
! 472: .Fa argv
! 473: as a '\\0'-terminated string allocated with the
! 474: .Xr typed_mem 3
! 475: type
! 476: .Fa mtype .
! 477: The first argument is always the function name, and subsequent arguments
! 478: are the (evaluated) arguments passed to the function.
! 479: Therefore,
! 480: .Fa argc
! 481: is always at least one.
! 482: .Pp
! 483: .Fn handler
! 484: may indicate an error by returning
! 485: .Dv NULL ,
! 486: in which case it should either set
! 487: .Va errno
! 488: appropriately or else set
! 489: .Fa "*errmsgp"
! 490: to point to an error message (which should also be allocated with
! 491: .Xr typed_mem 3
! 492: type
! 493: .Fa mtype) ;
! 494: .Fa "*errmsgp"
! 495: will be
! 496: .Dv NULL
! 497: when
! 498: .Fn handler
! 499: is invoked.
! 500: .Pp
! 501: The error formatter function
! 502: .Fn errfmtr
! 503: is optional.
! 504: It should return an error string allocated with
! 505: .Xr typed_mem 3
! 506: type
! 507: .Fa mtype
! 508: and formatted appropriately for the template output
! 509: (e.g., in HTML).
! 510: The
! 511: .Fa errmsg
! 512: is the original, unformatted error string returned by the function handler;
! 513: if the handler did not return an explicit error message,
! 514: .Li "strerror(errno)"
! 515: is used for
! 516: .Fa errmsg .
! 517: .Pp
! 518: .Fn tmpl_list_handler
! 519: may be useful for implementing
! 520: .Fn handler
! 521: when there is a fixed list of user functions.
! 522: The
! 523: .Fa userfuncs
! 524: parameter points to a length
! 525: .Fa uflen
! 526: array of
! 527: .Li "struct tmpl_func" :
! 528: .Pp
! 529: .Bd -literal -compact -offset 3n
! 530: struct tmpl_func {
! 531: const char *name; /* function name, null to end list */
! 532: u_int min_args; /* min # args (not counting name) */
! 533: u_int max_args; /* max # args (not counting name) */
! 534: tmpl_handler_t *handler; /* handler for function */
! 535: };
! 536: .Ed
! 537: .Pp
! 538: Each entry in the array describes a user function.
! 539: The function called
! 540: .Fa name
! 541: accepts at least
! 542: .Fa min_args
! 543: and at most
! 544: .Fa max_args
! 545: parameters, and is implemented by the
! 546: .Fa handler .
! 547: The array must be sorted lexicographically by name.
! 548: .Fn tmpl_list_handler
! 549: finds the function named by
! 550: .Li "argv[0]"
! 551: using a binary search of the array and invokes its
! 552: .Fn handler
! 553: with the supplied arguments.
! 554: In the case of an error,
! 555: .Fn tmpl_list_handler
! 556: prepends the returned error string with the offending function call
! 557: and arguments.
! 558: .Pp
! 559: .Fn tmpl_ctx_set_var
! 560: and
! 561: .Fn tmpl_ctx_get_var
! 562: may be used to set and retrieve variables associated with
! 563: .Fa ctx .
! 564: .Pp
! 565: .Fn tmpl_ctx_destroy
! 566: destroys a template context.
! 567: Upon return,
! 568: .Fa "*ctxp"
! 569: will be set to
! 570: .Dv NULL .
! 571: If
! 572: .Fa "*ctxp"
! 573: is already
! 574: .Dv NULL
! 575: when
! 576: .Fn tmpl_ctx_destroy
! 577: is invoked, nothing happens.
! 578: .Pp
! 579: .Fn tmpl_execute
! 580: executes the parsed template
! 581: .Fa tmpl
! 582: using the execution context
! 583: .Fa ctx ,
! 584: and writes the output to
! 585: .Fa output .
! 586: .Fa flags
! 587: may contain any of the following values OR'd together:
! 588: .Pp
! 589: .Bd -literal -compact -offset 3n
! 590: TMPL_SKIP_NL_WHITE Skip newline plus whitespace
! 591: .Ed
! 592: .Pp
! 593: .Dv TMPL_SKIP_NL_WHITE
! 594: causes any inter-function occurrences of a newline followed by whitespace
! 595: to be ignored.
! 596: This often generates more intuitive output.
! 597: The example template given previously would generate this output if
! 598: .Dv TMPL_SKIP_NL_WHITE
! 599: were specified:
! 600: .Pp
! 601: .Bd -literal -compact -offset 3n
! 602: I'm going to count to three:
! 603:
! 604: 123
! 605:
! 606: Done.
! 607: .Ed
! 608: .Pp
! 609: .Fn tmpl_execute_func
! 610: can be used to execute a single function defined in a template context.
! 611: This includes non-control flow built-in functions, user functions, and
! 612: run-time functions.
! 613: .Fa ctx ,
! 614: .Fa output ,
! 615: and
! 616: .Fa flags
! 617: are as with
! 618: .Fn tmpl_execute .
! 619: The function and arguments are described by
! 620: .Fa argc
! 621: and
! 622: .Fa argv ,
! 623: and
! 624: .Fa errmsgp
! 625: must point to a
! 626: .Li "char *"
! 627: error message pointer.
! 628: .Pp
! 629: .Fn tmpl_ctx_reset
! 630: resets an execution context to its initial state.
! 631: This causes any runtime variables and functions defined during a previous
! 632: execution using
! 633: .Fa ctx
! 634: to be forgotten.
! 635: .Sh RETURN VALUES
! 636: .Fn tmpl_create ,
! 637: .Fn tmpl_ctx_create ,
! 638: and
! 639: .Fn tmpl_execute
! 640: return
! 641: .Dv NULL
! 642: or -1 to indicate an error, with
! 643: .Va errno
! 644: set appropriately.
! 645: .Pp
! 646: .Fn tmpl_execute_func
! 647: returns -1 if there was an error.
! 648: In the case of a system error,
! 649: .Fa "*errmsgp"
! 650: will be set to
! 651: .Dv NULL
! 652: and
! 653: .Va errno
! 654: will be set appropriately; otherwise,
! 655: .Fa "*errmsgp"
! 656: will point to an appropriate error message allocated with
! 657: .Xr typed_mem 3
! 658: type
! 659: .Fa mtype ,
! 660: which the caller must eventually free.
! 661: .Sh SEE ALSO
! 662: .Xr http_servlet_tmpl 3 ,
! 663: .Xr libpdel 3 ,
! 664: .Xr strtol 3 ,
! 665: .Xr typed_mem 3
! 666: .Sh IMPLEMENTATION NOTES
! 667: Here are two common sources of bugs:
! 668: .Pp
! 669: .Bl -dash -compact -offset 3n
! 670: .It
! 671: User functions returning constant strings or strings allocated
! 672: with the wrong
! 673: .Xr typed_mem 3
! 674: type.
! 675: .It
! 676: Not sorting the user function array given to
! 677: .Fn tmpl_list_handler .
! 678: .El
! 679: .Sh HISTORY
! 680: The PDEL library was developed at Packet Design, LLC.
! 681: .Dv "http://www.packetdesign.com/"
! 682: .Sh AUTHORS
! 683: .An Archie Cobbs Aq archie@freebsd.org
! 684: .Sh BUGS
! 685: .Fn tmpl_create ,
! 686: .Fn tmpl_execute ,
! 687: and
! 688: .Fn tmpl_execute_func
! 689: may leak small amounts of memory if the thread is canceled.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to tmpl.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / tmpl