settune_txn(2)

NAME

settune_txn() — sets the values of kernel tunable parameters in a transaction

SYNOPSIS

#include <sys/dyntune.h> 

int settune_txn (uint64_t              version, 
                 struct ktune_context *transaction, 
                 size_t                struct_size, 
                 uint64_t              num_elements, 
                 char                 *err_buf, 
                 uint64_t             *err_bufsize, 
                 uint64_t              stf_flags); 

PARAMETERS

version

The version parameter should always be set to SETTUNE_VERSION.

transaction

The details of the changes are specified in an array of ktune_context structures. Each ktune_context structure provides context to the changes to be made to a single tunable, and contains at least the following fields, in unspecified order:

char *kct_name

The name of the tunable parameter to be changed. NULL-terminated ASCII string.

uint64_t ktc_value

The value to which the tunable parameter must be set.

uint64_t ktc_flags

These are flags to describe this change within the transaction. Valid flags and their corresponding connotations are:

TCF_CURRVALUE: 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.
TCF_DEFAULT: 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 ktune_context 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 specify 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 messages 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 operation. The following flag value is recognized:

STF_VALIDATE: Check the requested changes, but do not actually make any change. With this flag set, settune_txn() 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 following 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 exec() 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 tuneinfo2() call can give information about whether or not changes to a parameter are allowed, or will require a reboot, or can be tuned automatically. 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 SYSATTR privilege. Processes owned by the superuser have this privilege. Processes owned by other users may have this privilege, depending on system configuration. See privileges(5) for more information about privileged access on systems that support fine-grained privileges.

RETURN VALUES

STR_OK

The values of the parameters have been changed and the new values are effective immediately.

STR_ERROR

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.

STR_WARN

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 generated which did not fit into the buffer.

ERRORS

When the function returns STR_ERROR the global variable errno will be set to one of the following values:

ENOENT: One or more of the specified tunables does not exist.
EPERM: The caller does not have the SYSATTR privilege.
EBADVER: The version parameter is not valid.
EINVAL: One or more of the specified values within the transaction are not within the acceptable range of values for the corresponding parameters.
EINVAL: At least one transaction rule was violated and hence none of the changes were made.
EINVAL: The changes within the transaction could not be applied immediately.
EINVAL: The combination of flags specified is invalid.
EINVAL: The number of elements specified is zero.
EINVAL: The size of a ktune_context structure as specified by struct_size is invalid.
EINVAL: The number of elements specified is greater than the number of tunables available.
EFAULT: err_buf or err_bufsize specifies an address that is inaccessible.
EIO: The Kernel Registry Service was either unavailable or encountered an error.
ENOMEM: 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 configuration 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 settune_txn() are automatically logged to syslog.

If the tunables being changed through settune_txn() are used in expressions that set the values of other tunables, those expressions will not be re-evaluated and those tunable values will not be updated. This behavior may change in future releases of HP-UX. If expression evaluation is desired, use kctune() to set tunable values.

Tunable changes made using settune_txn() 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 kctune() to set tunable values.

AUTHOR

settune_txn() was developed by Hewlett-Packard Company.