diff options
| -rw-r--r-- | extension/ChangeLog | 5 | ||||
| -rw-r--r-- | extension/filefuncs.3am | 342 | ||||
| -rw-r--r-- | extension/fnmatch.3am | 116 | ||||
| -rw-r--r-- | extension/ordchr.3am | 74 | ||||
| -rw-r--r-- | extension/readfile.3am | 67 |
5 files changed, 604 insertions, 0 deletions
diff --git a/extension/ChangeLog b/extension/ChangeLog index 66c88ec8..80cb44d7 100644 --- a/extension/ChangeLog +++ b/extension/ChangeLog @@ -1,3 +1,8 @@ +2012-07-20 Arnold D. Robbins <arnold@skeeve.com> + + * filefuncs.3am, fnmatch.3am, ordchr.3am, readfile.3am: + new files. + 2012-07-16 Arnold D. Robbins <arnold@skeeve.com> * fnmatch.c: Simplify flag table. diff --git a/extension/filefuncs.3am b/extension/filefuncs.3am new file mode 100644 index 00000000..3e606bc5 --- /dev/null +++ b/extension/filefuncs.3am @@ -0,0 +1,342 @@ +.TH FILEFUNCS 3am "Jul 15 2012" "Free Software Foundation" "GNU Awk Extension Modules" +.SH NAME +filefuncs \- provide some file related functionality to gawk +.SH SYNOPSIS +.ft CW +@load "filefuncs" +.sp +result = chdir("/some/directory") +.sp +result = stat("/some/path", statdata) +.sp +flags = or(FTS_PHYSICAL, ...) +.br +result = fts(pathlist, flags, filedata) +.ft R +.SH DESCRIPTION +The +.I filefuncs +extension adds several functions that provide access to +file-related facilities. +.SS chdir() +The +.B chdir() +function is a direct hook to the +.IR chdir (2) +system call to change the current directory. +It returns zero +upon success or less than zero upon error. +In the latter case it updates +.BR ERRNO . +.SS stat() +The +.B stat() +function provides a hook into the +.IR stat (2) +system call. In fact, it uses +.IR lstat (2). +It returns zero +upon success or less than zero upon error. +In the latter case it updates +.BR ERRNO . +.PP +In all cases, it clears the +.B statdata +array. +When the call is successful, +.B stat() +fills the +.B statdata +array with information retrieved from the filesystem, as follows: +.TP +\fBstatdata["name"]\fP +The name of the file. +.TP +\fBstatdata["dev"]\fP +Corresponds to the +.I st_dev +field in the +.IR "struct stat" . +.TP +\fBstatdata["ino"]\fP +Corresponds to the +.I st_ino +field in the +.IR "struct stat" . +.TP +\fBstatdata["mode"]\fP +Corresponds to the +.I st_mode +field in the +.IR "struct stat" . +.TP +\fBstatdata["nlink"]\fP +Corresponds to the +.I st_nlink +field in the +.IR "struct stat" . +.TP +\fBstatdata["uid"]\fP +Corresponds to the +.I st_uid +field in the +.IR "struct stat" . +.TP +\fBstatdata["gid"]\fP +Corresponds to the +.I st_gid +field in the +.IR "struct stat" . +.TP +\fBstatdata["size"]\fP +Corresponds to the +.I st_size +field in the +.IR "struct stat" . +.TP +\fBstatdata["atime"]\fP +Corresponds to the +.I st_atime +field in the +.IR "struct stat" . +.TP +\fBstatdata["mtime"]\fP +Corresponds to the +.I st_mtime +field in the +.IR "struct stat" . +.TP +\fBstatdata["ctime"]\fP +Corresponds to the +.I st_ctime +field in the +.IR "struct stat" . +.TP +\fBstatdata["rdev"]\fP +Corresponds to the +.I st_rdev +field in the +.IR "struct stat" . +This element is only present for device files. +.TP +\fBstatdata["major"]\fP +Corresponds to the +.I st_major +field in the +.IR "struct stat" . +This element is only present for device files. +.TP +\fBstatdata["minor"]\fP +Corresponds to the +.I st_minor +field in the +.IR "struct stat" . +This element is only present for device files. +.TP +\fBstatdata["blksize"]\fP +Corresponds to the +.I st_blksize +field in the +.IR "struct stat" , +if this field is present on your system. +(It is present on all modern systems that we know of.) +.TP +\fBstatdata["pmode"]\fP +A human-readable version of the mode value, such as printed by +.IR ls (1). +For example, \fB"-rwxr-xr-x"\fP. +.TP +\fBstatdata["linkval"]\fP +If the named file is a symbolic link, this element will exist +and its value is the value of the symbolic link (where the +symbolic link points to). +.TP +\fBstatdata["type"]\fP +The type of the file as a string. One of +\fB"file"\fP, +\fB"blockdev"\fP, +\fB"chardev"\fP, +\fB"directory"\fP, +\fB"socket"\fP, +\fB"fifo"\fP, +\fB"symlink"\fP, +\fB"door"\fP, +or +\fB"unknown"\fP. +Not all systems support all file types. +.SS fts() +The +.B fts() +function provides a hook to the +.IR fts (3) +set of routines for traversing file heirarchies. +Instead of returning data about one file at a time in a ``stream,'' +it fills in a multi-dimensional array with data about each file and +directory encountered in the requested heirarchies. +.PP +The arguments are as follows: +.TP +.B pathlist +An array of filenames. The element values are used; the index values are ignored. +.TP +.B flags +This should be the bitwise OR of one or more of the following +predefined constant flag values. At least one of +.B FTS_LOGICAL +or +.B FTS_PHYSICAL +must be provided; otherwise +.B fts() +returns an error value. +.RS +.TP +.B FTS_LOGICAL +Do a ``logical'' file traversal, where the information returned for +a symbolic link refers to the linked-to file, and not to the +symbolic link itself. +.TP +.B FTS_PHYSICAL +Do a ``physical'' file traversal, where the information returned for +a symbolic link refers to the symbolic link itself. +.TP +.B FTS_NOCHDIR +As a performance optimization, the +.IR fts (3) +routines change directory as they traverse a file heirarchy. +This flag disables that optimization. +.TP +.B FTS_COMFOLLOW +Immediatly follow a symbolic link named in +.BR pathlist , +whether or not +.B FTS_LOGICAL +is set. +.TP +.B FTS_SEEDOT +By default, the +.IR fts (3) +routines do not return entries for ``.'' and ``..''. +This option causes entries for ``..'' to also be included. +(The AWK extension always includes an entry for ``.'', see below.) +.TP +.B FTS_XDEV +During a traversal, do not cross onto a different mounted filesystem. +.RE +.TP +.B filedata +The +.B filedata +array is first cleared. +Then, +.B fts() +creates an element in +.B filedata +for every element in +.BR pathlist . +The index is the name of the directory or file given in +.BR pathlist . +The element for this index is itself an array. +There are two cases. +.RS +.TP +The path is a file. +In this case, the array contains at two or three elements: +.RS +.TP +\fB"path"\fP +The full path to this file, starting from the ``root'' that was given +in the +.B pathlist +array. +.TP +\fB"stat"\fP +This element is itself an array, containing the same information as provided +by the +.B stat() +function described earlier for its +.B statdata +argument. +The element may not be present if +.IR stat (2) +for the file failed. +.TP +\fB"error"\fP +If some kind of error was encountered, the array will also +contain an element named \fB"error"\fP, which is a string describing the error. +.RE +.TP +The path is a directory. +In this case, the array contains one element for each entry in the directory. +If an entry is a file, that element is as for files, just described. +If the entry is a directory, that element is (recursively), an array describing +the subdirectory. +If +.B FTS_SEEDOT +was provided in the flags, then there will also be an element named +\fB".."\fP. This element will be an array containing the data +as provided by +.BR stat() . +.sp +In addition, there will be an element whose index is \fB"."\fP. +This element is an array containing the same two or three elements +as for a file: +\fB"path"\fP, +\fB"stat"\fP, +and +\fB"error"\fP. +.RE +.PP +The +.B fts() +function returns 0 if there were no errors. Otherwise it returns \-1. +.SH NOTES +The AWK extension does not exactly mimic the interface of the +.IR fts (3) +routines, choosing instead to provide an interface that is based +on associative arrays, which should be more comfortable to use from +an AWK program. This includes the lack of a comparison function, since +.I gawk +already provides powerful array sorting facilities. While an +.IR fts_read() \-like +interface could have been provided, this felt less natural than +simply creating a multi-dimensional array to represent the file +heirarchy and its information. +... .SH BUGS +.SH EXAMPLE +.ft CW +.nf +.fi +.ft R +.SH "SEE ALSO" +.IR "GAWK: Effective AWK Programming" , +.IR fnmatch (3am), +.IR ordchr (3am), +.IR readfile (3am), +.IR rwarray (3am), +.IR time (3am). +.SH AUTHOR +Arnold Robbins, +.BR arnold@skeeve.com . +.SH COPYING PERMISSIONS +Copyright \(co 2012 +Free Software Foundation, Inc. +.PP +Permission is granted to make and distribute verbatim copies of +this manual page provided the copyright notice and this permission +notice are preserved on all copies. +.ig +Permission is granted to process this file through troff and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual page). +.. +.PP +Permission is granted to copy and distribute modified versions of this +manual page under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. +.PP +Permission is granted to copy and distribute translations of this +manual page into another language, under the above conditions for +modified versions, except that this permission notice may be stated in +a translation approved by the Foundation. diff --git a/extension/fnmatch.3am b/extension/fnmatch.3am new file mode 100644 index 00000000..eefa5dc4 --- /dev/null +++ b/extension/fnmatch.3am @@ -0,0 +1,116 @@ +.TH FNMATCH 3am "Jul 12 2012" "Free Software Foundation" "GNU Awk Extension Modules" +.SH NAME +fnmatch \- compare a string against a filename wildcard +.SH SYNOPSIS +.ft CW +@load "fnmatch" +.br +result = fnmatch(pattern, string, flags) +.ft R +.SH DESCRIPTION +The +.I fnmatch +extension provides an AWK interface to the +.IR fnmatch (3) +routine. It adds a single function named +.BR fnmatch() , +one constant +.RB ( FNM_NOMATCH ), +and an array of flag values named +.BR FNM . +.PP +The first argument is the filename wildcard to match, the second +is the filename string, and the third is either zero, +or the bitwise OR of one or more of the flags in the +.B FNM +array. +.PP +The return value is zero on success, +.B FNM_NOMATCH +if the string did not match the pattern, or +a different non-zero value if an error occurred. +.PP +The flags are follows: +.TP +\fBFNM["CASEFOLD"]\fP +Corresponds to the +.B FNM_CASEFOLD +flag as defined in +.IR fnmatch (3). +.TP +\fBFNM["FILE_NAME"]\fP +Corresponds to the +.B FNM_FILE_NAME +flag as defined in +.IR fnmatch (3). +.TP +\fBFNM["LEADING_DIR"]\fP +Corresponds to the +.B FNM_LEADING_DIR +flag as defined in +.IR fnmatch (3). +.TP +\fBFNM["NOESCAPE"]\fP +Corresponds to the +.B FNM_NOESCAPE +flag as defined in +.IR fnmatch (3). +.TP +\fBFNM["PATHNAME"]\fP +Corresponds to the +.B FNM_PATHNAME +flag as defined in +.IR fnmatch (3). +.TP +\fBFNM["PERIOD"]\fP +Corresponds to the +.B FNM_PERIOD +flag as defined in +.IR fnmatch (3). +.PP +... .SH NOTES +... .SH BUGS +.SH EXAMPLE +.ft CW +.nf +@load "fnmatch" +\&... +flags = or(FNM["PERIOD"], FNM["NOESCAPE"]) +if (fnmatch("*.a", "foo.c", flags) == FNM_NOMATCH) + print "no match" +.fi +.ft R +.SH "SEE ALSO" +.IR fnmatch (3), +.IR "GAWK: Effective AWK Programming" , +.IR filefuncs (3am), +.IR ordchr (3am), +.IR readfile (3am), +.IR rwarray (3am), +.IR time (3am). +.SH AUTHOR +Arnold Robbins, +.BR arnold@skeeve.com . +.SH COPYING PERMISSIONS +Copyright \(co 2012 +Free Software Foundation, Inc. +.PP +Permission is granted to make and distribute verbatim copies of +this manual page provided the copyright notice and this permission +notice are preserved on all copies. +.ig +Permission is granted to process this file through troff and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual page). +.. +.PP +Permission is granted to copy and distribute modified versions of this +manual page under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. +.PP +Permission is granted to copy and distribute translations of this +manual page into another language, under the above conditions for +modified versions, except that this permission notice may be stated in +a translation approved by the Foundation. diff --git a/extension/ordchr.3am b/extension/ordchr.3am new file mode 100644 index 00000000..f2aec9c2 --- /dev/null +++ b/extension/ordchr.3am @@ -0,0 +1,74 @@ +.TH ORDCHR 3am "Jul 11 2012" "Free Software Foundation" "GNU Awk Extension Modules" +.SH NAME +ordchr \- convert characters to strings and vice versa +.SH SYNOPSIS +.ft CW +@load "ordchr" +.br +number = ord("A") +.br +string = chr(65) +.ft R +.SH DESCRIPTION +The +.I ordchr +extension adds two functions named +.BR ord() . +and +.BR chr() , +as follows. +.TP +.B ord() +This function takes a string argument, and returns the +numeric value of the first character in the string. +.TP +.B chr() +This function takes a numeric argument and returns a string +whose first character is that represented by the number. +.PP +These functions are inspired by the Pascal language functions +of the same name. +... .SH NOTES +... .SH BUGS +.SH EXAMPLE +.ft CW +.nf +@load "ordchr" +\&... +printf("The numeric value of 'A' is %d\en", ord("A")) +printf("The string value of 65 is %s\en", chr(65)) +.fi +.ft R +.SH "SEE ALSO" +.IR "GAWK: Effective AWK Programming" , +.IR filefuncs (3am), +.IR fnmatch (3am), +.IR readfile (3am), +.IR rwarray (3am), +.IR time (3am). +.SH AUTHOR +Arnold Robbins, +.BR arnold@skeeve.com . +.SH COPYING PERMISSIONS +Copyright \(co 2012 +Free Software Foundation, Inc. +.PP +Permission is granted to make and distribute verbatim copies of +this manual page provided the copyright notice and this permission +notice are preserved on all copies. +.ig +Permission is granted to process this file through troff and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual page). +.. +.PP +Permission is granted to copy and distribute modified versions of this +manual page under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. +.PP +Permission is granted to copy and distribute translations of this +manual page into another language, under the above conditions for +modified versions, except that this permission notice may be stated in +a translation approved by the Foundation. diff --git a/extension/readfile.3am b/extension/readfile.3am new file mode 100644 index 00000000..76a38cad --- /dev/null +++ b/extension/readfile.3am @@ -0,0 +1,67 @@ +.TH READFILE 3am "Jul 11 2012" "Free Software Foundation" "GNU Awk Extension Modules" +.SH NAME +readfile \- return the entire contents of a file as a string +.SH SYNOPSIS +.ft CW +@load "readfile" +.br +result = readfile("/some/path") +.ft R +.SH DESCRIPTION +The +.I readfile +extension adds a single function named +.BR readfile() . +The argument is the name of the file to read. +The return value is a string containing the entire contents of +the requested file. +.PP +Upon error, the function returns the empty string and sets +.BR ERRNO . +... .SH NOTES +... .SH BUGS +.SH EXAMPLE +.ft CW +.nf +@load "readfile" +\&... +contents = readfile("/path/to/file"); +if (contents == "" && ERRNO != "") { + print("problem reading file", ERRNO) > "/dev/stderr" + ... +} +.fi +.ft R +.SH "SEE ALSO" +.IR "GAWK: Effective AWK Programming" , +.IR filefuncs (3am), +.IR fnmatch (3am), +.IR ordchr (3am), +.IR rwarray (3am), +.IR time (3am). +.SH AUTHOR +Arnold Robbins, +.BR arnold@skeeve.com . +.SH COPYING PERMISSIONS +Copyright \(co 2012 +Free Software Foundation, Inc. +.PP +Permission is granted to make and distribute verbatim copies of +this manual page provided the copyright notice and this permission +notice are preserved on all copies. +.ig +Permission is granted to process this file through troff and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual page). +.. +.PP +Permission is granted to copy and distribute modified versions of this +manual page under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. +.PP +Permission is granted to copy and distribute translations of this +manual page into another language, under the above conditions for +modified versions, except that this permission notice may be stated in +a translation approved by the Foundation. |