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, 8 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

# User Rev Content
1 tdb 1.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 tdb 1.2 #include <ukcprog.h>
31 tdb 1.1 .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 tdb 1.2 Godfrey Paul
771 tdb 1.1 .br
772 tdb 1.2 Mark Russell
773 tdb 1.1 .sp
774     Computing Laboratory, University of Kent at Canterbury.
775 tdb 1.2 .br
776 tdb 1.3 Contact: cs-sysadmin@kent.ac.uk