ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/libukcprog/doc/ukcprog.3
Revision: 1.3
Committed: Sun Aug 1 10:41:13 2004 UTC (19 years, 7 months ago) by tdb
Branch: MAIN
CVS Tags: HEAD
Changes since 1.2: +1 -1 lines
Log Message:
Catch a lot of old URL's and update them. Also remove a couple of old files
that aren't used.

File Contents

# Content
1 .\" $Id: ukcprog.3,v 1.18 1993/02/23 11:31:42 gjap Exp $ UKC
2 .\" .fX - print the argument in a fixed font
3 .de fX
4 \&\\$3\f(CR\\$1\fP\\$2
5 ..
6 .\" .Vs - start example
7 .de Vs
8 .LP
9 .ne 1i
10 .RS
11 .nf
12 .ft CR
13 ..
14 .\" .Ve - end example
15 .de Ve
16 .ft P
17 .fi
18 .hy 0
19 .RE
20 .LP
21 ..
22 .TH UKCPROG 3 "February 1991" "UKC Local"
23 .SH NAME
24 ukcprog \- Library of utilities for C programmers
25 .SH SYNOPSIS
26 .nf
27 .LP
28 In source code,
29 .Vs
30 #include <ukcprog.h>
31 .Ve
32 and link with
33 .Vs
34 cc ... -lukcprog
35 .Ve
36 .SH AVAILABILITY
37 .LP
38 .\"
39 .\" The following sentence motivated the port to MS-DOG.
40 .\"
41 This is a UKC library, available for the \s-1UNIX\s0 and \s-1VMS\s0
42 operating systems, and for MS-DOS.
43 .\"
44 .\" It was worth it ...
45 .\"
46 The source code is freely available so if you want to make
47 a source release of your application you can include a copy of the
48 source of this library as well.
49 .SH DESCRIPTION
50 .LP
51 The ukcprog library contains generally useful low level routines.
52 The
53 .fX ukcprog.h
54 header file contains prototypes for the
55 routines as well as defining some useful macros and types.
56 .Vs
57 #ifdef __STDC__
58 #define PROTO(a) a
59 typedef void *voidptr;
60 #else
61 #define PROTO(a) ()
62 #define const
63 #define volatile
64 #define signed
65 typedef char *voidptr;
66 #endif
67 .Ve
68 .LP
69 The definitions of
70 .fX const ,
71 .fX volatile
72 and
73 .fX signed
74 allow these ANSI C keywords to be used in code which must be portable
75 to pre-ANSI C compilers.
76 .LP
77 The
78 .fX voidptr
79 typedef is similarly there to help with code for pre-ANSI compilers
80 which do not support the
81 .fX "void *" ' `
82 type.
83 Functions which are documented here as returning
84 .fX "void *" ' `
85 return
86 .fX "char *" ' `
87 when compiling with a non-ANSI C compiler.
88 .LP
89 The
90 .fX PROTO
91 macro is useful for declaring function prototypes
92 for use with ANSI C while still allowing the code to be compiled with
93 K&R compilers.
94 It is used thus:
95 .Vs
96 int myfunc PROTO((int arg1, char *arg2));
97 .Ve
98 With an ANSI C compiler this expands to
99 .Vs
100 int myfunc (int arg1, char *arg2);
101 .Ve
102 whereas a pre-ANSI compiler sees:
103 .Vs
104 int myfunc ();
105 .Ve
106 .LP
107 Note the double brackets; these are necessary to make all the parameters
108 a single argument to the
109 .fX PROTO
110 macro.
111 .Vs
112 #ifndef FALSE
113 #define FALSE 0
114 #endif
115 #ifndef TRUE
116 #define TRUE 1
117 #endif
118 #ifndef bool
119 #define bool int
120 #endif
121 .Ve
122 These define the commonly used
123 .fX TRUE
124 and
125 .fX FALSE
126 macros to their usual values.
127 The definitions are protected in case these are already defined.
128 The
129 .fX bool
130 macro is intended to be used to declared variables
131 that are conceptually boolean.
132 A
133 .fX #define
134 is used rather than a typedef because there might already be a typedef
135 for
136 .fX bool .
137 .Vs
138 #ifdef __STDC__
139 #define CAT(a,b) a ## b
140 #else
141 #define _IDENT(a) a
142 #define CAT(a,b) _IDENT(a)b
143 #endif /* !__STDC__ */
144 .Ve
145 The
146 .fX CAT
147 macro can be used to glue two tokens together in the same way as
148 the ANSI C
149 .fX ##
150 operator.
151 .fX CAT
152 also works with many (but not all) pre-ANSI C preprocessors.
153 .Vs
154 void panic(const char *message)
155 .sp
156 typedef void (*panic_handler_t)(const char *message);
157 panic_handler_t install_panic_handler(panic_hander_t handler)
158 .Ve
159 By default
160 .fX panic()
161 produces a message on stderr of the form
162 .Vs
163 fatal internal error: \fIsomething\fP (aborting)...
164 .Ve
165 It then calls
166 .fX abort(3)
167 to produce a core dump.
168 Alternative `panic handlers' can be installed using
169 .fX install_panic_handler()
170 which returns the previous handler.
171 Panic handlers can perform tidy-up tasks, such as
172 removing temporary files or calling
173 .fX chdir(2)
174 to arrange for
175 the core to land in a safe place.
176 If a panic handler is called and returns then the default
177 action is carried out.
178 .Vs
179 void *e_malloc(size_t size)
180 void *e_realloc(void *old, size_t size)
181 char *strsave(const char *str)
182 .Ve
183 .fX e_malloc()
184 and
185 .fX e_realloc()
186 are error-checking versions
187 of the corresponding routines in the standard C library.
188 They call
189 .fX panic()
190 if the request fails.
191 .fX e_realloc()
192 behaves according to the ANSI specification for
193 .fX realloc() ;
194 that is, if
195 .fX old
196 is NULL it behaves like
197 .fX malloc()
198 and if size is 0, it behaves like
199 .fX free() .
200 .fX strsave()
201 allocates some memory using
202 .fX e_malloc() ,
203 copies
204 .fX str
205 into it, and returns a pointer to the copy.
206 .Vs
207 char *fpgetline(FILE *fp)
208 .Ve
209 .fX fpgetline()
210 reads characters from the standard IO stream
211 .fX fp
212 until a newline character or EOF is encountered.
213 .fX fpgetline()
214 returns
215 .fX NULL
216 if EOF or an error occurred before any characters were read;
217 otherwise it returns a pointer to the NUL terminated line.
218 .fX fpgetline()
219 never adds a newline to the buffer.
220 The user can check for a missing final newline in a file by checking
221 the EOF flag of the stream pointer when
222 .fX fpgetline()
223 returns a non-NULL pointer.
224 .LP
225 When
226 .fX fpgetline()
227 returns
228 .fX NULL
229 the caller should check with
230 .fX ferror(3)
231 whether the cause was EOF or an error reading the stream
232 .fX fp .
233 .LP
234 .fX fpgetline()
235 returns a pointer to a static buffer that is resized as necessary
236 to handle long lines.
237 The caller can modify the contents of the buffer but must not free
238 it or realloc it.
239 The buffer is valid only until the next call of
240 .fX fpgetline() .
241 .Vs
242 char *config_trim_line(char *line)
243 .Ve
244 .fX config_trim_line()
245 trims comments and white space in place from a line.
246 First it scans for the first
247 .fX # ' `
248 character in the line.
249 If there is one it is removed along with any following characters.
250 Then leading and trailing whitespace characters (as defined by
251 .IR isspace (3))
252 are removed.
253 .fX config_trim_line()
254 returns a pointer to the trimmed line (which will point into the line
255 that it was given).
256 .LP
257 A typical use of this routine is to skip blank lines and comments from
258 a configuration file.
259 .Vs
260 typedef void (*errf_ofunc_t)(const char *string);
261 .sp
262 void errf(const char *fmt, ...)
263 char *strf(const char *fmt, ...)
264 .sp
265 errf_ofunc_t errf_set_ofunc(errf_ofunc_t func)
266 const char *errf_set_prefix(const char *prefix)
267 const char *errf_get_prefix(void)
268 void_errf_set_progname(const char *progname)
269 const char *errf_get_progname(void)
270 char *formf(char *buffer, int buffer_size,
271 const char *format, va_list args)
272 void errf_usage(const char *usage)
273 .Ve
274 These routines form the basis of a generalised error handling system.
275 .fX errf()
276 formats an error message, much like
277 .fX printf(3) ,
278 but then passes the formatted text to the `current output function'.
279 The default output function appends a newline to the message and
280 sends it to stderr.
281 An alternative output function can be installed with
282 .fX errf_set_ofunc() ;
283 it returns the old one which can be re-installed as required.
284 The default output function can optionally prefix the message with
285 a fixed string; this can be inserted with
286 .fX errf_set_prefix() .
287 A pointer to the current prefix is returned by
288 .fX errf_get_prefix() .
289 By convention, this prefix is derived from the name of the program.
290 .fX errf_set_progname()
291 is a convenience routine which, when passed
292 .fX argv[0] ,
293 munges it in an operating system specific way to produce the program name
294 and sets the prefix to something that looks `nice'.
295 A pointer to the program name (after munging) can be obtained by
296 .fX errf_get_progname().
297 A usage line can be sent to the current output function by
298 .fX errf_usage() ;
299 it prefixes
300 .Vs
301 Usage: \fIprogname\fP
302 .Ve
303 to its argument, and exits with status 1.
304 .LP
305 .fX strf()
306 formats a string in the same way as
307 .fX errf() ,
308 but returns a pointer to a buffer obtained from
309 .fX malloc(3)
310 that
311 contains the result.
312 .LP
313 .fX formf()
314 is used in the internal implementation of
315 .fX errf()
316 and
317 .fX strf()
318 and
319 .fX logf()
320 (see below) and is not for the faint-hearted.
321 It is made visible because it is useful if you need to implement
322 other
323 .fX errf() "-style"
324 functions.
325 In addition to the normal format conversions,
326 .fX formf()
327 provides
328 .fX %m ' `
329 which inserts an error message
330 corresponding to the current value of
331 .fX errno
332 into the output string.
333 .Vs
334 int logf_set_ofile PROTO((const char *filename, const char *prefix));
335 void logf(int level, const char *fmt, ...)
336 int logf_set_level PROTO((int level));
337 void logf_errf_ofunc PROTO((const char *str));
338 .Ve
339 These routines are an alternative to
340 .I syslog (3)
341 for applications that need to log messages to a specified file.
342 .fX logf()
343 handles the
344 .fX fmt
345 format string and arguments in the same same way as
346 .fX errf() .
347 If there has been no prior call to
348 .fX logf_set_ofile ()
349 (see below) the message is
350 displayed on stderr, prefixed with the current date and time.
351 If the output
352 .I is
353 going to a file,
354 .fX logf()
355 tries to ensure that messages from multiple processes to a single log
356 file are interleaved correctly.
357 .LP
358 The
359 .fX level
360 argument specifies the class of the message; it is one of
361 .fX LG_DEBUG ,
362 .fX LG_INFO ,
363 or
364 .fX LG_ERR
365 (which are in increasing numerical order).
366 Messages at a level less than the current log level are discarded.
367 The default log level is
368 .fX LG_INFO ;
369 it can be set using
370 .fX logf_set_level() ,
371 which also returns the previous log level.
372 The log levels
373 .fX LG_ALL
374 and
375 .fX LG_LOG
376 are valid only in calls to
377 .fX logf_set_level() ;
378 .fX LG_ALL
379 means log all messages and
380 .fX LG_LOG
381 means log only messages relating to
382 .fX logf()
383 itself.
384 .LP
385 .fX logf_set_ofile()
386 sets the output file for
387 .fX logf()
388 messages.
389 If the log file does not exist
390 .fX logf_set_ofile()
391 attempts to create it; otherwise it is opened for writing (without
392 discarding any existing contents).
393 If the attempt to create or open the file fails,
394 .fX logf_set_ofile()
395 gives an error message and returns -1, otherwise it returns zero.
396 If the
397 .fX prefix
398 argument is not
399 .fX NULL ,
400 the string specified is prepended to all future log messages.
401 .fX logf_set_ofile()
402 makes a copy of the string so it need not be preserved after the call.
403 .LP
404 .fX logf_errf_ofunc()
405 logs the message
406 .fX str
407 at level
408 .fX LG_ERR .
409 It can be passed as an output function to
410 .fX errf_set_ofunc()
411 to arrange that all error messages are sent to a log file.
412 .Ve
413 .fX ssplit()
414 splits a string into a vector of words, treating
415 occurrences in the string of any of the characters in the
416 .fX delimiters
417 string as word separators.
418 .LP
419 If the delimiters string starts with a NUL character then multiple
420 adjacent delimiters and leading delimiters generate zero length fields.
421 Otherwise, leading delimiter characters are skipped and multiple adjacent
422 delimiters are treated as a single delimiter.
423 Thus
424 .Vs
425 char **words = ssplit(line, " \\t");
426 .Ve
427 will to a shell-like split of a command line into words, and
428 .Vs
429 char **fields = ssplit(pwline, "\\0:");
430 .Ve
431 would be good for splitting lines from the password file.
432 .LP
433 .fX ssplit()
434 returns a
435 .fX NULL
436 terminated vector of words.
437 The space for this vector and the pointed to words is allocated with
438 a (single) call to
439 .fX e_malloc() .
440 .fX ssplit()
441 thus never returns
442 .fX NULL ;
443 it aborts the program
444 by calling
445 .fX panic()
446 if memory runs out.
447 .LP
448 The vector returned by
449 .fX ssplit()
450 should be freed when it is finished
451 with by passing it to
452 .fX free() .
453 .Vs
454 int get_host_addr(const char *hostname, struct in_addr *p_addr)
455 .Ve
456 .fX get_host_addr()
457 looks up the IP address of
458 .fX hostname
459 using
460 .IR gethostbyaddr (3).
461 If the lookup succeeds it sets
462 .fX *p_addr
463 to the IP address of the host in network byte order.
464 If the lookup fails it gives an error message with
465 .fX errf()
466 and returns -1.
467 If
468 .fX hostname
469 consists of four decimal numbers separated by dots then
470 .fX get_host_addr
471 parses this as an IP quad and does not call
472 .IR gethostbyname .
473 .Vs
474 int get_service_port(const char *servname, int *p_port)
475 .Ve
476 .fX get_service_port
477 looks up the port number of the TCP service
478 .fX servname
479 using
480 .IR getservbyname (3).
481 If it succeeds it sets
482 .fX *p_port
483 to the port number in network byte order.
484 Otherwise it gives an error message with
485 .fX errf()
486 and returns -1.
487 If
488 .fX servname
489 is an \s-2ASCII\s0 decimal number then
490 .fX get_service_port()
491 returns that number (again in network byte order).
492 .Vs
493 ebuf_t *ebuf_create(bool errors_are_fatal);
494 void ebuf_reset(ebuf_t *eb);
495 ebuf_t *ebuf_start(ebuf_t *eb, bool errors_are_fatal);
496 int ebuf_add(ebuf_t *eb, const char *buf, int count);
497 char *ebuf_get(ebuf_t *eb, int *p_len);
498 void ebuf_free(ebuf_t *eb);
499 .Ve
500 These routines implement variable sized contiguous buffers to which data
501 can be appended at any time.
502 .fX ebuf_create()
503 creates a new zero length buffer.
504 The
505 .fX errors_are_fatal
506 parameter controls the handling of errors; if it is
507 .fX TRUE
508 then all of the routines will call
509 .fX panic()
510 on failure.
511 .LP
512
513 .fX ebuf_add()
514 appends
515 .fX count
516 bytes of memory pointed at by
517 .fX data
518 to the buffer
519 .fX eb
520 (which must have been created using
521 .fX ebuf_create() ).
522 .fX ebuf_add()
523 returns zero on success.
524 On failure it panics or returns
525 .fX -1
526 (depending on the setting of
527 .fX errors_are_fatal
528 in the call of
529 .fX ebuf_create()).
530 .LP
531 .fX ebuf_get()
532 returns a pointer to the current contents of
533 .fX eb ;
534 if the
535 .fX p_len
536 parameter is not
537 .fX NULL
538 the current length of the buffer in bytes is stored there.
539 The returned buffer and length are only valid up to the next call of
540 .fX ebuf_add() ,
541 .fX ebuf_reset()
542 or
543 .fX ebuf_free().
544 .LP
545 .fX ebuf_reset()
546 frees the data associated with
547 .fX eb
548 and resets the length to zero.
549 Furthur calls of
550 .fX ebuf_add()
551 can be used to add fresh data to
552 .fX eb .
553 .fX ebuf_free()
554 frees and destroys
555 .fX eb .
556 .LP
557 .fX ebuf_start()
558 is a convenience routine which either creates or resets a buffer.
559 If
560 .fX eb
561 is
562 .fX NULL
563 it calls
564 .fX ebuf_create()
565 with the supplied value of
566 .fX errors_are_fatal .
567 If
568 .fX eb
569 is not
570 .fX NULL
571 then it is passed to
572 .fX ebuf_reset().
573 The routine is intended to be used like for static buffers in the following
574 way:
575 .Vs
576 void foo(void)
577 {
578 static ebuf_t *eb = NULL;
579
580 eb = ebuf_start(eb, TRUE);
581 ...
582 }
583 .Ve
584 The first time the function is called the buffer is created; on subsequent
585 calls it is reset.
586 .Vs
587 alloc_pool_t *alloc_create_pool(void)
588 .sp
589 void *alloc(alloc_pool_t *ap, int nbytes)
590 void *alloc_ck(alloc_pool_t *ap, int nbytes)
591 .Ve
592 .fX alloc_create_pool()
593 creates a memory allocation `pool' and
594 returns a handle referring to it.
595 .fX alloc()
596 allocates memory like
597 .fX malloc(3)
598 but from the
599 specified pool rather from the general malloc arena.
600 .fX alloc()
601 calls
602 .fX e_malloc()
603 to obtain memory in reasonably
604 large chunks when necessary.
605 This means that it never returns
606 .fX NULL ;
607 the program is aborted
608 via
609 .fX panic()
610 if there is insufficient memory to satisfy the
611 request.
612 The alternative interface
613 .fX alloc_ck()
614 returns
615 .fX NULL
616 if
617 it runs out of memory; it is otherwise identical to
618 .fX alloc() .
619 Memory obtained with
620 .fX alloc()
621 cannot be freed individually; only
622 entire pools can be freed.
623 .Vs
624 void alloc_free_pool(alloc_pool_t *ap)
625 void alloc_reset_pool(alloc_pool_t *ap)
626 .Ve
627 .fX alloc_free_pool()
628 frees an alloc pool, releasing all memory
629 allocated from it with
630 .fX alloc() .
631 The pool is no longer valid after this call.
632 .fX alloc_reset_pool()
633 conceptually frees all the memory associated with
634 a pool but does not return it via
635 .fX free() .
636 The pool remains valid and subsequent calls to
637 .fX alloc()
638 allocate
639 memory from the existing memory associated with the pool if possible.
640 .LP
641 These routines are suitable for applications which make lots of small
642 allocations for a data structure which is to be freed in one go.
643 .fX alloc()
644 is much faster than
645 .fX malloc()
646 as it does not do
647 the bookkeeping to support individual freeing of allocated memory.
648 It also has no space overhead other than that necessary to correctly
649 align objects in memory.
650 .LP
651 .fX alloc_create_pool()
652 is a lightweight routine \- it involves a
653 single call to
654 .fX malloc()
655 plus some assignments to initialise the
656 pool header structure.
657 It is thus reasonable to use the
658 .fX alloc()
659 routines in situations where
660 there are only going to be a few tens of calls to
661 .fX alloc() .
662 .Vs
663 bool alloc_set_default_debug_flag(bool val)
664 bool alloc_set_debug_flag(alloc_pool_t *ap, bool val)
665 .Ve
666 By default all memory obtained with
667 .fX alloc()
668 and related routines
669 is initialised to the repeated byte
670 .fX 0x53 .
671 When memory is freed (with
672 .fX alloc_free_pool() ,
673 .fX alloc_reset_pool()
674 or
675 .fX alloc_release() )
676 it is set
677 to the repeated byte
678 .fX 0x42 .
679 This is intended to trap erroneous use of uninitialised data and data
680 that has been freed \- newly allocated memory contains obvious garbage
681 and freed memory is immediately stamped on.
682 .LP
683 Of course these safety features cost speed, so they can be turned off
684 globally or per-pool.
685 .fX alloc_set_debug_flag()
686 sets the debugging flag for a pool; memory
687 will be initialised to garbage and stamped on when freed only of the flag
688 is non-zero.
689 .fX alloc_set_default_debug_flag()
690 sets the value of the flag used
691 for pools created from then on with
692 .fX alloc_create_pool() .
693 Both routines return the previous value of the flag they set.
694 .Vs
695 char *allocstr(alloc_pool_t *ap, int nbytes)
696 char *allocstr_ck(alloc_pool_t *ap, int nbytes)
697 .Ve
698 .fX allocstr()
699 is like
700 .fX alloc()
701 except that it assumes that
702 no alignment is required.
703 It is thus suitable only for allocating space for strings.
704 .fX allocstr()
705 is implemented such that interspersed calls to
706 .fX alloc()
707 and
708 .fX allocstr()
709 will pack both
710 the strings and the other objects tightly in memory with no space
711 wasted on alignment.
712 .fX allocstr()
713 never returns
714 .fX NULL
715 \- it panics like
716 .fX alloc()
717 if there is no memory.
718 .fX allocstr_ck()
719 is the same as
720 .fX allocstr()
721 except that
722 it returns
723 .fX NULL
724 if there is no memory.
725 .Vs
726 char *alloc_strdup(alloc_pool_t *ap, const char *s)
727 .Ve
728 .fX alloc_strdup()
729 is a convenience routine that returns a pointer
730 to a copy of a string allocated using
731 .fX allocstr() .
732 Note that it will never return
733 .fX NULL
734 as it uses
735 .fX allocstr()
736 rather than
737 .fX allocstr_ck() .
738 .Vs
739 alloc_mark_t *alloc_mark(alloc_pool_t *ap)
740 void alloc_release(alloc_pool_t *ap, alloc_mark_t *am)
741 .Ve
742 .fX alloc_mark()
743 returns an opaque handle that `remembers' the
744 current position in an alloc pool.
745 A subsequent call to
746 .fX alloc_release()
747 conceptually frees all
748 memory allocated from the pool since the corresponding call of
749 .fX alloc_mark() .
750 Subsequent calls to
751 .fX alloc()
752 et al will reuse the freed memory.
753 A call to
754 .fX alloc_release()
755 renders invalid any marks that were
756 returned after the
757 .fX alloc_mark()
758 call that returned the mark
759 being passed to
760 .fX alloc_release() .
761 .Vs
762 const char *ukcprog_version(void)
763 .Ve
764 .fX ukcprog_version()
765 returns a string giving the current version number of the library.
766 .SH BUGS
767 This library treads rather freely on the name space.
768 .SH AUTHORS
769 .LP
770 Godfrey Paul
771 .br
772 Mark Russell
773 .sp
774 Computing Laboratory, University of Kent at Canterbury.
775 .br
776 Contact: cs-sysadmin@kent.ac.uk