| .TH FILEFUNCS 3am "Jan 15 2013" "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 [, follow]) |
| .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. |
| It returns zero |
| upon success or less than zero upon error. |
| In the latter case it updates |
| .BR ERRNO . |
| By default, it uses |
| .IR lstat (2). |
| However, if passed a third argument, it uses |
| .IR stat (2), |
| instead. |
| .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 flag values. At least one of |
| .B FTS_LOGICAL |
| or |
| .B FTS_PHYSICAL |
| must be provided; otherwise |
| .B fts() |
| returns an error value and sets |
| .BR ERRNO . |
| .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. |
| This flag is mutually exclusive with |
| .BR FTS_PHYSICAL . |
| .TP |
| .B FTS_PHYSICAL |
| Do a ``physical'' file traversal, where the information returned for |
| a symbolic link refers to the symbolic link itself. |
| This flag is mutually exclusive with |
| .BR FTS_LOGICAL . |
| .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 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 |
| .B fts() |
| 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. |
| .PP |
| Nothing prevents AWK code from changing the predefined |
| .BI FTS_ xx |
| values, but doing so is may cause strange results when |
| the changed values are passed to |
| .BR fts() . |
| .SH BUGS |
| There are many more file-related functions for which AWK |
| interfaces would be desirable. |
| .SH EXAMPLE |
| See |
| .B test/fts.awk |
| in the |
| .I gawk |
| distribution for an example. |
| .SH "SEE ALSO" |
| .IR "GAWK: Effective AWK Programming" , |
| .IR fnmatch (3am), |
| .IR fork (3am), |
| .IR inplace (3am), |
| .IR ordchr (3am), |
| .IR readdir (3am), |
| .IR readfile (3am), |
| .IR revoutput (3am), |
| .IR rwarray (3am), |
| .IR time (3am). |
| .PP |
| .IR chdir (2), |
| .IR fts (3), |
| .IR stat (2). |
| .SH AUTHOR |
| Arnold Robbins, |
| .BR arnold@skeeve.com . |
| .SH COPYING PERMISSIONS |
| Copyright \(co 2012, 2013, |
| 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. |