1FILEFUNCS(3am)             GNU Awk Extension Modules            FILEFUNCS(3am)
2
3
4

NAME

6       filefuncs - provide some file related functionality to gawk
7

SYNOPSIS

9       @load "filefuncs"
10
11       result = chdir("/some/directory")
12
13       result = stat("/some/path", statdata [, follow])
14
15       flags = or(FTS_PHYSICAL, ...)
16       result = fts(pathlist, flags, filedata)
17

DESCRIPTION

19       The  filefuncs  extension adds several functions that provide access to
20       file-related facilities.
21
22   chdir()
23       The chdir() function is a direct hook to the chdir(2)  system  call  to
24       change  the  current  directory.   It returns zero upon success or less
25       than zero upon error.  In the latter case it updates ERRNO.
26
27   stat()
28       The stat() function provides a hook into the stat(2) system  call.   It
29       returns  zero upon success or less than zero upon error.  In the latter
30       case it updates ERRNO.  By default,  it  uses  lstat(2).   However,  if
31       passed a third argument, it uses stat(2), instead.
32
33       In  all cases, it clears the statdata array.  When the call is success‐
34       ful, stat() fills the statdata array with  information  retrieved  from
35       the filesystem, as follows:
36
37       statdata["name"]
38              The name of the file.
39
40       statdata["dev"]
41              Corresponds to the st_dev field in the struct stat.
42
43       statdata["ino"]
44              Corresponds to the st_ino field in the struct stat.
45
46       statdata["mode"]
47              Corresponds to the st_mode field in the struct stat.
48
49       statdata["nlink"]
50              Corresponds to the st_nlink field in the struct stat.
51
52       statdata["uid"]
53              Corresponds to the st_uid field in the struct stat.
54
55       statdata["gid"]
56              Corresponds to the st_gid field in the struct stat.
57
58       statdata["size"]
59              Corresponds to the st_size field in the struct stat.
60
61       statdata["atime"]
62              Corresponds to the st_atime field in the struct stat.
63
64       statdata["mtime"]
65              Corresponds to the st_mtime field in the struct stat.
66
67       statdata["ctime"]
68              Corresponds to the st_ctime field in the struct stat.
69
70       statdata["rdev"]
71              Corresponds  to the st_rdev field in the struct stat.  This ele‐
72              ment is only present for device files.
73
74       statdata["major"]
75              Corresponds to the st_major field in the struct stat.  This ele‐
76              ment is only present for device files.
77
78       statdata["minor"]
79              Corresponds to the st_minor field in the struct stat.  This ele‐
80              ment is only present for device files.
81
82       statdata["blksize"]
83              Corresponds to the st_blksize field in the struct stat, if  this
84              field  is  present on your system.  (It is present on all modern
85              systems that we know of.)
86
87       statdata["pmode"]
88              A human-readable version of the mode value, such as  printed  by
89              ls(1).  For example, "-rwxr-xr-x".
90
91       statdata["linkval"]
92              If  the  named  file is a symbolic link, this element will exist
93              and its value is the value of the symbolic link (where the  sym‐
94              bolic link points to).
95
96       statdata["type"]
97              The  type  of  the  file as a string. One of "file", "blockdev",
98              "chardev", "directory", "socket", "fifo", "symlink", "door",  or
99              "unknown".  Not all systems support all file types.
100
101   fts()
102       The  fts()  function  provides a hook to the fts(3) set of routines for
103       traversing file hierarchies.  Instead of returning data about one  file
104       at  a time in a stream, it fills in a multi-dimensional array with data
105       about each file and directory encountered in the requested hierarchies.
106
107       The arguments are as follows:
108
109       pathlist
110              An array of filenames.  The element values are used;  the  index
111              values are ignored.
112
113       flags  This  should  be  the bitwise OR of one or more of the following
114              predefined  flag  values.   At  least  one  of  FTS_LOGICAL   or
115              FTS_PHYSICAL  must be provided; otherwise fts() returns an error
116              value and sets ERRNO.
117
118              FTS_LOGICAL
119                     Do a ``logical'' file traversal,  where  the  information
120                     returned  for  a  symbolic  link  refers to the linked-to
121                     file, and not to the symbolic link itself.  This flag  is
122                     mutually exclusive with FTS_PHYSICAL.
123
124              FTS_PHYSICAL
125                     Do  a  ``physical'' file traversal, where the information
126                     returned for a symbolic link refers to the symbolic  link
127                     itself.   This  flag is mutually exclusive with FTS_LOGI‐
128                     CAL.
129
130              FTS_NOCHDIR
131                     As a performance optimization, the fts(3) routines change
132                     directory  as  they traverse a file hierarchy.  This flag
133                     disables that optimization.
134
135              FTS_COMFOLLOW
136                     Immediately follow a symbolic  link  named  in  pathlist,
137                     whether or not FTS_LOGICAL is set.
138
139              FTS_SEEDOT
140                     By default, the fts(3) routines do not return entries for
141                     ``.'' and ``..''.  This option causes entries for  ``..''
142                     to  also be included.  (The AWK extension always includes
143                     an entry for ``.'', see below.)
144
145              FTS_XDEV
146                     During a traversal, do not cross onto a different mounted
147                     filesystem.
148
149       filedata
150              The  filedata  array  is  first cleared.  Then, fts() creates an
151              element in filedata for every element in pathlist.  The index is
152              the  name  of the directory or file given in pathlist.  The ele‐
153              ment for this index is itself an array.  There are two cases.
154
155              The path is a file.
156                     In this case, the array contains two or three elements:
157
158                     "path" The full path to  this  file,  starting  from  the
159                            ``root'' that was given in the pathlist array.
160
161                     "stat" This  element  is  itself an array, containing the
162                            same information as provided by the  stat()  func‐
163                            tion  described earlier for its statdata argument.
164                            The element may not be present if stat(2) for  the
165                            file failed.
166
167                     "error"
168                            If  some  kind of error was encountered, the array
169                            will also contain an element named "error",  which
170                            is a string describing the error.
171
172              The path is a directory.
173                     In  this  case,  the  array contains one element for each
174                     entry in the directory.  If an entry is a file, that ele‐
175                     ment  is as for files, just described.  If the entry is a
176                     directory,  that  element  is  (recursively),  an   array
177                     describing  the subdirectory.  If FTS_SEEDOT was provided
178                     in the flags, then there will also be  an  element  named
179                     "..".   This element will be an array containing the data
180                     as provided by stat().
181
182                     In addition, there will be an element whose index is ".".
183                     This element is an array containing the same two or three
184                     elements as for a file: "path", "stat", and "error".
185
186       The fts() function returns 0 if there  were  no  errors.  Otherwise  it
187       returns -1.
188

NOTES

190       The  AWK  fts()  extension  does not exactly mimic the interface of the
191       fts(3) routines, choosing instead to provide an interface that is based
192       on  associative arrays, which should be more comfortable to use from an
193       AWK program.  This includes the lack of a  comparison  function,  since
194       gawk  already  provides  powerful  array  sorting facilities.  While an
195       fts_read()-like interface could have been provided, this felt less nat‐
196       ural  than  simply  creating a multi-dimensional array to represent the
197       file hierarchy and its information.
198
199       Nothing prevents AWK code from changing the predefined  FTS_xx  values,
200       but  doing  so  may  cause  strange results when the changed values are
201       passed to fts().
202

BUGS

204       There are many more file-related functions  for  which  AWK  interfaces
205       would be desirable.
206

EXAMPLE

208       See test/fts.awk in the gawk distribution for an example.
209

SEE ALSO

211       GAWK: Effective AWK Programming, fnmatch(3am), fork(3am), inplace(3am),
212       ordchr(3am), readdir(3am), readfile(3am), revoutput(3am), rwarray(3am),
213       time(3am).
214
215       chdir(2), fts(3), stat(2).
216

AUTHOR

218       Arnold Robbins, arnold@skeeve.com.
219

COPYING PERMISSIONS

221       Copyright © 2012, 2013, Free Software Foundation, Inc.
222
223       Permission  is  granted  to make and distribute verbatim copies of this
224       manual page provided the copyright notice and  this  permission  notice
225       are preserved on all copies.
226
227       Permission  is granted to copy and distribute modified versions of this
228       manual page under the conditions for verbatim  copying,  provided  that
229       the  entire  resulting derived work is distributed under the terms of a
230       permission notice identical to this one.
231
232       Permission is granted to copy and distribute translations of this  man‐
233       ual page into another language, under the above conditions for modified
234       versions, except that this permission notice may be stated in a  trans‐
235       lation approved by the Foundation.
236
237
238
239Free Software Foundation          Jan 15 2013                   FILEFUNCS(3am)
Impressum