diff options
Diffstat (limited to 'libtecla-1.4.1/html/ef_expand_file.html')
| -rw-r--r-- | libtecla-1.4.1/html/ef_expand_file.html | 267 |
1 files changed, 267 insertions, 0 deletions
diff --git a/libtecla-1.4.1/html/ef_expand_file.html b/libtecla-1.4.1/html/ef_expand_file.html new file mode 100644 index 0000000..c1e71c7 --- /dev/null +++ b/libtecla-1.4.1/html/ef_expand_file.html @@ -0,0 +1,267 @@ +<head> +<title>Manual Page</title> +</head> +<body> +<pre> +</pre><h2>NAME</h2><pre> + ef_expand_file, del_ExpandFile, ef_last_error, + ef_list_expansions, new_ExpandFile - expand filenames con- + taining ~user/$envvar and wildcard expressions + +</pre><h2>SYNOPSIS</h2><pre> + #include <libtecla.h> + + ExpandFile *new_ExpandFile(void); + + ExpandFile *del_ExpandFile(ExpandFile *ef); + + FileExpansion *ef_expand_file(ExpandFile *ef, + const char *path, + int pathlen); + + int ef_list_expansions(FileExpansion *result, FILE *fp, + int term_width); + + const char *ef_last_error(ExpandFile *ef); + + +</pre><h2>DESCRIPTION</h2><pre> + The ef_expand_file() function is part of the tecla library + (see the <a href="libtecla.html">libtecla(3)</a> man page). It expands a specified + filename, converting ~user/ and ~/ expressions at the start + of the filename to the corresponding home directories, + replacing $envvar with the value of the corresponding + environment variable, and then, if there are any wildcards, + matching these against existing filenames. Backslashes in + the input filename are interpreted as escaping any special + meanings of the characters that follow them. Only + backslahes that are themselves preceded by backslashes are + preserved in the expanded filename. + + In the presence of wildcards, the returned list of filenames + only includes the names of existing files which match the + wildcards. Otherwise, the original filename is returned + after expansion of tilde and dollar expressions, and the + result is not checked against existing files. This mimics + the file-globbing behavior of the unix tcsh shell. + + The supported wildcards and their meanings are: + * - Match any sequence of zero or more characters. + ? - Match any single character. + [chars] - Match any single character that appears in + 'chars'. If 'chars' contains an expression of + the form a-b, then any character between a and + b, including a and b, matches. The '-' + character looses its special meaning as a + range specifier when it appears at the start + of the sequence of characters. The ']' + character also looses its significance as the + terminator of the range expression if it + appears immediately after the opening '[', at + which point it is treated one of the + characters of the range. If you want both '-' + and ']' to be part of the range, the '-' + should come first and the ']' second. + + [^chars] - The same as [chars] except that it matches any + single character that doesn't appear in + 'chars'. + + Note that wildcards never match the initial dot in filenames + that start with '.'. The initial '.' must be explicitly + specified in the filename. This again mimics the globbing + behavior of most unix shells, and its rational is based in + the fact that in unix, files with names that start with '.' + are usually hidden configuration files, which are not listed + by default by the ls command. + + The following is a complete example of how to use the file + expansion function. + + #include <stdio.h> + #include <libtecla.h> + + int main(int argc, char *argv[]) + { + ExpandFile *ef; /* The expansion resource object */ + char *filename; /* The filename being expanded */ + FileExpansion *expn; /* The results of the expansion */ + int i; + + ef = new_ExpandFile(); + if(!ef) + return 1; + + for(arg = *(argv++); arg; arg = *(argv++)) { + if((expn = ef_expand_file(ef, arg, -1)) == NULL) { + fprintf(stderr, "Error expanding %s (%s).\n", arg, + ef_last_error(ef)); + } else { + printf("%s matches the following files:\n", arg); + for(i=0; i<expn->nfile; i++) + printf(" %s\n", expn->files[i]); + } + } + + ef = del_ExpandFile(ef); + return 0; + } + + Descriptions of the functions used above are as follows: + + ExpandFile *new_ExpandFile(void) + + This function creates the resources used by the + ef_expand_file() function. In particular, it maintains the + memory that is used to record the array of matching + filenames that is returned by ef_expand_file(). This array + is expanded as needed, so there is no built in limit to the + number of files that can be matched. + + ExpandFile *del_ExpandFile(ExpandFile *ef) + + This function deletes the resources that were returned by a + previous call to new_ExpandFile(). It always returns NULL + (ie a deleted object). It does nothing if the ef argument is + NULL. + + A container of the following type is returned by + ef_expand_file(). + + typedef struct { + int exists; /* True if the files in files[] exist */ + int nfile; /* The number of files in files[] */ + char **files; /* An array of 'nfile' filenames. */ + } FileExpansion; + + FileExpansion *ef_expand_file(ExpandFile *ef, + const char *path, + int pathlen) + + The ef_expand_file() function performs filename expansion, + as documented at the start of this section. Its first argu- + ment is a resource object returned by new_ExpandFile(). A + pointer to the start of the filename to be matched is passed + via the path argument. This must be a normal NUL terminated + string, but unless a length of -1 is passed in pathlen, only + the first pathlen characters will be used in the filename + expansion. If the length is specified as -1, the whole of + the string will be expanded. + + The function returns a pointer to a container who's contents + are the results of the expansion. If there were no wildcards + in the filename, the nfile member will be 1, and the exists + member should be queried if it is important to know if the + expanded file currently exists or not. If there were wild- + cards, then the contained files[] array will contain the + names of the nfile existing files that matched the wild- + carded filename, and the exists member will have the value + 1. Note that the returned container belongs to the specified + ef object, and its contents will change on each call, so if + you need to retain the results of more than one call to + ef_expand_file(), you should either make a private copy of + the returned results, or create multiple file-expansion + resource objects via multiple calls to new_ExpandFile(). + + On error, NULL is returned, and an explanation of the error + can be determined by calling ef_last_error(ef). + + const char *ef_last_error(ExpandFile *ef) + + This function returns the message which describes the error + that occurred on the last call to ef_expand_file(), for the + given (ExpandFile *ef) resource object. + + int ef_list_expansions(FileExpansion *result, FILE *fp, + int terminal_width); + + The ef_list_expansions() function provides a convenient way + to list the filename expansions returned by + ef_expand_file(). Like the unix ls command, it arranges the + filenames into equal width columns, each column having the + width of the largest file. The number of columns used is + thus determined by the length of the longest filename, and + the specified terminal width. Beware that filenames that are + longer than the specified terminal width are printed without + being truncated, so output longer than the specified termi- + nal width can occur. The list is written to the stdio stream + specified by the fp argument. + + +</pre><h2>THREAD SAFETY</h2><pre> + In multi-threaded programs, you should use the libtecla_r.a + version of the library. This uses POSIX reentrant functions + where available (hence the _r suffix), and disables features + that rely on non-reentrant system functions. Currently there + are no features disabled in this module. + + Using the libtecla_r.a version of the library, it is safe to + use the facilities of this module in multiple threads, pro- + vided that each thread uses a separately allocated Expand- + File object. In other words, if two threads want to do file + expansion, they should each call new_ExpandFile() to allo- + cate their own file-expansion objects. + + +</pre><h2>FILES</h2><pre> + libtecla.a - The tecla library + libtecla.h - The tecla header file. + + +</pre><h2>SEE ALSO</h2><pre> + <a href="libtecla.html">libtecla(3)</a>, <a href="gl_get_line.html">gl_get_line(3)</a>, <a href="cpl_complete_word.html">cpl_complete_word(3)</a>, + <a href="pca_lookup_file.html">pca_lookup_file(3)</a> +</pre><h2>AUTHOR</h2><pre> + Martin Shepherd (mcs@astro.caltech.edu) + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</pre> +</body> |