diff options
Diffstat (limited to 'libtecla-1.4.1/man3/ef_expand_file.3')
| -rw-r--r-- | libtecla-1.4.1/man3/ef_expand_file.3 | 245 |
1 files changed, 0 insertions, 245 deletions
diff --git a/libtecla-1.4.1/man3/ef_expand_file.3 b/libtecla-1.4.1/man3/ef_expand_file.3 deleted file mode 100644 index 88c2d54..0000000 --- a/libtecla-1.4.1/man3/ef_expand_file.3 +++ /dev/null @@ -1,245 +0,0 @@ -.\" Copyright (C) 2000, 2001 by Martin C. Shepherd -.\" -.\" All rights reserved. -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining a -.\" copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, and/or sell copies of the Software, and to permit persons -.\" to whom the Software is furnished to do so, provided that the above -.\" copyright notice(s) and this permission notice appear in all copies of -.\" the Software and that both the above copyright notice(s) and this -.\" permission notice appear in supporting documentation. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT -.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR -.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL -.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING -.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, -.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION -.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.\" Except as contained in this notice, the name of a copyright holder -.\" shall not be used in advertising or otherwise to promote the sale, use -.\" or other dealings in this Software without prior written authorization -.\" of the copyright holder. -.TH ef_expand_file 3 -.SH NAME -ef_expand_file, del_ExpandFile, ef_last_error, ef_list_expansions, new_ExpandFile \- expand filenames containing ~user/$envvar and wildcard expressions -.SH SYNOPSIS -.nf -#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); -.fi - -.SH DESCRIPTION - -The \f3ef_expand_file()\f1 function is part of the tecla library -(see the libtecla(3) man page). It expands a specified filename, -converting \f3~user/\f1 and \f3~/\f1 expressions at the start of the -filename to the corresponding home directories, replacing -\f3$envvar\f1 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. -.sp -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 \f3tcsh\f1 shell. -.sp -The supported wildcards and their meanings are: -.nf - * - 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'. -.fi - -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. -.sp -The following is a complete example of how to use the file expansion -function. - -.nf - #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; - } -.fi -.sp -Descriptions of the functions used above are as follows: -.sp -.nf - ExpandFile *new_ExpandFile(void) -.fi -.sp -This function creates the resources used by the \f3ef_expand_file()\f1 -function. In particular, it maintains the memory that is used to record the -array of matching filenames that is returned by \f3ef_expand_file()\f1. This -array is expanded as needed, so there is no built in limit to the number of -files that can be matched. -.sp -.nf - ExpandFile *del_ExpandFile(ExpandFile *ef) -.fi -.sp -This function deletes the resources that were returned by a previous call to -\f3new_ExpandFile()\f1. It always returns \f3NULL\f1 (ie a deleted object). It -does nothing if the \f3ef\f1 argument is \f3NULL\f1. -.sp -A container of the following type is returned by \f3ef_expand_file()\f1. -.sp -.nf - 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; -.fi -.sp -.nf - FileExpansion *ef_expand_file(ExpandFile *ef, - const char *path, - int pathlen) -.fi -.sp -The \f3ef_expand_file()\f1 function performs filename expansion, as documented -at the start of this section. Its first argument is a resource object returned -by \f3new_ExpandFile()\f1. A pointer to the start of the filename to be matched -is passed via the \f3path\f1 argument. This must be a normal \f3NUL\f1 -terminated string, but unless a length of -1 is passed in \f3pathlen\f1, only -the first \f3pathlen\f1 characters will be used in the filename expansion. If -the length is specified as -1, the whole of the string will be -expanded. -.sp -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 \f3nfile\f1 member will be 1, and the \f3exists\f1 member should -be queried if it is important to know if the expanded file currently -exists or not. If there were wildcards, then the contained -\f3files[]\f1 array will contain the names of the \f3nfile\f1 existing -files that matched the wildcarded filename, and the \f3exists\f1 -member will have the value 1. Note that the returned container belongs -to the specified \f3ef\f1 object, and its contents will change on each -call, so if you need to retain the results of more than one call to -\f3ef_expand_file()\f1, you should either make a private copy of the -returned results, or create multiple file-expansion resource objects -via multiple calls to \f3new_ExpandFile()\f1. -.sp -On error, \f3NULL\f1 is returned, and an explanation of the error can -be determined by calling \f3ef_last_error(ef)\f1. -.sp -.nf - const char *ef_last_error(ExpandFile *ef) -.fi -.sp -This function returns the message which describes the error that -occurred on the last call to \f3ef_expand_file()\f1, for the given -\f3(ExpandFile *ef)\f1 resource object. -.sp -.nf - int ef_list_expansions(FileExpansion *result, FILE *fp, - int terminal_width); -.fi -.sp -The \f3ef_list_expansions()\f1 function provides a convenient way to -list the filename expansions returned by \f3ef_expand_file()\f1. Like -the unix \f3ls\f1 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 terminal width can -occur. The list is written to the stdio stream specified by the -\f3fp\f1 argument. - -.SH THREAD SAFETY - -In multi-threaded programs, you should use the \f3libtecla_r.a\f1 -version of the library. This uses POSIX reentrant functions where -available (hence the \f3_r\f1 suffix), and disables features that rely -on non-reentrant system functions. Currently there are no features -disabled in this module. - -Using the \f3libtecla_r.a\f1 version of the library, it is safe to use -the facilities of this module in multiple threads, provided that each -thread uses a separately allocated \f3ExpandFile\f1 object. In other -words, if two threads want to do file expansion, they should each call -\f3new_ExpandFile()\f1 to allocate their own file-expansion objects. - -.SH FILES -.nf -libtecla.a - The tecla library -libtecla.h - The tecla header file. -.fi - -.SH SEE ALSO -libtecla(3), gl_get_line(3), cpl_complete_word(3), pca_lookup_file(3) - -.SH AUTHOR -Martin Shepherd (mcs@astro.caltech.edu) |