before I attempt to change the POD, would this wording be appropriate?
=item chown
our multi chown (Int $uid, Int $gid, Str|IO [EMAIL PROTECTED])
our multi chown (Str $user, Str $group, Str|IO [EMAIL PROTECTED])
Changes the owner (and/or group) of a list of files. The new
ownership can be specified either as integers or as strings.
If an argument is either a negative integer or undefined then
the ownership (or group membership) of the files will be
unchanged.
A True value will be returned if the operation succeeds,
otherwise the function will C<fail>.
The list of files may contain strings and/or filehandles.
Strings are interpretted as filenames. On systems that don't
support C<fchown> the use of file handles will result in
failure
When $user or $group are passed as strings, the implementation
will convert this name to the underlying uid/gid using a
function such as getpwnam.
On most systems, you are not allowed to change the ownership of
the file unless you?re the superuser, although you should be
able to change the group to any of your secondary groups. On
insecure systems, these restrictions may be relaxed, but this
is not a portable assumption. On POSIX systems, you can detect
this condition this way:
use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
$can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
=item chmod
our multi chmod( Int $mode, Str|IO [EMAIL PROTECTED] );
our multi chmod( PermissionModifier :$user?, PermissionModifier :
$group?, PermissionModifier :$other?, Str|IO [EMAIL PROTECTED] );
class PermissionModifier {
submethod BUILD ( Bool :$r, Bool :$w, Bool :$x );
...
};
Changes the permissions of a list of files. Returns a true value if
the operation is sucessful on all the files, otherwise C<fail>.
The files to modify can be given either as Strings, or FileHandles.
The permissions can be provided as either a single integer,
corresponding
to the underlying Unix permissions mode value, or as named options
using PermissionModifier objects.
A PermissionModifier object is constructed using options similar
to filetest operators. :r, :w and :x (and their inverted forms).
If a given option is not included in the object that the corresponding
permission mode of the file(s) will not be changed.
Examples:
chmod 0o755, @executables;
$mode = '0644'; chmod $mode, 'foo'; # !!! sets mode to --
w----r-T
$mode = '0o644'; chmod $mode, 'foo'; # this is better
$mode = 0o644; chmod $mode, 'foo'; # this is best
@executables ==> chmod :user( :x ), # users can execute
these
:group( :x ), # as can group members
:other( :!x :!r :!w ); # but non-group members
cannot
