HP-UX Reference (11i v2 04/09) - 3 Library Functions A-M (vol 6)

c
chownacl(3C) chownacl(3C)
NAME
chownacl( ) - change owner and/or group represented in a file’s access control list (ACL) (HFS File Sys-
tems 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 nega-
tive 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,orauid 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. Copy-
ing 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>
HP-UX 11i Version 2: September 2004 − 1 − Hewlett-Packard Company Section 3−−101