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
19 The filefuncs extension adds several functions that provide access to
20 file-related facilities.
21 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 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 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 statdata["name"]
38 The name of the file.
39 statdata["dev"]
41 Corresponds to the st_dev field in the struct stat.
42 statdata["ino"]
44 Corresponds to the st_ino field in the struct stat.
45 statdata["mode"]
47 Corresponds to the st_mode field in the struct stat.
48 statdata["nlink"]
50 Corresponds to the st_nlink field in the struct stat.
51 statdata["uid"]
53 Corresponds to the st_uid field in the struct stat.
54 statdata["gid"]
56 Corresponds to the st_gid field in the struct stat.
57 statdata["size"]
59 Corresponds to the st_size field in the struct stat.
60 statdata["atime"]
62 Corresponds to the st_atime field in the struct stat.
63 statdata["mtime"]
65 Corresponds to the st_mtime field in the struct stat.
66 statdata["ctime"]
68 Corresponds to the st_ctime field in the struct stat.
69 statdata["rdev"]
71 Corresponds to the st_rdev field in the struct stat. This ele‐
72 ment is only present for device files.
73 statdata["major"]
75 Corresponds to the st_major field in the struct stat. This ele‐
76 ment is only present for device files.
77 statdata["minor"]
79 Corresponds to the st_minor field in the struct stat. This ele‐
80 ment is only present for device files.
81 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 statdata["pmode"]
88 A human-readable version of the mode value, such as printed by
89 ls(1). For example, "-rwxr-xr-x".
90 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 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 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 The arguments are as follows:
108 pathlist
110 An array of filenames. The element values are used; the index
111 values are ignored.
112 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 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 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 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 FTS_COMFOLLOW
136 Immediately follow a symbolic link named in pathlist,
137 whether or not FTS_LOGICAL is set.
138 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 FTS_XDEV
146 During a traversal, do not cross onto a different mounted
147 filesystem.
148 FTS_SKIP
150 When set, causes top level directories to not be
151 descended into.
152 filedata
154 The filedata array is first cleared. Then, fts() creates an
155 element in filedata for every element in pathlist. The index is
156 the name of the directory or file given in pathlist. The ele‐
157 ment for this index is itself an array. There are two cases.
158 The path is a file.
160 In this case, the array contains two or three elements:
161 "path" The full path to this file, starting from the
163 ``root'' that was given in the pathlist array.
164 "stat" This element is itself an array, containing the
166 same information as provided by the stat() func‐
167 tion described earlier for its statdata argument.
168 The element may not be present if stat(2) for the
169 file failed.
170 "error"
172 If some kind of error was encountered, the array
173 will also contain an element named "error", which
174 is a string describing the error.
175 The path is a directory.
177 In this case, the array contains one element for each
178 entry in the directory. If an entry is a file, that ele‐
179 ment is as for files, just described. If the entry is a
180 directory, that element is (recursively), an array
181 describing the subdirectory. If FTS_SEEDOT was provided
182 in the flags, then there will also be an element named
183 "..". This element will be an array containing the data
184 as provided by stat().
185 In addition, there will be an element whose index is ".".
187 This element is an array containing the same two or three
188 elements as for a file: "path", "stat", and "error".
189 The fts() function returns 0 if there were no errors. Otherwise it
191 returns -1.
192
194 The AWK fts() extension does not exactly mimic the interface of the
195 fts(3) routines, choosing instead to provide an interface that is based
196 on associative arrays, which should be more comfortable to use from an
197 AWK program. This includes the lack of a comparison function, since
198 gawk already provides powerful array sorting facilities. While an
199 fts_read()-like interface could have been provided, this felt less nat‐
200 ural than simply creating a multi-dimensional array to represent the
201 file hierarchy and its information.
202 Nothing prevents AWK code from changing the predefined FTS_xx values,
204 but doing so may cause strange results when the changed values are
205 passed to fts().
206
208 There are many more file-related functions for which AWK interfaces
209 would be desirable.
210 It's not clear why I thought adding FTS_SKIP was a good idea.
212
214 See test/fts.awk in the gawk distribution for an example.
215
217 GAWK: Effective AWK Programming, fnmatch(3am), fork(3am), inplace(3am),
218 ordchr(3am), readdir(3am), readfile(3am), revoutput(3am), rwarray(3am),
219 time(3am).
220 chdir(2), fts(3), stat(2).
222
224 Arnold Robbins, arnold@skeeve.com.
225
227 Copyright © 2012, 2013, 2018, Free Software Foundation, Inc.
228 Permission is granted to make and distribute verbatim copies of this
230 manual page provided the copyright notice and this permission notice
231 are preserved on all copies.
232 Permission is granted to copy and distribute modified versions of this
234 manual page under the conditions for verbatim copying, provided that
235 the entire resulting derived work is distributed under the terms of a
236 permission notice identical to this one.
237 Permission is granted to copy and distribute translations of this man‐
239 ual page into another language, under the above conditions for modified
240 versions, except that this permission notice may be stated in a trans‐
241 lation approved by the Foundation.
242Free Software Foundation Feb 21 2018 FILEFUNCS(3am)