NAME
chownacl() — change owner and/or group represented in a file's access control list (ACL) (HFS File Systems only)
SYNOPSIS
#include <acllib.h>
void chownacl(
int nentries,
const struct acl_entry *acl,
uid_t olduid,
gid_t oldgid,
uid_t newuid,
gid_t newgid
);
Remarks:
To ensure continued conformance with emerging industry standards,
features described in this manual entry are likely to change
in a future release.
DESCRIPTION
This routine alters an access control list
(ACL)
to reflect the change in a file's owner or group
ID
when an old file is copied to a new file and the
ACL
is also copied.
chownacl()
transfers ownership (that is, it modifies base
ACL
entries) in a manner similar to
chown()
(see
chown(2)).
The algorithm is described below and also in
acl(5).
The
nentries
parameter is the current number of
ACL
entries in the
acl[]
array (zero or more; a negative value is treated as zero).
The
olduid
and
oldgid
values are the user and group
IDs
of the original file's owner, typically the
st_uid
and
st_gid
values from
stat()
(see
stat(2)).
The
newuid
and
newgid
values are the user and group
IDs
of the new file's owner, typically the return values from
geteuid()
and
getegid()
(see
geteuid(2)
and
getegid(2)
in
getuid(2)).
If an
ACL
entry in
acl[]
has a
uid
of
olduid
and a
gid
of
ACL_NSGROUP
(that is, an owner base
ACL
entry),
chownacl()
changes
uid
to
newuid
(with exceptions - see below).
If an entry has a
uid
of
ACL_NSUSER
and a
gid
of
oldgid
(that is, a group base
ACL
entry),
chownacl()
changes
gid
to
newgid.
In either case, only the last matching
ACL
entry is altered; a valid
ACL
can have only one of each type.
As with
chown(2),
if the new user or group already has an
ACL
entry (that is, a
uid
of
newuid
and a
gid
of
ACL_NSGROUP,
or a
uid
of
ACL_NSUSER
and a
gid
of
newgid),
chownacl()
does not change the old user or group base
ACL
entry; both the old and new
ACL
entries are preserved.
As a special case, if
olduid
(oldgid)
is equal to
newuid
(newgid),
chownacl()
does not search
acl[]
for an old user (group) base
ACL
entry to change.
Calling it with both
olduid
equal to
newuid
and
oldgid
equal to
newgid
causes
chownacl()
to do nothing.
Suggested Use
This routine is useful in a program that creates
a new or replacement copy of a file
whose original was (or possibly was) owned
by a different user or group, and that copies the old file's
ACL
to the new file.
Copying another user's and/or group's file
is equivalent to having the original file's owner and/or group
copy and then transfer a file to a new owner and/or group using
chown().
This routine is not needed for merely changing a file's ownership;
chown()
modifies the
ACL
appropriately in that case.
If a program also copies file miscellaneous mode bits
from an old file to a new one, it must use
chmod()
(see
chmod(2)).
However, since
chmod()
deletes optional
ACL
entries, it must be called before
setacl()
(see
setacl(2)).
Furthermore, to avoid leaving a new file temporarily unprotected, the
chmod()
call should set only the file miscellaneous mode bits,
with all access permission mode bits set to zero
(that is, mask the mode with 07000).
The
cpacl()
library call encapsulates this operation,
and handles remote files appropriately too.
EXAMPLES
The following code fragment gets
stat()
information and the
ACL
from
oldfile,
transfers ownership of
newfile
to the caller, and sets the revised
ACL
to
newfile.
#include <sys/types.h>
#include <sys/stat.h>
#include <sys/acl.h>
int nentries;
struct acl_entry acl [NACLENTRIES];
struct stat statbuf;
if (stat ("oldfile", & statbuf) < 0)
error (...);
if ((nentries = getacl ("oldfile", NACLENTRIES, acl)) < 0)
error (...);
chownacl (nentries, acl, statbuf.st_uid, statbuf.st_gid,
geteuid(), getegid());
if (setacl ("newfile", nentries, acl))
error (...);
DEPENDENCIES
chownacl()
is only supported on HFS file system on standard HP-UX operating system.
AUTHOR
chownacl()
was developed by HP.
SEE ALSO
chown(2),
getacl(2),
getegid(2),
geteuid(2),
getuid(2),
setacl(2),
stat(2),
acltostr(3C),
cpacl(3C),
setaclentry(3C),
strtoacl(3C),
acl(5),
thread_safety(5).
Printable version
