summaryrefslogtreecommitdiffstats
path: root/upstream/opensuse-leap-15-6/man3/filefuncs.3am
blob: e5be1e99ab8c3757d342aad154d1105ff55468e4 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
.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 hierarchies.
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 hierarchies.
.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 hierarchy.
This flag disables that optimization.
.TP
.B FTS_COMFOLLOW
Immediately 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
hierarchy and its information.
.PP
Nothing prevents AWK code from changing the predefined
.BI FTS_ xx
values, but doing so 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.
.\" vim: set filetype=nroff :