1FILEFUNCS(3am) GNU Awk Extension Modules FILEFUNCS(3am)
2
6 filefuncs - provide some file related functionality to gawk
7
9 @load "filefuncs"
10 result = chdir("/some/directory")
12 result = stat("/some/path", statdata [, follow])
14 flags = or(FTS_PHYSICAL, ...)
16 result = fts(pathlist, flags, filedata)
17 result = statvfs("/some/path", fsdata)
19
21 The filefuncs extension adds several functions that provide access to
22 file-related facilities.
23 chdir()
25 The chdir() function is a direct hook to the chdir(2) system call to
26 change the current directory. It returns zero upon success or less
27 than zero upon error. In the latter case it updates ERRNO.
28 stat()
30 The stat() function provides a hook into the stat(2) system call. It
31 returns zero upon success or less than zero upon error. In the latter
32 case it updates ERRNO. By default, it uses lstat(2). However, if
33 passed a third argument, it uses stat(2), instead.
34 In all cases, it clears the statdata array. When the call is success‐
36 ful, stat() fills the statdata array with information retrieved from
37 the filesystem, as follows:
38 statdata["name"]
40 The name of the file, equal to the first argument passed to
41 stat().
42 statdata["dev"]
44 Corresponds to the st_dev field in the struct stat.
45 statdata["ino"]
47 Corresponds to the st_ino field in the struct stat.
48 statdata["mode"]
50 Corresponds to the st_mode field in the struct stat.
51 statdata["nlink"]
53 Corresponds to the st_nlink field in the struct stat.
54 statdata["uid"]
56 Corresponds to the st_uid field in the struct stat.
57 statdata["gid"]
59 Corresponds to the st_gid field in the struct stat.
60 statdata["size"]
62 Corresponds to the st_size field in the struct stat.
63 statdata["atime"]
65 Corresponds to the st_atime field in the struct stat.
66 statdata["mtime"]
68 Corresponds to the st_mtime field in the struct stat.
69 statdata["ctime"]
71 Corresponds to the st_ctime field in the struct stat.
72 statdata["rdev"]
74 Corresponds to the st_rdev field in the struct stat. This ele‐
75 ment is only present for device files.
76 statdata["major"]
78 Corresponds to the st_major field in the struct stat. This ele‐
79 ment is only present for device files.
80 statdata["minor"]
82 Corresponds to the st_minor field in the struct stat. This ele‐
83 ment is only present for device files.
84 statdata["blksize"]
86 Corresponds to the st_blksize field in the struct stat, if this
87 field is present on your system. (It is present on all modern
88 systems that we know of.)
89 statdata["pmode"]
91 A human-readable version of the mode value, such as printed by
92 ls(1). For example, "-rwxr-xr-x".
93 statdata["linkval"]
95 If the named file is a symbolic link, this element will exist
96 and its value is the value of the symbolic link (where the sym‐
97 bolic link points to).
98 statdata["type"]
100 The type of the file as a string. One of "file", "blockdev",
101 "chardev", "directory", "socket", "fifo", "symlink", "door", or
102 "unknown". Not all systems support all file types.
103 fts()
105 The fts() function provides a hook to the fts(3) set of routines for
106 traversing file hierarchies. Instead of returning data about one file
107 at a time in a stream, it fills in a multi-dimensional array with data
108 about each file and directory encountered in the requested hierarchies.
109 The arguments are as follows:
111 pathlist
113 An array of filenames. The element values are used; the index
114 values are ignored.
115 flags This should be the bitwise OR of one or more of the following
117 predefined flag values. At least one of FTS_LOGICAL or
118 FTS_PHYSICAL must be provided; otherwise fts() returns an error
119 value and sets ERRNO.
120 FTS_LOGICAL
122 Do a ``logical'' file traversal, where the information
123 returned for a symbolic link refers to the linked-to
124 file, and not to the symbolic link itself. This flag is
125 mutually exclusive with FTS_PHYSICAL.
126 FTS_PHYSICAL
128 Do a ``physical'' file traversal, where the information
129 returned for a symbolic link refers to the symbolic link
130 itself. This flag is mutually exclusive with FTS_LOGI‐
131 CAL.
132 FTS_NOCHDIR
134 As a performance optimization, the fts(3) routines change
135 directory as they traverse a file hierarchy. This flag
136 disables that optimization.
137 FTS_COMFOLLOW
139 Immediately follow a symbolic link named in pathlist,
140 whether or not FTS_LOGICAL is set.
141 FTS_SEEDOT
143 By default, the fts(3) routines do not return entries for
144 ``.'' and ``..''. This option causes entries for ``..''
145 to also be included. (The AWK extension always includes
146 an entry for ``.'', see below.)
147 FTS_XDEV
149 During a traversal, do not cross onto a different mounted
150 filesystem.
151 FTS_SKIP
153 When set, causes top level directories to not be
154 descended into.
155 filedata
157 The filedata array is first cleared. Then, fts() creates an
158 element in filedata for every element in pathlist. The index is
159 the name of the directory or file given in pathlist. The ele‐
160 ment for this index is itself an array. There are two cases.
161 The path is a file.
163 In this case, the array contains two or three elements:
164 "path" The full path to this file, starting from the
166 ``root'' that was given in the pathlist array.
167 "stat" This element is itself an array, containing the
169 same information as provided by the stat() func‐
170 tion described earlier for its statdata argument.
171 The element may not be present if stat(2) for the
172 file failed.
173 "error"
175 If some kind of error was encountered, the array
176 will also contain an element named "error", which
177 is a string describing the error.
178 The path is a directory.
180 In this case, the array contains one element for each
181 entry in the directory. If an entry is a file, that ele‐
182 ment is as for files, just described. If the entry is a
183 directory, that element is (recursively), an array
184 describing the subdirectory. If FTS_SEEDOT was provided
185 in the flags, then there will also be an element named
186 "..". This element will be an array containing the data
187 as provided by stat().
188 In addition, there will be an element whose index is ".".
190 This element is an array containing the same two or three
191 elements as for a file: "path", "stat", and "error".
192 The fts() function returns 0 if there were no errors. Otherwise it
194 returns -1.
195 statvfs()
197 The statvfs() function provides a hook into the statvfs(2) system call
198 on systems that supply this system call. It returns zero upon success
199 or less than zero upon error. In the latter case it updates ERRNO.
200 When the call is successful, statvfs() fills the fsdata array with
202 information retrieved about the filesystem, as follows:
203 fsdata["bsize"]
205 Corresponds to the bsize member in the struct statvfs.
206 fsdata["frsize"]
208 Corresponds to the f_frsize member in the struct statvfs.
209 fsdata["blocks"]
211 Corresponds to the f_blocks member in the struct statvfs.
212 fsdata["bfree"]
214 Corresponds to the f_bfree member in the struct statvfs.
215 fsdata["bavail"]
217 Corresponds to the f_bavail member in the struct statvfs.
218 fsdata["files"]
220 Corresponds to the f_files member in the struct statvfs.
221 fsdata["ffree"]
223 Corresponds to the f_ffree member in the struct statvfs.
224 fsdata["favail"]
226 Corresponds to the f_favail member in the struct statvfs.
227 fsdata["fsid"]
229 Corresponds to the f_fsid member in the struct statvfs. This
230 member is not available on all systems.
231 fsdata["flag"]
233 Corresponds to the f_flag member in the struct statvfs.
234 fsdata["namemax"]
236 Corresponds to the f_namemax member in the struct statvfs.
237
239 The AWK fts() extension does not exactly mimic the interface of the
240 fts(3) routines, choosing instead to provide an interface that is based
241 on associative arrays, which should be more comfortable to use from an
242 AWK program. This includes the lack of a comparison function, since
243 gawk already provides powerful array sorting facilities. While an
244 fts_read()-like interface could have been provided, this felt less nat‐
245 ural than simply creating a multi-dimensional array to represent the
246 file hierarchy and its information.
247 Nothing prevents AWK code from changing the predefined FTS_xx values,
249 but doing so may cause strange results when the changed values are
250 passed to fts().
251
253 There are many more file-related functions for which AWK interfaces
254 would be desirable.
255 It's not clear why I thought adding FTS_SKIP was a good idea.
257
259 See test/fts.awk in the gawk distribution for an example.
260
262 GAWK: Effective AWK Programming, fnmatch(3am), fork(3am), inplace(3am),
263 ordchr(3am), readdir(3am), readfile(3am), revoutput(3am), rwarray(3am),
264 time(3am).
265 chdir(2), fts(3), stat(2), statvfs(2).
267
269 Arnold Robbins, arnold@skeeve.com.
270
272 Copyright © 2012, 2013, 2018, 2019, Free Software Foundation, Inc.
273 Permission is granted to make and distribute verbatim copies of this
275 manual page provided the copyright notice and this permission notice
276 are preserved on all copies.
277 Permission is granted to copy and distribute modified versions of this
279 manual page under the conditions for verbatim copying, provided that
280 the entire resulting derived work is distributed under the terms of a
281 permission notice identical to this one.
282 Permission is granted to copy and distribute translations of this man‐
284 ual page into another language, under the above conditions for modified
285 versions, except that this permission notice may be stated in a trans‐
286 lation approved by the Foundation.
287Free Software Foundation Feb 21 2018 FILEFUNCS(3am)