"Fossies" - the Fresh Open Source Software Archive

Member "gawk-5.1.0/extension/filefuncs.3am" (6 Feb 2020, 10590 Bytes) of package /linux/misc/gawk-5.1.0.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "filefuncs.3am": 5.0.1_vs_5.1.0.

    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 arnold@skeeve.com .
  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 :