settune_txn(2)settune_txn(2)NAMEsettune_txn() - sets the values of kernel tunable parameters in a
transaction
SYNOPSISPARAMETERS
version The version parameter should always be set to
transaction The details of the changes are specified in an array of
structures. Each structure provides context to the
changes to be made to a single tunable, and contains at
least the following fields, in unspecified order:
The name of the tunable parameter to be changed. NULL-
terminated ASCII string.
The value to which the tunable parameter must be set.
These are flags to describe this change within the
transaction. Valid flags
and their corresponding connotations are:
The current value of the tunable should be
changed to the value
specified in the ktc_value parameter.
This is allowed for all tunables. Setting
the current value of a tunable that the
system is tuning automatically turns off
the automatic tuning.
The tunable parameter is switched to its default
state. For tunables that can be tuned by
the system, the automatic tuning is turned
on. The value specified in the ktc_value
parameter is ignored.
size The size of a structure, as understood by the caller.
num_elements The number of tunables that are being modified in this
call.
err_buf Errors or warning messages that give details about the
tuning are passed back in the err_buf, which must spec‐
ify an address in the caller's space. The messages will
be in English and returned as NULL-terminated ASCII
strings. A NULL string terminates the error messages.
err_bufsize The parameter err_bufsize is a pointer to a variable
containing the size of the err_buf buffer (in bytes).
Upon completion of the system call, err_bufsize will
contain the size necessary for all the error and/or
warning messages for the transaction. If this value is
greater than the original err_bufsize value, the mes‐
sages have been truncated to fit into err_buf. A buffer
of size 300 bytes per tunable is usually sufficient for
the error buffer.
stf_flags A bitmask of flags governing the tunable change opera‐
tion. The following flag value is recognized:
Check the requested changes, but do not actually make
any change. With this flag set, will return the same
exit code and error and warning messages as if it were
actually making the change, but no change will be made.
DESCRIPTION
This function is used to modify the values of a set of kernel tunable
parameters at the same time. Changes are made to the tunables using a
transactional change model using a three-phase commit where the follow‐
ing rules apply:
· None of the changes within a transaction succeed or all of the
changes within a transaction succeed. There are no in-betweens.
· No duplicates are allowed within a transaction, where duplicates are
defined as more than one change to a tunable.
· There are no restrictions on the order in which the tunables need to
be specified within a transaction.
Some parameters represent limits on resources that can be consumed by
individual processes. In general, changes to these parameters do not
affect processes that are running at the time the change is made; they
affect only new programs started (with or an equivalent) after that
time. Some specific parameters may be exceptions to this general rule;
see the man pages for those parameters for details.
The call can give information about whether or not changes to a parame‐
ter are allowed, or will require a reboot, or can be tuned automati‐
cally. Some individual parameters may have specific notes regarding
their behavior when changed; see the man pages for those parameters
for details.
Security Restrictions
The actions associated with this system call require the privilege.
Processes owned by the superuser have this privilege. Processes owned
by other users may have this privilege, depending on system configura‐
tion. See privileges(5) for more information about privileged access
on systems that support fine-grained privileges.
RETURN VALUES
The values of the parameters have been changed and the new val‐
ues are effective immediately.
The function did not complete successfully. None of the
changes were applied. The detailed error messages are in
the buffer err_buf.
If the buffer size returned in err_bufsize is greater
than the size of err_buf, there were more error messages
than have been returned. To get the remaining errors,
increase the size of the buffer and try again.
The function completed successfully, but there were
warning messages generated. These warning messages are
in the buffer, err_buf.
If the buffer size returned in err_bufsize is greater
than the size of err_buf, some warning messages were gen‐
erated which did not fit into the buffer.
ERRORS
When the function returns the global variable errno will be set to one
of the following values:
One or more of the specified tunables does not exist.
The caller does not have the
privilege.
The version parameter is not valid.
One or more of the specified values within the transaction
are not within the acceptable range of values for the
corresponding parameters.
At least one transaction rule was violated and hence none of the
changes were made.
The changes within the transaction could not be applied
immediately.
The combination of flags specified is invalid.
The number of elements specified is zero.
The size of a
structure as specified by struct_size is invalid.
The number of elements specified is greater than the number of
tunables available.
err_buf
or err_bufsize specifies an address that is inaccessible.
The Kernel Registry Service was either unavailable or
encountered an error.
Insufficient memory to accommodate the changes within the
transaction.
WARNING
It is possible to seriously degrade system performance, or even render
a system unbootable, with incorrect tunable settings. Use care when
setting tunable values. Always have a known working kernel configura‐
tion saved as a backup; if the system fails to boot after a tunable
change, boot from that backup kernel configuration. Keep good records
of all tunable changes so that they can be reversed if they degrade
system performance. Tunable changes made with are automatically logged
to
If the tunables being changed through are used in expressions that set
the values of other tunables, those expressions will not be re-evalu‐
ated and those tunable values will not be updated. This behavior may
change in future releases of HP-UX. If expression evaluation is
desired, use to set tunable values.
Tunable changes made using may not remain effective across reboots.
This behavior may change in future releases of HP-UX. If persistence
of changes across reboots is desired, use to set tunable values.
AUTHOR
was developed by Hewlett-Packard Company.
SEE ALSOkctune(1M), mk_kernel(1M), gettune(2), settune(2), tuneinfo2(2), privi‐
leges(5), and the individual tunable parameter man pages in section 5.
settune_txn(2)