STRING(3)

NAME
string - procedures for manipulating strings in libmagicutils.a

SYNOPSIS
#include magic.h
#include utils.h

typedef struct { char *d_str; } LookupTable;

int Lookup(str, table)
char *str;
char *table[];

int LookupStruct(str, table, size)
char *str;
LookupTable *table;
int size;

int LookupAny(c, table)
char c;
char *table[];

int LookupFull(name, table)
char *name;
char *table[];

char *StrDup(oldstr, str)
char **oldstr, *str;

bool StrIsWhite(str, commentok)
char *str;
bool commentok;

bool StrIsInt(str)
char *str;

bool Match(pattern, string)
char *pattern, *string;

char *ArgStr(pargc, pargv, argType)
int *pargc;
char ***pargv;
char *argType;

DESCRIPTION
This collection of procedures provide a number of useful functions for dealing with strings. Lookup searches a table of strings to find one that matches a given string. It's useful mostly for command lookup. The table of strings should be terminated with a NULL string pointer, and the entries should be alphabetical and all lower-case. Any characters following the first white space in an entry are ignored. If str is an unambiguous abbreviation for one of the entries in table, then the index of the matching entry is returned. If str is an abbreviation for more than one entry in table, then -1 is returned. If str doesn't match any entry, then -2 is returned. Case differences are ignored.

LookupStruct is a more general version of Lookup for dealing with tables of structures whose first word is a string pointer. The table argument should be a pointer to an array of such structures, cast as type (LookupTable *). The table should be terminated with an entry whose string pointer is NULL. As in Lookup, all entries should contain lower-case strings and should be sorted alphabetically. The size parameter gives the size in bytes of each structure in the table.

LookupAny looks up a single character in a table of pointers to strings. The last entry in the string table must be a NULL pointer. The index of the first string in the table containing the indicated character is returned, or -1 if no matching string is found.

LookupFull is like Lookup, but does not allow abbreviations. It either returns the index of the entry of table matching str, or -1 if no match is found. Case is significant, and entries are considered to extend all the way to their trailing NULL byte, instead of being terminated by the first white space as in Lookup.

StrDup can be used to replace an old string with a new one, freeing the storage for the old one and allocating sufficient storage for the new one. It returns a pointer to a newly allocated character array just large enough to hold str and its trailing NULL byte. This newly allocated array contains a copy of str. However, if str is NULL, no memory is allocated and we return NULL. If oldstr is non-NULL, then if *oldstr is non-NULL, StrDup frees the storage pointed to by *oldstr. StrDup then sets *oldstr to point to the new array of memory just allocated, or NULL if str was NULL.

StrIsWhite returns TRUE if str is all white space, or FALSE otherwise. If commentok is TRUE, then if the first non-white character in str is a pound-sign (``#''), str is considered to be all white space.

StrIsInt returns TRUE if str is a well-formed decimal integer, or FALSE if it isn't.

Match provides a csh(1)-like wild-card matching facility. The string pattern may contain any of the csh wildcard characters: *, ?, \, [, and ]. If pattern matches string, Match returns TRUE; otherwise, it returns FALSE.

ArgStr is provided to allow standard processing of command-line arguments that take parameters. It recognizes flag-value pairs of either the form ``-Xvalue'' (a single argument string) or ``-X value'' (two successive argument strings) in the argument list (*pargc, *pargv), incrementing *pargc and *pargv by an amount sufficient to step over the flag-value pair. If there are no more arguments remaining in the list, ArgStr prints an error message complaining that argType is required for the flag *pargv[0].

SEE ALSO
magicutils(3)