test veritas logo



vxfs_ap_define2 - define a new allocation policy


cc -I /opt/VRTS/include -L /opt/VRTS/lib

-l vxfsutil -ldl

#include <sys/types.h>

#include <vxfsutil.h>

int vxfs_ap_define2(int fd, struct fsap_info2 *info, uint32_t flags);




vxfs_ap_define2() defines an allocation policy with the specified name, flags, order, and up to 2048 volumes or 64 subpolicies per policy definition. If the policy name is already defined, the definition is overwritten with the new values. The specified component names must all exist as either volumes in the file system or as previously defined allocation policies. The file descriptor fd specifies any file in the file system where the policy will be defined. The flags argument is currently unused.

To use this function, specify -l vxfsutil while linking.

struct fsap_info2 { char ap_name[FSAP_NAMESZ]; uint32_t ap_flags; uint32_t ap_order; uint64_t ap_chunk; uint32_t ap_ncomp; uint32_t ap_pad; union { char apc_vols[1][FSVOL_NAMEZ]; char apc_subp[1][FSAP_NAMEZ]; } ap_comp; }; #define ap_vols ap_comp.apc_vols #define ap_subp ap_comp.apc_subp

A chunk is in units of bytes.

Possible values for ap_flags are:

  The policy can be assigned by non-privileged users. By default, only privileged users can assign policies.
  The policy definition will contain the names of other allocation policies in its component list. Without this flag, the component list will contain volume names. A policy can refer to either subpolicies or volumes, but not to both.

Possible values for ap_order are:

  Allocations are done from the components in the order in which they are given in the allocation policy.
  Allocations are done from the volume specified in the allocation policy that has the most free blocks. This order cannot be used in FSAP_SUBPOLICIES definitions.
  Allocations are done from a component that is selected in a round-robin fashion from those specified in the allocation policy.
  Allocations are done from a volume that is selected at random from those specified in the allocation policy. When a volume is selected, the allocation is limited to a maximum chunk size. This order cannot be used in FSAP_SUBPOLICIES definitions.


Assigning or defining an allocation policy can fail because of a conflict with volume flags. For example, assigning an allocation policy that allocates metadata to a dataonly volume creates a conflict. The conflict detection attempts to detect all conflicts, but there is no guarantee that all conflicts will be detected.

This API supports file system versions 6.0 and above.


vxfs_ap_define2() returns zero on success, non-zero on failure.


EEXIST The specified policy name is reserved.
EFAULT An address specified by an argument is invalid.
EINVAL One or more arguments to the function are invalid for any of the following reasons:
o The specified number of components exceeds the maximum value
o The specified list of components contains a duplicate entry
o An FSAP_ORDER_BALANCE policy does not have a chunk size
o A policy with an ordering other than FSAP_ORDER_BALANCE has a chunk size
o An FSAP_SUBPOLICIES definition is attempting to use the FS_AP_LEASTFULL or FS_AP_BALANCE order
o An FSAP_SUBPOLICIES definition refers to subpolicies that are themselves FSAP_SUBPOLICIES; only policy trees with a depth of 2 are supported; FSAP_SUBPOLICIES policies must refer to policies that contain volumes
EIO An I/O error occurred during the operation.
ENOENT One or more of the specified components does not exist in the file system.
ENOSPC There was not enough space to store the policy definition.
ENOSYS There is no license installed to allow this operation.
ENOTSUP This operation is not supported by the disk layout version of the specified file system. Use vxupgrade(1m) to enable this operation.
ENXIO An I/O error occurred during the operation.
EPERM The effective user ID of the calling process does not have appropriate priviledges to perform this operation.
EROFS The specified file system is mounted read-only.


The following pseudo-code defines a simple policy:

#include <vxfsutil.h> /* * Define a simple policy. */ int define_simple_policy() { struct fsap_info2 *ap = NULL; uint32_t ncomp = 2; uint32_t comp; int err; int fd; if ((fd = open("My_mountpoint", O_RDONLY)) < 0) { return errno; } if ((ap = vxfs_ap_alloc2(ncomp, 0)) == NULL) { close(fd); return ENOMEM; } strncpy((char *)ap->ap_name, "My_policy_name", FSAP_NAMESZ); ap->ap_flags = 0; ap->ap_order = FSAP_ORDER_ASGIVEN; ap->ap_chunk = 0; ap->ap_ncomp = ncomp; for (comp = 0; comp < ap->ap_ncomp; comp++) { sprintf(ap->ap_vols[comp], "Volume_%d", comp); } if (err = vxfs_ap_define2(fd, ap, 0)) { goto out; } out: close(fd); if (ap) { vxfs_ap_free2(ap); } return err; }


vxfs_ap_alloc2(3), vxfs_ap_assign_ckpt(3), vxfs_ap_assign_file(3), vxfs_ap_assign_fs(3), vxfs_ap_define(3), vxfs_ap_enforce_file(3), vxfs_ap_enforce_file2(3), vxfs_ap_enumerate(3), vxfs_ap_enumerate2(3), vxfs_ap_free2(3), vxfs_ap_query(3), vxfs_ap_query2(3), vxfs_ap_query_ckpt(3), vxfs_ap_query_file(3), vxfs_ap_query_fs(3), vxfs_ap_remove(3), vxfs_vol_add(3), vxfs_vol_deencapsulate(3), vxfs_vol_encapsulate(3), vxfs_vol_enumerate(3), vxfs_vol_remove(3), vxfs_vol_resize(3), vxfs_vol_stat(3)

VxFS 8.0 vxfs_ap_define2(3)