Return to libpdel.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel

libpdel

    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: libpdel.3,v 1.1.1.1 2012/02/21 23:25:53 misho Exp $
   39: .\"
   40: .Dd April 22, 2002
   41: .Dt LIBPDEL 3
   42: .Os
   43: .Sh NAME
   44: .Nm libpdel
   45: .Nd multi-purpose C library for embedded applications
   46: .Sh LIBRARY
   47: PDEL Library (libpdel, \-lpdel)
   48: .Sh DESCRIPTION
   49: The Packet Design Embedded Library (PDEL) is a C library containing
   50: an assorted collection of code useful for developing embedded
   51: applications:
   52: .Pp
   53: .Bl -dash -compact
   54: .It
   55: C data structure run-time introspection library:
   56: .Xr structs 3
   57: .Bl -dash -compact
   58: .It
   59: Support for automated conversion to/from XML
   60: .It
   61: Pre-defined types for most C data structures
   62: .El
   63: .It
   64: Threaded HTTP client/server library:
   65: .Xr http_server 3
   66: .Bl -dash -compact
   67: .It
   68: SSL support
   69: .It
   70: User-definable C "servlets":
   71: .Xr http_servlet 3
   72: .It
   73: Several pre-defined servlets
   74: .It
   75: Support for XML/HTTP and XML-RPC:
   76: .Xr http_xml 3
   77: .El
   78: .It
   79: PPP stack library (FreeBSD only):
   80: .Xr pdel_ppp 3
   81: .Bl -dash -compact
   82: .It
   83: Netgraph(4) based for kernel data packet handling
   84: .It
   85: Servers for PPTP and L2TP
   86: .El
   87: .It
   88: Application configuration framework:
   89: .Xr app_config 3
   90: .It
   91: Heap memory accounting and sanity checking:
   92: .Xr typed_mem 3
   93: .It
   94: File template library:
   95: .Xr tmpl 3
   96: .It
   97: Routines to configure networking interfaces, ARP table,
   98: and routing table (FreeBSD only):
   99: .Xr if_util 3 ,
  100: .Xr route_msg 3 ,
  101: .Xr uroute 3
  102: .It
  103: Logging library:
  104: .Xr alog 3
  105: .Bl -dash -compact
  106: .It
  107: Automated storage into circular file:
  108: .Xr logfile 3
  109: .It
  110: .Xr syslog 3 
  111: compatibile
  112: .El
  113: .It
  114: Generic TCP server:
  115: .Xr tcp_server 3
  116: .It
  117: Generic hash table implementation:
  118: .Xr ghash 3
  119: .It
  120: Generic balanced tree implementation:
  121: .Xr gtree 3
  122: .It
  123: .Vt "FILE *"
  124: enhancements:
  125: .Bl -dash -compact
  126: .It
  127: Generic data "filters":
  128: .Xr filter_fopen 3
  129: .It
  130: MIME boundary input streams:
  131: .Xr boundary_fopen 3
  132: .It
  133: Fixed length input streams:
  134: .Xr count_fopen 3
  135: .It
  136: String buffer input/output streams:
  137: .Xr string_fp 3
  138: .It
  139: Timeout streams:
  140: .Xr timeout_fdopen 3
  141: .It
  142: SSL streams:
  143: .Xr ssl_fp 3
  144: .El
  145: .It
  146: Base-64 encoding/decoding:
  147: .Xr base64 3
  148: .It
  149: Events and actions with automated locking:
  150: .Xr paction 3 ,
  151: .Xr pevent 3
  152: .It
  153: Generalized per-thread variables:
  154: .Xr tinfo 3
  155: .It
  156: Message ports:
  157: .Xr mesg_port 3
  158: .It
  159: Digital signature creation/verification:
  160: .Xr rsa_util_sign 3
  161: .It
  162: Filesystem mounting/unmounting (FreeBSD only):
  163: .Xr fs_mount 3
  164: .It
  165: String quoting/parsing:
  166: .Xr string_enquote 3
  167: .El
  168: .Pp
  169: For more details, see the individual man pages referenced above.
  170: .Sh REQUIREMENTS
  171: Unlike Java, libraries written in C cannot presume a commonly accepted
  172: standard for handling certain issues like threading and heap allocation.
  173: Therefore,
  174: .Nm libpdel
  175: makes certain assumptions which user code must follow.
  176: .Pp
  177: First, all heap memory in
  178: .Nm libpdel
  179: is allocated through the
  180: .Xr typed_mem 3
  181: typed memory system.
  182: Participation by user code in this system is optional, but it
  183: must be done, or not done, consistently.
  184: .Pp
  185: The
  186: .Nm libpdel
  187: library assumes that
  188: .Xr pthread 3
  189: is used for user-level threading.
  190: In general,
  191: .Nm libpdel
  192: objects are not safe to be called simultaneously from separate threads,
  193: or re-entrantly from the same thread, except where explicitly documented.
  194: For example, the application must guarantee serialized access to a
  195: .Xr ghash 3
  196: hash table; the hash table itself does not provide this protection.
  197: .Pp
  198: Some threads that can end up running user code
  199: are subject to cancellation at any cancellation point.
  200: For example, a thread created by an
  201: .Xr http_server 3
  202: object to handle an HTTP request will be canceled if the remote client
  203: closes the TCP connection.
  204: This implies that any user code which could be running under such a
  205: thread must register thread cleanup hooks to release any resources
  206: such as heap memory, mutexes, etc., should the thread be canceled.
  207: .Pp
  208: All
  209: .Nm libpdel
  210: functions are cancel-safe if the thread has cancel type
  211: .Dv PTHREAD_CANCEL_DEFERRED ,
  212: except where noted.
  213: .Pp
  214: Because
  215: .Nm libpdel
  216: in turn depends on other libraries, programs linking with
  217: .Nm libpdel
  218: must also link with these libraries:
  219: .Pp
  220: .Bl -dash -compact
  221: .It
  222: SSL:
  223: .Li "-lssl"
  224: .It
  225: Cryptography:
  226: .Li "-lcrypto"
  227: .It
  228: Netgraph (FreeBSD only):
  229: .Li "-lnetgraph"
  230: .It
  231: RADIUS (FreeBSD only):
  232: .Li "-lradius"
  233: .It
  234: Expat:
  235: .Li "-L/usr/local/lib -lexpat"
  236: .It
  237: Pthreads:
  238: .Li "-pthread"
  239: .Li "(-lpthread"
  240: on Linux)
  241: .El
  242: .Pp
  243: Expat is available as FreeBSD port "textproc/expat2"
  244: (see
  245: .Xr ports 7) .
  246: .Sh SEE ALSO
  247: .Xr alog 3 ,
  248: .Xr app_config 3 ,
  249: .Xr base64 3 ,
  250: .Xr boundary_fopen 3 ,
  251: .Xr count_fopen 3 ,
  252: .Xr filter_fopen 3 ,
  253: .Xr fs_mount 3 ,
  254: .Xr ghash 3 ,
  255: .Xr gtree 3 ,
  256: .Xr http_client 3 ,
  257: .Xr http_server 3 ,
  258: .Xr if_util 3 ,
  259: .Xr logfile 3 ,
  260: .Xr paction 3 ,
  261: .Xr pdel_ppp 3 ,
  262: .Xr pevent 3 ,
  263: .Xr pthread 3 ,
  264: .Xr route_msg 3 ,
  265: .Xr rsa_util_sign 3 ,
  266: .Xr string_enquote 3 ,
  267: .Xr string_fp 3 ,
  268: .Xr structs 3 ,
  269: .Xr tcp_server 3 ,
  270: .Xr timeout_fdopen 3 ,
  271: .Xr tinfo 3 ,
  272: .Xr tmpl 3 ,
  273: .Xr typed_mem 3 ,
  274: .Xr uroute 3
  275: .Rs
  276: .%Q The Open Group
  277: .%R "Single UNIX Specification, Version 2"
  278: .%T "Threads"
  279: .%O "http://www.opengroup.org/onlinepubs/7908799/xsh/threads.html"
  280: .Re
  281: .Rs
  282: .%A James Clark
  283: .%T "Expat XML Parser"
  284: .%O "http://sourceforge.net/projects/expat/"
  285: .Re
  286: .Sh HISTORY
  287: The PDEL library was developed at Packet Design, LLC.
  288: .Dv "http://www.packetdesign.com/"
  289: .Sh AUTHORS
  290: .An Archie Cobbs Aq archie@freebsd.org
  291: .Sh BUGS
  292: Some functionality is only supported under FreeBSD.
  293: .Pp
  294: Please report bugs to the author.