*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->HP-UX 11i man pages -> settune_txn (2)              


 settune_txn(2)                                               settune_txn(2)

 NAME    [Toc]    [Back]
      settune_txn(2) - sets the values of kernel tunable parameters in a

 SYNOPSIS    [Toc]    [Back]
      #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    [Toc]    [Back]
      version        The version parameter should always be set to

      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    [Toc]    [Back]
                                              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    [Toc]    [Back]
                                              The tunable parameter is
                                              switched to its default state.

 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003

 settune_txn(2)                                               settune_txn(2)

                                              For tunables that can be tuned
                                              by the system, the automatic
                                              tuning is turned on.  The
                                              value specified in the
                                              ktc_value parameter is

      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

      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

      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      The following values are valid for the stf_flags
                     parameter and their corresponding connotations are:

                     STF_NEXTBOOT      Hold all requested changes for next
                                       boot instead of applying them
                                       immediately.  Without this flag,
                                       changes are applied immediately.  (If
                                       this flag is not set, and the changes
                                       cannot be applied immediately,
                                       settune_txn() returns an error.)

                     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    [Toc]    [Back]
      This function is used to modify the values of a set of kernel tunable

 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003

 settune_txn(2)                                               settune_txn(2)

      parameters at the same time.  The caller needs to have super-user
      privileges to make this call.  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.

      +  If any of the tunables in a transaction require a reboot to take
         effect, then the entire transaction requires a reboot to take
         effect i.e. the effects of all the changes within the transaction
         are visible only on a reboot.

      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(2) or an equivalent) after
      that time.  (Some specific parameters may be exceptions to this
      general rule; see the documentation for those parameters in the
      kcweb(1M) online help for details.) The tuneinfo2(2) 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; consult the online help in kcweb(1M) for details on each
      specific parameter.

    Persistence of Changes    [Toc]    [Back]
      Changes to parameter values made with settune_txn() will remain
      effective across reboots in this release of HP-UX.  Tunable parameter
      values are stored in the Kernel Registry database.  Each time the
      system boots, it reads the parameter values from the database and
      restores them.  Changes to parameter values made with settune_txn()
      may not remain effective across reboots in future releases of HP-UX.

 RETURN VALUES    [Toc]    [Back]
           STR_OK            The values of the parameters have been changed
                             and the new values are effective immediately.

           STR_REBOOT        The new values of the parameters have been held
                             pending and will be effective at the next

           STR_ERROR         The function did not complete successfully.
                             None of the changes were applied.  The detailed
                             error messages are in the buffer err_buf.

 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003

 settune_txn(2)                                               settune_txn(2)

                             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    [Toc]    [Back]
      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

           [EPERM]         The caller does not have super-user privileges.

           [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]        The transaction rules were violated and hence
                           none of the changes were made.

           [EINVAL]        The changes within the transaction could not be
                           applied immediately.  One or more of the tunables
                           within the transaction either do not support
                           pending values or the STF_NEXTBOOT flag was not

           [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.

 Hewlett-Packard Company            - 4 -   HP-UX 11i Version 2: August 2003

 settune_txn(2)                                               settune_txn(2)

           [EIO]           The Kernel Registry Service was either
                           unavailable or encountered an error.

           [ENOMEM]        Insufficient memory to accommodate the changes
                           within the transaction.

 WARNING    [Toc]    [Back]
      The caller must have super-user permissions to use this call.

      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.)

 AUTHOR    [Toc]    [Back]
      settune_txn() was developed by Hewlett-Packard Company.

 SEE ALSO    [Toc]    [Back]
      kctune(1M), kcweb(1M), mk_kernel(1M), gettune(2), settune(2),

 Hewlett-Packard Company            - 5 -   HP-UX 11i Version 2: August 2003
[ Back ]
 Similar pages
Name OS Title
kctune HP-UX manage kernel tunable parameters
tuneinfo2 HP-UX retrieve detailed information about kernel tunable parameters
kcalarm HP-UX add, delete, or list kernel tunable alarms, as well as turn kernel tunable monitoring on and off.
systune IRIX display and set tunable parameters
mtune IRIX default system tunable parameters
stune IRIX local settings for system tunable parameters
tune2fs Linux adjust tunable filesystem parameters on second extended filesystems
gettune HP-UX get the value of a kernel tunable parameter
settune HP-UX set the value of a kernel tunable parameter
kcmond HP-UX EMS Kernel Tunable Monitor daemon
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service