Table of Contents
filestat
Table of Contents
Prototype: filestat(filename, field)
Return type: string
Description: Returns the requested file field field
for the file object
filename
.
If the file object does not exist, the function call fails and the variable does not expand.
Arguments:
filename
: the file or directory name to inspect, in the range: "?(/.*)field
: the requested field, with the following allowed values:size
: size in bytesgid
: group IDuid
: owner IDino
: inode numbernlink
: number of hard linksctime
: time of last change in Unix epoch formatatime
: last access time in Unix epoch formatmtime
: last modification time in Unix epoch formatmode
: file mode as a decimal numbermodeoct
: file mode as an octal number, e.g.10777
permstr
: permission string, e.g.-rwx---rwx
(not available on Windows)permoct
: permissions as an octal number, e.g.644
(not available on Windows)type
: file type (not available on Windows):block device
,character device
,directory
,FIFO/pipe
,symlink
,regular file
,socket
, orunknown
devno
: device number (drive letter on Windows, e.g.C:
)dev_minor
: minor device number (not available on Windows)dev_major
: major device number (not available on Windows)basename
: the file name minus the directorydirname
: the directory portion of the file namelinktarget
: if the file is asymlink
, its final target. The target is chased up to 32 levels of recursion. On Windows, this returns the file name itself.linktarget_shallow
: if the file is asymlink
, its first target. On Windows, this returns the file name itself.xattr
: a string with newline-separated extended attributes and SELinux contexts inkey=value<NEWLINE>key2=value2<NEWLINE>tag1<NEWLINE>tag2
format.
On Mac OS X, you can list and set extended attributes with the xattr
utility.
On SELinux, the contexts are the same as what you see with ls -Z
.
Example:
Prepare:
echo 1234567890 > FILE.txt
chmod 0755 FILE.txt
chown 0 FILE.txt
chgrp 0 FILE.txt
Run:
body common control
{
bundlesequence => { "example" };
}
bundle agent example
{
vars:
"file" string => "$(this.promise_filename).txt";
methods:
"fileinfo" usebundle => fileinfo("$(file)");
}
bundle agent fileinfo(f)
{
vars:
# use the full list if you want to see all the attributes!
# "fields" slist => splitstring("size,gid,uid,ino,nlink,ctime,atime,mtime,mode,modeoct,permstr,permoct,type,devno,dev_minor,dev_major,basename,dirname,linktarget,linktarget_shallow", ",", 999);
# ino (inode number), ctime (creation time),
# devno/dev_minor/dev_major (device numbers) were omitted but
# they are all integers
"fields" slist => splitstring("size,gid,uid,nlink,mode,modeoct,permstr,permoct,type,basename", ",", 999);
"stat[$(f)][$(fields)]" string => filestat($(f), $(fields));
reports:
"$(this.bundle): file $(stat[$(f)][basename]) has $(fields) = $(stat[$(f)][$(fields)])";
}
Output:
R: fileinfo: file filestat.cf.txt has size = 11
R: fileinfo: file filestat.cf.txt has gid = 0
R: fileinfo: file filestat.cf.txt has uid = 0
R: fileinfo: file filestat.cf.txt has nlink = 1
R: fileinfo: file filestat.cf.txt has mode = 33261
R: fileinfo: file filestat.cf.txt has modeoct = 100755
R: fileinfo: file filestat.cf.txt has permstr = -rwxr-xr-x
R: fileinfo: file filestat.cf.txt has permoct = 755
R: fileinfo: file filestat.cf.txt has type = regular file
R: fileinfo: file filestat.cf.txt has basename = filestat.cf.txt
Notes:
linktarget
will prepend the directory name to relative symlink targets, in order to be able to resolve them. Uselinktarget_shallow
to get the exact link as-is in case it is a relative link.- The list of fields may be extended as needed by CFEngine.
History:
- function introduced in version 3.5.0.
linktarget
andlinktarget_shallow
field options added in 3.6.0.
See also: dirname()
, fileexists()
, isdir()
, islink()
, isplain()
, lastnode()
, returnszero()
, splitstring()
.