Annotation of embedaddon/libpdel/libpdel.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: libpdel.3,v 1.23 2004/06/03 21:16:16 archie 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.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to libpdel.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