Debian Codegraph @

upstream/debian-unstable/man3/filefuncs.3am

raw
1 .TH FILEFUNCS 3am "Feb 21 2018" "Free Software Foundation" "GNU Awk Extension Modules"
2 .SH NAME
3 filefuncs \- provide some file related functionality to gawk
4 .SH SYNOPSIS
5 .ft CW
6 @load "filefuncs"
7 .sp
8 result = chdir("/some/directory")
9 .sp
10 result = stat("/some/path", statdata [, follow])
11 .sp
12 flags = or(FTS_PHYSICAL, ...)
13 .br
14 result = fts(pathlist, flags, filedata)
15 .sp
16 result = statvfs("/some/path", fsdata)
17 .ft R
18 .SH DESCRIPTION
19 The
20 .I filefuncs
21 extension adds several functions that provide access to
22 file-related facilities.
23 .SS chdir()
24 The
25 .B chdir()
26 function is a direct hook to the
27 .IR chdir (2)
28 system call to change the current directory.
29 It returns zero
30 upon success or less than zero upon error.
31 In the latter case it updates
32 .BR ERRNO .
33 .SS stat()
34 The
35 .B stat()
36 function provides a hook into the
37 .IR stat (2)
38 system call.
39 It returns zero
40 upon success or less than zero upon error.
41 In the latter case it updates
42 .BR ERRNO .
43 By default, it uses
44 .IR lstat (2).
45 However, if passed a third argument, it uses
46 .IR stat (2),
47 instead.
48 .PP
49 In all cases, it clears the
50 .B statdata
51 array.
52 When the call is successful,
53 .B stat()
54 fills the
55 .B statdata
56 array with information retrieved from the filesystem, as follows:
57 .TP
58 \fBstatdata["name"]\fP
59 The name of the file, equal to the first argument passed to
60 .BR stat() .
61 .TP
62 \fBstatdata["dev"]\fP
63 Corresponds to the
64 .I st_dev
65 field in the
66 .IR "struct stat" .
67 .TP
68 \fBstatdata["ino"]\fP
69 Corresponds to the
70 .I st_ino
71 field in the
72 .IR "struct stat" .
73 .TP
74 \fBstatdata["mode"]\fP
75 Corresponds to the
76 .I st_mode
77 field in the
78 .IR "struct stat" .
79 .TP
80 \fBstatdata["nlink"]\fP
81 Corresponds to the
82 .I st_nlink
83 field in the
84 .IR "struct stat" .
85 .TP
86 \fBstatdata["uid"]\fP
87 Corresponds to the
88 .I st_uid
89 field in the
90 .IR "struct stat" .
91 .TP
92 \fBstatdata["gid"]\fP
93 Corresponds to the
94 .I st_gid
95 field in the
96 .IR "struct stat" .
97 .TP
98 \fBstatdata["size"]\fP
99 Corresponds to the
100 .I st_size
101 field in the
102 .IR "struct stat" .
103 .TP
104 \fBstatdata["atime"]\fP
105 Corresponds to the
106 .I st_atime
107 field in the
108 .IR "struct stat" .
109 .TP
110 \fBstatdata["mtime"]\fP
111 Corresponds to the
112 .I st_mtime
113 field in the
114 .IR "struct stat" .
115 .TP
116 \fBstatdata["ctime"]\fP
117 Corresponds to the
118 .I st_ctime
119 field in the
120 .IR "struct stat" .
121 .TP
122 \fBstatdata["rdev"]\fP
123 Corresponds to the
124 .I st_rdev
125 field in the
126 .IR "struct stat" .
127 This element is only present for device files.
128 .TP
129 \fBstatdata["major"]\fP
130 Corresponds to the
131 .I st_major
132 field in the
133 .IR "struct stat" .
134 This element is only present for device files.
135 .TP
136 \fBstatdata["minor"]\fP
137 Corresponds to the
138 .I st_minor
139 field in the
140 .IR "struct stat" .
141 This element is only present for device files.
142 .TP
143 \fBstatdata["blksize"]\fP
144 Corresponds to the
145 .I st_blksize
146 field in the
147 .IR "struct stat" ,
148 if this field is present on your system.
149 (It is present on all modern systems that we know of.)
150 .TP
151 \fBstatdata["pmode"]\fP
152 A human-readable version of the mode value, such as printed by
153 .IR ls (1).
154 For example, \fB"-rwxr-xr-x"\fP.
155 .TP
156 \fBstatdata["linkval"]\fP
157 If the named file is a symbolic link, this element will exist
158 and its value is the value of the symbolic link (where the
159 symbolic link points to).
160 .TP
161 \fBstatdata["type"]\fP
162 The type of the file as a string. One of
163 \fB"file"\fP,
164 \fB"blockdev"\fP,
165 \fB"chardev"\fP,
166 \fB"directory"\fP,
167 \fB"socket"\fP,
168 \fB"fifo"\fP,
169 \fB"symlink"\fP,
170 \fB"door"\fP,
171 or
172 \fB"unknown"\fP.
173 Not all systems support all file types.
174 .SS fts()
175 The
176 .B fts()
177 function provides a hook to the
178 .IR fts (3)
179 set of routines for traversing file hierarchies.
180 Instead of returning data about one file at a time in a stream,
181 it fills in a multi-dimensional array with data about each file and
182 directory encountered in the requested hierarchies.
183 .PP
184 The arguments are as follows:
185 .TP
186 .B pathlist
187 An array of filenames. The element values are used; the index values are ignored.
188 .TP
189 .B flags
190 This should be the bitwise OR of one or more of the following
191 predefined flag values. At least one of
192 .B FTS_LOGICAL
193 or
194 .B FTS_PHYSICAL
195 must be provided; otherwise
196 .B fts()
197 returns an error value and sets
198 .BR ERRNO .
199 .RS
200 .TP
201 .B FTS_LOGICAL
202 Do a ``logical'' file traversal, where the information returned for
203 a symbolic link refers to the linked-to file, and not to the
204 symbolic link itself.
205 This flag is mutually exclusive with
206 .BR FTS_PHYSICAL .
207 .TP
208 .B FTS_PHYSICAL
209 Do a ``physical'' file traversal, where the information returned for
210 a symbolic link refers to the symbolic link itself.
211 This flag is mutually exclusive with
212 .BR FTS_LOGICAL .
213 .TP
214 .B FTS_NOCHDIR
215 As a performance optimization, the
216 .IR fts (3)
217 routines change directory as they traverse a file hierarchy.
218 This flag disables that optimization.
219 .TP
220 .B FTS_COMFOLLOW
221 Immediately follow a symbolic link named in
222 .BR pathlist ,
223 whether or not
224 .B FTS_LOGICAL
225 is set.
226 .TP
227 .B FTS_SEEDOT
228 By default, the
229 .IR fts (3)
230 routines do not return entries for ``.'' and ``..''.
231 This option causes entries for ``..'' to also be included.
232 (The AWK extension always includes an entry for ``.'', see below.)
233 .TP
234 .B FTS_XDEV
235 During a traversal, do not cross onto a different mounted filesystem.
236 .TP
237 .B FTS_SKIP
238 When set, causes top level directories to not be descended into.
239 .RE
240 .TP
241 .B filedata
242 The
243 .B filedata
244 array is first cleared.
245 Then,
246 .B fts()
247 creates an element in
248 .B filedata
249 for every element in
250 .BR pathlist .
251 The index is the name of the directory or file given in
252 .BR pathlist .
253 The element for this index is itself an array.
254 There are two cases.
255 .RS
256 .TP
257 The path is a file.
258 In this case, the array contains two or three elements:
259 .RS
260 .TP
261 \fB"path"\fP
262 The full path to this file, starting from the ``root'' that was given
263 in the
264 .B pathlist
265 array.
266 .TP
267 \fB"stat"\fP
268 This element is itself an array, containing the same information as provided
269 by the
270 .B stat()
271 function described earlier for its
272 .B statdata
273 argument.
274 The element may not be present if
275 .IR stat (2)
276 for the file failed.
277 .TP
278 \fB"error"\fP
279 If some kind of error was encountered, the array will also
280 contain an element named \fB"error"\fP, which is a string describing the error.
281 .RE
282 .TP
283 The path is a directory.
284 In this case, the array contains one element for each entry in the directory.
285 If an entry is a file, that element is as for files, just described.
286 If the entry is a directory, that element is (recursively), an array describing
287 the subdirectory.
288 If
289 .B FTS_SEEDOT
290 was provided in the flags, then there will also be an element named
291 \fB".."\fP. This element will be an array containing the data
292 as provided by
293 .BR stat() .
294 .sp
295 In addition, there will be an element whose index is \fB"."\fP.
296 This element is an array containing the same two or three elements
297 as for a file:
298 \fB"path"\fP,
299 \fB"stat"\fP,
300 and
301 \fB"error"\fP.
302 .RE
303 .PP
304 The
305 .B fts()
306 function returns 0 if there were no errors. Otherwise it returns \-1.
307 .SS statvfs()
308 The
309 .B statvfs()
310 function provides a hook into the
311 .IR statvfs (2)
312 system call on systems that supply this system call.
313 It returns zero
314 upon success or less than zero upon error.
315 In the latter case it updates
316 .BR ERRNO .
317 .PP
318 When the call is successful,
319 .B statvfs()
320 fills the
321 .B fsdata
322 array with information retrieved about the filesystem, as follows:
323 .TP
324 \fBfsdata["bsize"]\fP
325 Corresponds to the
326 .B bsize
327 member in the
328 .IR "struct statvfs" .
329 .TP
330 \fBfsdata["frsize"]\fP
331 Corresponds to the
332 .I f_frsize
333 member in the
334 .IR "struct statvfs" .
335 .TP
336 \fBfsdata["blocks"]\fP
337 Corresponds to the
338 .I f_blocks
339 member in the
340 .IR "struct statvfs" .
341 .TP
342 \fBfsdata["bfree"]\fP
343 Corresponds to the
344 .I f_bfree
345 member in the
346 .IR "struct statvfs" .
347 .TP
348 \fBfsdata["bavail"]\fP
349 Corresponds to the
350 .I f_bavail
351 member in the
352 .IR "struct statvfs" .
353 .TP
354 \fBfsdata["files"]\fP
355 Corresponds to the
356 .I f_files
357 member in the
358 .IR "struct statvfs" .
359 .TP
360 \fBfsdata["ffree"]\fP
361 Corresponds to the
362 .I f_ffree
363 member in the
364 .IR "struct statvfs" .
365 .TP
366 \fBfsdata["favail"]\fP
367 Corresponds to the
368 .I f_favail
369 member in the
370 .IR "struct statvfs" .
371 .TP
372 \fBfsdata["fsid"]\fP
373 Corresponds to the
374 .I f_fsid
375 member in the
376 .IR "struct statvfs" .
377 This member is not available on all systems.
378 .TP
379 \fBfsdata["flag"]\fP
380 Corresponds to the
381 .I f_flag
382 member in the
383 .IR "struct statvfs" .
384 .TP
385 \fBfsdata["namemax"]\fP
386 Corresponds to the
387 .I f_namemax
388 member in the
389 .IR "struct statvfs" .
390 .SH NOTES
391 The AWK
392 .B fts()
393 extension does not exactly mimic the interface of the
394 .IR fts (3)
395 routines, choosing instead to provide an interface that is based
396 on associative arrays, which should be more comfortable to use from
397 an AWK program. This includes the lack of a comparison function, since
398 .I gawk
399 already provides powerful array sorting facilities. While an
400 .IR fts_read() \-like
401 interface could have been provided, this felt less natural than
402 simply creating a multi-dimensional array to represent the file
403 hierarchy and its information.
404 .PP
405 Nothing prevents AWK code from changing the predefined
406 .BI FTS_ xx
407 values, but doing so may cause strange results when
408 the changed values are passed to
409 .BR fts() .
410 .SH BUGS
411 There are many more file-related functions for which AWK
412 interfaces would be desirable.
413 .PP
414 It's not clear why I thought adding
415 .B FTS_SKIP
416 was a good idea.
417 .SH EXAMPLE
418 See
419 .B test/fts.awk
420 in the
421 .I gawk
422 distribution for an example.
423 .SH "SEE ALSO"
424 .IR "GAWK: Effective AWK Programming" ,
425 .IR fnmatch (3am),
426 .IR fork (3am),
427 .IR inplace (3am),
428 .IR ordchr (3am),
429 .IR readdir (3am),
430 .IR readfile (3am),
431 .IR revoutput (3am),
432 .IR rwarray (3am),
433 .IR time (3am).
434 .PP
435 .IR chdir (2),
436 .IR fts (3),
437 .IR stat (2),
438 .IR statvfs (2).
439 .SH AUTHOR
440 Arnold Robbins,
441 .BR [email protected] .
442 .SH COPYING PERMISSIONS
443 Copyright \(co 2012, 2013, 2018, 2019,
444 Free Software Foundation, Inc.
445 .PP
446 Permission is granted to make and distribute verbatim copies of
447 this manual page provided the copyright notice and this permission
448 notice are preserved on all copies.
449 .ig
450 Permission is granted to process this file through troff and print the
451 results, provided the printed document carries copying permission
452 notice identical to this one except for the removal of this paragraph
453 (this paragraph not being relevant to the printed manual page).
454 ..
455 .PP
456 Permission is granted to copy and distribute modified versions of this
457 manual page under the conditions for verbatim copying, provided that
458 the entire resulting derived work is distributed under the terms of a
459 permission notice identical to this one.
460 .PP
461 Permission is granted to copy and distribute translations of this
462 manual page into another language, under the above conditions for
463 modified versions, except that this permission notice may be stated in
464 a translation approved by the Foundation.
465 .\" vim: set filetype=nroff :