sysutil - file and system utilities

`sysutil` - file and system utilities

SYNOPSIS

<sysutil $action [option ...] $arg [...]>

DESCRIPTION
The sysutil function provides various file and system utilities. The $action argument determines the action; its possible values and the expected syntax of successive arguments are as follows:

mkdir or md $dir [$dir ...] Creates each directory named in $dir and successive arguments. If a permissions mode is given as an option (see below), the directory will be created with that mode; the default is 0777. In either case the mode is masked by the process's umask.
chown or lchown $owner $file [$file ...] Changes ownership of each file named by $file and successive arguments to the user and/or group named by the parallel value of $owner. If there are more file values than $owner values, the last $owner value is re-used. If the owner value has a period or colon appended, an optional group name may appear afterwards, in which case the group will be changed as well. If the group name is empty, the named user's default group will be used. If the named user is empty but a group is present (e.g. value starts with period or colon), only the group is changed; in this case the behavior is that of chgrp or lchgrp. If lchown is used, the owner of symlinks is changed instead of the file the symbolic link points to. Note: These actions are unimplemented under Windows.
chgrp or lchgrp $group $file [$file ...] Changes the group of each file named by $file and successive arguments to the group named by the corresponding value of $group. If there are more file values than $group values, the last $group value is re-used. If lchgrp is used instead of chgrp, the group of symlinks is changed instead of the file the symbolic link points to. Note: These actions are unimplemented under Windows.
chmod $mode $file [$file ...] Changes the file permissions of each file named by $file and successive arguments to the mode named by the parallel value of $mode. If there are more file values than $mode values, the last $mode value is re-used. A mode value may be octal numeric (e.g. "0666") or symbolic ("ugo+rw").
attrib $attrs $file [$file ...] Changes the file attributes of each file named by $file and successive arguments to the value named by the parallel value of $attrs. If there are more file values than $attrs values, the last $attrs value is re-used. An attribute value may be octal numeric (e.g. "040" for the archive bit) or symbolic. Symbolic values follow a similar syntax to chmod symbolic values: {+|-|=}token[,token...][,{+|-|=}token[,token...]], i.e. one of the operator characters plus, minus or equals, followed by zero or more comma-separated attribute tokens. The possible tokens are: readonly, hidden, system, volumelabel, directory, archive, device, normal, temporary, sparsefile, reparsepoint, compressed, offline, notcontentindexed, encrypted. Not all attributes are settable, e.g. the directory and device attributes cannot be modified. The normal attribute, if set, must be set alone and with the set (=) operator. This is a Windows-specific operation; on other OSes (e.g. Unix), attrib may be emulated to a limited extent, and chmod is preferred. Added in version 5.01.1245200000 20090616.
rm or del or delete $file [$file ...] Removes each file named by $file and successive arguments.
rmdir or rd $dir [$dir ...] Removes each directory named by $dir and successive arguments.
mv or rename $src [$src ...] $dest Moves each file named by $src and successive arguments (except the last) to the corresponding value of $dest. If there are more source values than $dest values (either as given or due to wildcard globbing or recursion), the $dest value must exist and be a directory, in which case the source files are moved into it. Moving files across filesystems is supported.
cp or copy $src [$src ...] $dest Copies each file named by $src and successive arguments (except the last) to the corresponding value of $dest. If there are more source values than $dest values (either as given or due to wildcard globbing or recursion), the $dest value must exist and be a directory, in which case the source files are copied into it.
link or symlink $target [$target ...] $name Creates a link $name to the specified $target. If there are more targets than names, the last $name must be a directory, in which case the links are created in it. If symlink is used instead of link, a symbolic link instead of a hard link is created. Note: These actions are unimplemented under Windows.
sync Calls sync() to flush system write buffers to disk. Not implemented under Windows. Added in version 5.01.1099669738 20041105.
touch $file [$file ...]
Touches - i.e. updates last-access/last-modification times to "now" - each $file, creating it if nonexistent. Can be passed nocreate, date, reference, setaccess, setmodify options (see below). Added in version 6.00.1302850000 20110415.

After the $action argument and before any successive arguments, the following options may be given:

msg Turns on the generation of file-related putmsg calls for this action. Overrides the current filemsg value set with vxcp (here).
nomsg Turns off the generation of file-related putmsg calls for this action. Overrides the current filemsg value set with vxcp (here).
glob Enables globbing of source filenames: the characters "*" and "?" become significant as wildcard characters. Note that all filename(s) expanded from a given source argument still correspond to the same destination argument (if applicable for the action).
recurse Enables recursive descent of source directories, e.g. for removing or copying an entire directory tree. For cp, the additional descended path will be appended to the destination path, so that the copied tree has the same hierarchy as the source.
force Force the removal of files or directories, even if the file does not have write permission.
preserve Preserve the file attributes (owner, permissions) of copied files, for cp. (This flag is always on for mv.)
asis Copy non-directories "as-is" for cp, e.g. symlinks are created for symlinks. The default is to copy non-directories as regular files. Not applicable under Windows. (This flag is always on for mv.)
parents For mkdir, create the parents of the named directory if they do not already exist. Useful for creating a multi-level directory path in one call.
nocreate
For touch, do not create the file if it does not exist. Default is to create a new file if nonexistent.
date $date
For touch, next arg is a Texis-parseable date to use for access/modification times, instead of current time.
reference $file
For touch, next arg is a file to copy access/modification times from, instead of using current time.
setaccess
For touch, set access time. Default if neither setaccess nor setmodify is given is to set both times.
setmodify
For touch, set modify time. Default if neither setaccess nor setmodify is given is to set both times.
nnn or [ugoa]=[rwx] For mkdir, an optional file permission mode may be given to use instead of the default 0777.
-- Signifies the end of options. This is useful to avoid misinterpreting following file arguments as options, if they may have the same name.

DIAGNOSTICS
sysutil returns an empty string on success, otherwise a string describing the first error encountered.

EXAMPLE

<sysutil rm recurse force $dir>

The above example deletes the entire directory tree rooted at $dir.

CAVEATS
The sysutil function was added in version 3.01.984600000 20010314.