SHELLUTILS(3X) — Subroutines
NAME
shellscan − shell−style lexical analysis tools
SYNOPSIS
#include <codelibs/shellutils.h>
char const ∗const ∗
shellscan(char const ∗str, int ∗argc = NULL, unsigned opts = 0)
CC ... -lcodelibs
DESCRIPTION
shellscan is a scanner [lexical analyzer] which tokenizes the input string str according to the constraints specified in opts. The lexical rules used by shellscan are the same as those used by ksh(1).
opts is used to set constraints on the scanner. This is done by setting opts to any combination of the following bit values (defined in shellutils.h):
SHX_NOGLOB
Disables “globbing”. This inhibits the special interpretation normally given to the characters ∗ (asterisk), ? (question mark), [ (left square bracket), and ] (right square bracket).
SHX_NOTILDE
This inhibits the special interpretation normally given to tilde (~) characters encountered at the beginning of a token.
SHX_NOVARS This inhibits the substitution of variable references ($VAR and ${VAR}).
SHX_NOQUOTES
This inhibits the special interpretation normally given to the characters " (double quote), ´ (single quote), and \ (back−slash).
SHX_NOSPACE
This inhibits the special interpretation normally given to the characters specified in the environment variable $IFS (the default value of IFS contains the space, horizontal tab and newline characters).
SHX_NOMETA
This inhibits the special interpretation normally given to the characters ( (left parenthesis), ) (right parenthesis), & (ampersand), | (vertical bar), < (left angle bracket), > (right angle bracket), and ; (semi-colon).
SHX_NOCMD This inhibits the special interpretation normally given to grave accent (‘) characters and to $(...) substitutions.
SHX_COMPLETE
Causes str to be interpreted as a single token representing a file name. This can be used to perform file-name completion by finding any or all prefix name matches directly from the filesystem. (See RETURN VALUES below.) This option implicitly sets SHX_NOSPACE and SHX_NOMETA.
RETURN VALUES
Normally, shellscan will return the number of string tokens within the input str argument in ∗argc if argc is not NULL. The string tokens themselves are always returned as the return value from shellscan as a standard NULL-terminated vector of strings.
However, with the SHX_COMPLETE option, shellscan will return a NULL−terminated vector of values which may be interpreted as follows:
∗argc == 0 A null string was passed to shellscan.
∗argc == 1 No match, str is returned unchanged in the first element of the vector.
∗argc == 2 Exactly one match was found. This match is returned in both elements of the returned vector.
∗argc > 2 Multiple (∗argc - 1) matches were found. The longest common prefix is returned in the first element of the vector. The remaining elements contain all of the matches that were found.
NOTES
Supports HP-NLS 8-bit and 16-bit strings.
WARNINGS
This function returns pointers to internal static buffers so that the original str is never modified. Use strdup(3X) or strvdup(3X) if you need a permanent copy of the returned value. No other assumptions should be made about the returned strings.
SEE ALSO
— codelibs — C++