CPACL(3C)

NAME

cpacl, fcpacl − copy the access control list (ACL) and mode bits from one file to another

SYNOPSIS

int cpacl (fromfile, tofile, frommode, fromuid, fromgid, touid, togid)
char ∗fromfile, ∗tofile;
int frommode;
int fromuid, touid;
int fromgid, togid;

int fcpacl (fromfd, tofd, frommode, fromuid, fromgid, touid, togid)
int fromfd, tofd;
int frommode;
int fromuid, touid;
int fromgid, togid;

Remarks:

To ensure continued conformance with emerging industry standards, features described in this manual entry are likely to change in a future release.

DESCRIPTION

Both cpacl and fcpacl copy the access control list and mode bits (that is, file access permission bits and miscellaneous mode bits; see chmod(2)) from one file to another, and transfer ownership much like chown(2). Cpacl and fcpacl take the following parameters:

• Path names (fromfile and tofile) or open file descriptors (fromfd and tofd).

• A mode value (frommode, typically the st_mode value returned by stat(2)) containing file miscellaneous mode bits, which are always copied, and file access permission bits, which are copied instead of the access control list if either file is remote.

• User ID and group ID of the file (fromuid, touid and fromgid, togid) for transferring ownership. (Typically fromuid and fromgid are the st_uid and st_gid values returned by stat, and touid and togid are the return values from geteuid(2) and getegid(2).)

When both files are local, the cpacl routines copy the access control list and call chownacl(3C) to transfer ownership from the fromfile to the tofile, if necessary.

Cpacl (fcpacl) handles remote copying (via RFA or NFS) after recognizing failures of getacl(2) (fgetacl) or setacl(2) (fsetacl). When copying the mode from fromfile (fromfd) to tofile (tofd), cpacl copies the entire frommode (that is, the file miscellaneous mode bits and the file access permission bits) to tofile (tofd) using chmod(2) (fchmod(2)). Some of the miscellaneous mode bits may be turned off; see chmod(2).

Cpacl (fcpacl) can copy an access control list from fromfile (fromfd) to tofile (tofd) without transferring ownership, but ensuring error checking and handling of remote files. This is done by passing fromuid equal to touid and fromgid equal to togid (that is, four zeros). For remote files, fromuid, touid, fromgid, and togid are ignored.

RETURN VALUE

If successful, cpacl and fcpacl return zero. If an error occurs, they set errno to indicate the cause of failure and return a negative value, as follows:

−1 Unable to perform getacl (fgetacl) on a local fromfile (fromfd).

−2 Unable to perform chmod (fchmod) on tofile (tofd) to set its file miscellaneous mode bits. Cpacl (fcpacl) attempts this regardless of whether a file is local or remote, as long as fromfile (fromfd) is local.

−3 Unable to perform setacl (fsetacl) on a local tofile (tofd). As a consequence, the file’s optional ACL entries are deleted, its file access permission bits are zeroed, and its miscellaneous mode bits might be altered.

−4 Unable to perform chmod (fchmod) on tofile (tofd) to set its mode. As a consequence, if fromfile (fromfd) is local, tofile’s (tofd’s) optional ACL entries are deleted, its access permission bits are zeroed, and its file miscellaneous mode bits might be altered, regardless of whether the file is local or remote.

EXAMPLES

The following code fragment gets stat information on “oldfile” and copies its file miscellaneous bits and access control list to “newfile” owned by the caller. If either file is remote, only the st_mode on “oldfile” is copied.

#include <sys/types.h>
#include <sys/stat.h>

struct stat statbuf;

if (stat ("oldfile", & statbuf) < 0)
error (...);

if (cpacl ("oldfile", "newfile", statbuf.st_mode,
statbuf.st_uid, statbuf.st_gid, geteuid(), getegid()) < 0)
{
error (...);
}

DEPENDENCIES

RFA and NFS
Fcpacl fails if tofile is RFA-remote.

AUTHOR

Cpacl and fcpacl were developed by HP.

Museum

Related Articles