233 lines
9.7 KiB
Groff
233 lines
9.7 KiB
Groff
.TH arsctl 2
|
|
.SH NAME
|
|
arsctl \- modify the behavior of array sessions
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\f3#include <sys/arsess.h>\f1
|
|
.sp .8v
|
|
\f3int arsctl(int func, void *bufptr, int buflen);\f1
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The \f2arsctl\fP function queries and/or modifies some aspect of
|
|
the behavior of array sessions on the currently running system.
|
|
.PP
|
|
Most of the array session control operations take some sort of argument.
|
|
A pointer to the argument is passed as \f2bufptr\f1, and the length
|
|
of the argument is specified with \f2buflen\f1.
|
|
.PP
|
|
The particular operation to be performed is identified by the function
|
|
code \f2func\f1, which is defined in \f2<sys/arsess.h>\f1.
|
|
Available array session control operations include:
|
|
.PP
|
|
.TP 0.75i
|
|
\f3ARSCTL_GETDFLTSPILEN\f1
|
|
Returns the number of bytes of storage that is allocated for
|
|
Service Provider Information in new array sessions.
|
|
The value is stored as an \f2int\f1 at the location specified by
|
|
\f2bufptr\f1.
|
|
The default value at system initialization time
|
|
is determined by the kernel variable
|
|
\f2spilen\f1, which can be modified using \f2systune\f1(1M).
|
|
.TP
|
|
\f3ARSCTL_SETDFLTSPILEN\f1
|
|
Sets the number of bytes of storage that is allocated for
|
|
Service Provider Information in new array sessions to the
|
|
value contained in the \f2int\f1 pointed to by \f2bufptr\f1.
|
|
An \f3EINVAL\f1 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 \f2spilen\f1.
|
|
The caller must be privileged to use this function.
|
|
.TP
|
|
\f3ARSCTL_GETSAF\f1
|
|
Returns the session accounting record format.
|
|
The value is stored as an \f2int\f1 at the location specified by
|
|
\f2bufptr\f1.
|
|
The default value at system initialization time
|
|
is determined by the kernel variable
|
|
\f2sessaf\f1, which can be modified using \f2systune\f1(1M).
|
|
.TP
|
|
\f3ARSCTL_SETSAF\f1
|
|
Sets the session accounting record format to the
|
|
value contained in the \f2int\f1 pointed to by \f2bufptr\f1.
|
|
Any subsequent session accounting records that are generated
|
|
by the kernel will be in the specified format.
|
|
An \f3EINVAL\f1 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.
|
|
.TP
|
|
\f3ARSCTL_GETMACHID\f1
|
|
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 \f2int\f1 at the location specified by
|
|
\f2bufptr\f1.
|
|
The default value at system initialization time is determined by the
|
|
kernel variable \f2asmachid\f1, which can be modified using
|
|
\f2systune\f1(1M).
|
|
.TP
|
|
\f3ARSCTL_SETMACHID\f1
|
|
Sets the machine ID to the value contained in the \f2int\f1 pointed
|
|
to by \f2bufptr\f1.
|
|
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 \f2asmachid\f1 will be used instead.
|
|
If any other value is specified for the machine ID, an \f3EINVAL\f1
|
|
error will occur and the machine ID will remain unchanged.
|
|
The caller must be privileged to use this function.
|
|
.TP
|
|
\f3ARSCTL_GETARRAYID\f1
|
|
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 \f2int\f1 at the location specified by
|
|
\f2bufptr\f1.
|
|
The default value at system initialization time is determined by the
|
|
kernel variable \f2asarrayid\f1, which can be modified using
|
|
\f2systune\f1(1M).
|
|
.TP
|
|
\f3ARSCTL_SETARRAYID\f1
|
|
Sets the array ID to the value contained in the \f2int\f1 pointed
|
|
to by \f2bufptr\f1.
|
|
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 \f2asarrayid\f1 will be used instead.
|
|
If any other value outside of this range is specified,
|
|
an \f3EINVAL\f1 error will occur and the array ID will remain unchanged.
|
|
The values 0\-65534 (0\-0xfffe) are normally
|
|
reserved for array services (see \f2array_services\f1(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.
|
|
.TP
|
|
\f3ARSCTL_GETASHCTR\f1
|
|
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 \f2ash_t\f1 at the location specified by
|
|
\f2bufptr\f1.
|
|
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.
|
|
.TP
|
|
\f3ARSCTL_SETASHCTR\f1
|
|
Sets the counter that is used by the kernel to form the local
|
|
portion of array session handles to the value contained in the
|
|
\f2ash_t\f1 pointed to by \f2bufptr\f1.
|
|
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
|
|
\f2min_local_paggid\f1 and \f2max_local_paggid\f1.
|
|
If a value outside of this range is specified, an \f3EINVAL\f1 error
|
|
will occur and the counter will remain unchanged.
|
|
The caller must be privileged to use this function.
|
|
.TP
|
|
\f3ARSCTL_GETASHINCR\f1
|
|
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 \f2ash_t\f1 at the location specified by
|
|
\f2bufptr\f1.
|
|
.TP
|
|
\f3ARSCTL_SETASHINCR\f1
|
|
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 \f2ash_t\f1 pointed to by \f2bufptr\f1.
|
|
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
|
|
\f2max_local_paggid\f1 and \f2min_local_paggid\f1.
|
|
If an illegal value is specified, an \f3EINVAL\f1 error
|
|
will occur and the increment value will remain unchanged.
|
|
The caller must be privileged to use this function.
|
|
.TP
|
|
\f3ARSCTL_GETDFLTSPI\f1
|
|
Stores the default Service Provider Information
|
|
into the buffer pointed to by \f2bufptr\f1.
|
|
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 accomodate 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.
|
|
.TP
|
|
\f3ARSCTL_SETDFLTSPI\f1
|
|
Sets the default Service Provider Information
|
|
to the contents of the buffer pointed to by \f2bufptr\f1.
|
|
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 \f3ARSCTL_GETSPILEN\f1
|
|
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 \f3EINVAL\f1 error will occur
|
|
and the default service provider information will remain unchanged.
|
|
The caller must be privileged to use this function.
|
|
.TP
|
|
\f3ARSCTL_ALLOCASH\f1
|
|
Allocates an unused array session handle and stores it into the buffer
|
|
pointed to by \f2bufptr\f1.
|
|
\f2buflen\f1 must be equal to \f3sizeof(ash_t)\f1 or else an
|
|
\f3EINVAL\f1 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 \f3ARSCTL_GETASHCTR\f1 and \f3ARSCTL_SETASHCTR\f1)
|
|
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 \f3ARSCTL_SETASHCTR\f1
|
|
function.
|
|
.SH ERRORS
|
|
\f2arsctl\f1 may fail if one or more of these conditions are true:
|
|
.TP 1i
|
|
\f3EFAULT\f1
|
|
\f2bufptr\f1 is not a valid address.
|
|
.TP
|
|
\f3EINVAL\f1
|
|
\f2func\f1 is not a valid function code.
|
|
.TP
|
|
\f3EINVAL\f1
|
|
\f2buflen\f1 is the wrong size for the given function code.
|
|
.TP
|
|
\f3EINVAL\f1
|
|
The argument pointed to by \f2bufptr\f1 is not valid.
|
|
.TP
|
|
\f3EPERM\f1
|
|
The current process does not have the appropriate privileges to
|
|
perform the operation specified by \f2func\f1.
|
|
.SH SEE ALSO
|
|
systune(1M),
|
|
arsop(2),
|
|
extacct(4),
|
|
array_sessions(5).
|
|
.SH "DIAGNOSTICS"
|
|
Upon successful completion, \f2arsctl\f1 returns a value of 0.
|
|
Otherwise, a value of -1 is returned and \f2errno\f1 is set to
|
|
indicate the error.
|
|
|