arsctl(2) arsctl(2) NAME arsctl - modify the behavior of array sessions SYNOPSIS #include <sys/arsess.h> int arsctl(int func, void *bufptr, int buflen); DESCRIPTION The arsctl function queries and/or modifies some aspect of the behavior of array sessions on the currently running system. Most of the array session control operations take some sort of argument. A pointer to the argument is passed as bufptr, and the length of the argument is specified with buflen. The particular operation to be performed is identified by the function code func, which is defined in <sys/arsess.h>. Available array session control operations include: ARSCTL_GETDFLTSPILEN Returns the number of bytes of storage that is allocated for Service Provider Information in new array sessions. The value is stored as an int at the location specified by bufptr. The default value at system initialization time is determined by the kernel variable spilen, which can be modified using systune(1M). ARSCTL_SETDFLTSPILEN Sets the number of bytes of storage that is allocated for Service Provider Information in new array sessions to the value contained in the int pointed to by bufptr. An EINVAL error will occur if the value is negative or is greater than the system maximum value (typically 1024), and the current setting will remain unchanged. Existing array sessions are not affected by this change, nor is the setting of the kernel variable spilen. The caller must be privileged to use this function. ARSCTL_GETSAF Returns the session accounting record format. The value is stored as an int at the location specified by bufptr. The default value at system initialization time is determined by the kernel variable sessaf, which can be modified using systune(1M). ARSCTL_SETSAF Sets the session accounting record format to the value contained in the int pointed to by bufptr. Any subsequent session accounting records that are generated by the kernel will be in the specified format. An EINVAL error will occur if an invalid format number is specified, and the current setting will remain unchanged. The caller must be privileged to use this function. ARSCTL_GETMACHID Returns the current machine ID. The machine ID is an arbitrary value used by the kernel in the generation of array session handles. It is intended to uniquely identify a machine within a particular array/cluster configuration. The value is stored as an int at the location specified by bufptr. The default value at system initialization time is determined by the kernel variable asmachid, which can be modified using systune(1M). ARSCTL_SETMACHID Sets the machine ID to the value contained in the int pointed to by bufptr. Any subsequent array session handles that are generated by the kernel may incorporate this value in some way. A machine ID is normally a positive integer in the range 1-32767. In an array/cluster configuration, no two machines should have the same machine ID. If a machine ID of 0 is specified, any subsequent array session handles generated by the kernel will be "local"; this means that the machine and array ID's will not be incorporated into the array session handle, and its uniqueness in an array/cluster configuration is not guaranteed. If a machine ID of -1 is specified, then the default machine ID specified by the kernel variable asmachid will be used instead. If any other value is specified for the machine ID, an EINVAL error will occur and the machine ID will remain unchanged. The caller must be privileged to use this function. ARSCTL_GETARRAYID Returns the current array ID. The array ID is an arbitrary value used by the kernel in the generation of array session handles. If a particular machine were a member of more than one array or cluster, the array ID would typically identify which array the array session was associated with, if any. The value is stored as an int at the location specified by bufptr. The default value at system initialization time is determined by the kernel variable asarrayid, which can be modified using systune(1M). ARSCTL_SETARRAYID Sets the array ID to the value contained in the int pointed to by bufptr. Any subsequent array session handles that are generated by the kernel may incorporate this value in some way. An array ID is an integer in the range 0-65535. If a value of -1 is specified, then the default array ID specified by the kernel variable asarrayid will be used instead. If any other value outside of this range is specified, an EINVAL error will occur and the array ID will remain unchanged. The values 0-65534 (0-0xfffe) are normally reserved for array services (see array_services(5)), so if array services are in use on a system, the only appropriate array ID for the kernel is 65535 (0xffff). The caller must be privileged to use this function. ARSCTL_GETASHCTR Returns the current value of the counter used to form the local portion of the next array session handle. The value is stored as an ash_t at the location specified by bufptr. Notice that the counter could potentially be incremented at any time by any other CPU in the system, so the returned value must be considered a mere "snapshot" of the value at the instant that the function was processed. ARSCTL_SETASHCTR Sets the counter that is used by the kernel to form the local portion of array session handles to the value contained in the ash_t pointed to by bufptr. Any subsequent array session handles that are generated by the kernel may incorporate this value in some way. The valid range of values is determined by the kernel variables min_local_paggid and max_local_paggid. If a value outside of this range is specified, an EINVAL error will occur and the counter will remain unchanged. The caller must be privileged to use this function. ARSCTL_GETASHINCR Returns the current increment value for the counter used to form the local portion of the next array session handle. The value is stored as an ash_t at the location specified by bufptr. ARSCTL_SETASHINCR Sets the increment for the counter that is used by the kernel to form the local portion of array session handles to the value contained in the ash_t pointed to by bufptr. The specified value will be added to this counter after the next and subsequent array session handles are generated by the kernel. The value may be positive or negative but it may not be zero, and its absolute value must be less than the difference between the kernel variables max_local_paggid and min_local_paggid. If an illegal value is specified, an EINVAL error will occur and the increment value will remain unchanged. The caller must be privileged to use this function. ARSCTL_GETDFLTSPI Stores the default Service Provider Information into the buffer pointed to by bufptr. This information is considered to be associated with any array session that has neither specifically set its service provider information, nor is descended from an array session that has done so. If the argument buffer is too small to accommodate all of the service provider information, the data will be truncated. If the argument buffer is larger than the service provider information the data will be padded on the right with zeroes. ARSCTL_SETDFLTSPI Sets the default Service Provider Information to the contents of the buffer pointed to by bufptr. This information will immediately become associated with all array sessions that have neither specifically set their service provider information, nor are descended from an array session that has done so. The size of the service provider information should ordinarily be the same as whatever is returned by the ARSCTL_GETSPILEN function. If the argument buffer is too small, the service provider information will be padded on the right with zeroes. If the argument buffer is too large, an EINVAL error will occur and the default service provider information will remain unchanged. The caller must be privileged to use this function. ARSCTL_ALLOCASH Allocates an unused array session handle and stores it into the buffer pointed to by bufptr. buflen must be equal to sizeof(ash_t) or else an EINVAL error will occur. The ASH that is allocated by this function is guaranteed not to be in use on the local system at the time it was allocated. Furthermore, under normal circumstances the allocated ASH will not be reallocated by the local system until the "ASH counter" (see ARSCTL_GETASHCTR and ARSCTL_SETASHCTR) has incremented through its entire range of values and once again returns to the value that was used for the allocated ASH. Exceptions to this would include rebooting the system (which will ordinarily return the ASH counter to its minimum value) and manual changes to the ASH counter using the ARSCTL_SETASHCTR function. ERRORS arsctl may fail if one or more of these conditions are true: EFAULT bufptr is not a valid address. EINVAL func is not a valid function code. EINVAL buflen is the wrong size for the given function code. EINVAL The argument pointed to by bufptr is not valid. EPERM The current process does not have the appropriate privileges to perform the operation specified by func. SEE ALSO systune(1M), arsop(2), extacct(4), array_sessions(5). DIAGNOSTICS Upon successful completion, arsctl returns a value of 0. Otherwise, a value of -1 is returned and errno is set to indicate the error. Page 4