NAME
tuneinfo2() — retrieve detailed information about kernel tunable parameters
SYNOPSIS
#include <sys/dyntune.h>
int tuneinfo2(int version,
const char *tunable,
tuneinfo2_t *buf,
size_t *bufsize);
TUNEINFO_STRING(tunable, string)
DESCRIPTION
This function provides detailed information about one or all kernel tunable
parameters.
If a particular parameter is of interest, specify it by name in
tunable.
Otherwise, set
tunable
to NULL
and information will be returned on all kernel tunable parameters (if
the supplied buffer is big enough).
version
must always be set to
TUNEINFO_VERSION.
Information about the selected tunable parameters is returned in
tuneinfo2_t
structures and associated character strings.
The
buf
parameter must specify an address in the caller's space containing space for
these structures and strings.
bufsize
must point to a variable containing the size of the buffer (in bytes).
Since the character strings are of variable length,
the caller must first ask how much buffer space is needed, then
allocate the necessary buffer space, and then ask for the tunable
information.
To calculate the size of the buffer to hold all the
tunables, this function should be called with the parameters
buf
and
bufsize
set to NULL and zero, respectively.
The function will return successfully
with a return value of 0 and the variable at
bufsize
will have been changed to contain the amount of space needed to
hold all of the requested data.
See the example below.
Each
tuneinfo2_t
structure describes a single tunable parameter, and contains at least
the following fields, in unspecified order:
- uint64_t ti_name;
Location of the character string containing the name of the tunable.
- uint64_t ti_desc;
Location of the character string containing an English description of the parameter.
- uint64_t ti_module;
Location of the character string containing name of the DLKM module in which the parameter is defined.
This will be a null string for those parameters defined
in the core kernel.
- uint64_t ti_current;
The current value of the parameter.
- uint64_t ti_bootvalue;
The boot-time value of the parameter.
- uint64_t ti_default;
The HP-supplied default value of the parameter.
- uint64_t ti_min;
The minimum value of the parameter.
Valid only if the
TIF_MINVALID
flag is set in the
ti_flags
word, below.
- uint64_t ti_max;
The maximum value of the parameter.
Valid only if the
TIF_MAXVALID
flag is set in the
ti_flags
word, below.
Note:
The minimum and maximum values returned here are relatively static limits.
They will reflect the limitations of the operating system software, and any
limitations placed on this tunable parameter by the current values of other
tunable parameters.
However, they do not reflect any restrictions on the
tunable value based on transient factors like the current usage pattern of
the system.
For example, the maximum value returned for
maxuprc
(the maximum number of processes a non-root user may have) will be no
greater than the current value of
nproc
(the maximum number of processes on the system) minus 5.
However, the minimum value returned for
maxuprc
may very well be less than the number of processes that some user
currently has.
- uint64_t ti_flags;
A bitmask of zero or more of the following flags:
- TIF_CANSET
The value of this parameter can be changed using
settune().
- TIF_DYNAMIC
The value of this parameter can be changed using
settune(),
without requiring a reboot.
- TIF_SIGNED
The values, minima and maxima, for this parameter should be interpreted
as signed quantities.
- TIF_MINVALID
The
ti_minimum
field contains a minimum allowed value for this parameter.
- TIF_MAXVALID
The
ti_maximum
field contains a maximum allowed value for this parameter.
The character string location fields,
ti_name,
ti_desc,
and
ti_module,
can be used to retrieve the character strings.
These fields must
be accessed using the
TUNEINFO_STRING()
macro.
The first parameter of the macro is the pointer to the
tuneinfo2_t
structure and the second parameter is one of the four field names above.
The result of the macro will be a pointer to a null-terminated string.
See the example below.
RETURN VALUE
If
tuneinfo2()
is successful, it returns the number of tunable parameters for which
information was returned and sets the value of
bufsize
to the amount of buffer space used.
When the parameters
buf
and
bufsize
are set to NULL and zero, respectively; it returns 0 and sets the value of
bufsize
to the amount of buffer space that needs to be preallocated.
ERRORS
If this function returns -1 to indicate an error, the global variable
errno
will be set to one of the following values, to indicate the error that
occurred:
- ENOENT
The specified tunable parameter does not exist.
- ENOSPC
The space in
buf,
as specified in
bufsize,
is not sufficient to hold the requested data.
- EFAULT
tunable,
buf,
or
bufsize
contains an address that is inaccessible.
- EIO
The Kernel Registry Service was unavailable or encountered an error.
- EINVAL
The
version
is not supported.
EXAMPLES
#include <stdlib.h>
#include <stdio.h>
#include <sys/dyntune.h>
...
tuneinfo2_t *buf;
size_t bufsize;
int ret;
int count;
int i;
/* To gather information on all tunables: */
/* 1. Find out how much space we need: */
bufsize = 0;
ret = tuneinfo2(TUNEINFO_VERSION, NULL, NULL, &bufsize);
if (ret) {
...
}
/* 2. Allocate that much space: */
buf = (tuneinfo2_t *)malloc(bufsize);
if (buf == NULL) {
...
}
/* 3. Query the data: */
count = tuneinfo2(TUNEINFO_VERSION, NULL, buf, &bufsize);
if (count < 0) {
...
}
/* 4. Print the names of all tunables: */
for (i = 0; i < count; i++) {
char *name = TUNEINFO_STRING(&buf[i], ti_name);
puts(name);
}
WARNINGS
Applications and application modules must not share
tuneinfo2_t
structures unless it is certain that the value of
TUNEINFO_VERSION,
specified in the
<sys/dyntune.h>
header file, is the same for all modules and involved.
The value of
TUNEINFO_VERSION
may be changed without notice.
AUTHOR
tuneinfo2()
was developed by Hewlett-Packard Company.
Printable version
