arsctl(2)arsctl(2)NAMEarsctl - 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.
Page 1
arsctl(2)arsctl(2)
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.
Page 2
arsctl(2)arsctl(2)
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
Page 3
arsctl(2)arsctl(2)
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.
ERRORSarsctl 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 ALSOsystune(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
