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.10777permstr: 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, orunknowndevno: 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>tag2format.
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:
code
echo 1234567890 > FILE.txt
chmod 0755 FILE.txt
chown 0 FILE.txt
chgrp 0 FILE.txt
Run:
code
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:
code
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:
linktargetwill prepend the directory name to relative symlink targets, in order to be able to resolve them. Uselinktarget_shallowto 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.
linktargetandlinktarget_shallowfield options added in 3.6.0.
See also: dirname(), fileexists(), isdir(), islink(), isplain(), lastnode(), returnszero(), splitstring().