Annotation of embedaddon/libpdel/libpdel.3, revision 1.1.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