Libtune API documentation

Version 0.4
2007/11/09

Nadia Derbey
Nadia.Derbey@bull.net



1. Overview
2. Supported kernels and distros
3. The libtune API interfaces
    3.1. Getting information (tun_get)
        3.1.1. Description
        3.1.2. Parameters
        3.1.3. Returned values
    3.2. Setting information (tun_set)
        3.2.1. Description
        3.2.2. Parameters
        3.2.3. Returned values
    3.3. Locating information (tun_locate)
        3.3.1. Description
        3.3.2. Parameters
        3.3.3. Returned values
    3.4. Getting the key word for a location (tun_get_kwd)
        3.4.1. Description
        3.4.2. Parameters
        3.4.3. Returned values
    3.5. Getting all the valid keywords (tun_lst_all)
         3.5.1. Description
         3.5.2. Parameters
         3.5.3. Returned values
    3.6. Getting help information (tun_help)
         3.6.1. Description
         3.6.2 Parameters
         3.6.3. Returned values
4. Supported tunables
    4.1. Red Hat specific tunables
    4.2. SuSE specific tunables
5. Manual howto
    5.1. How to add support for a new kernel release
    5.2. How to add support for a new distribution family
    5.3. How to add support for a new tunable
         5.3.1. Kernel specific tunable
         5.3.2. Distro-dependent tunable
6. "Automatic" howto
    6.1. Adding support for a new kernel release
        6.1.1. In the source tree
        6.1.2. In the installed files
    6.2. Adding support for a new distro family
        6.2.1. In the source tree
        6.2.2. In the installed files
    6.3. Adding support for a new tunable
    6.4. Adding support for an existing tunable
    6.5. Removing a tunable support
    6.6. Getting the list of supported tunables
    6.7. Note
End of document




1. Overview

Accessing kernel tunables, system information and resource consumptions is needed during the whole life cycle of an application, starting from its installation. This access is usually implemented through installation and supervision scripts. Unfortunately, the following issues have been identified:
  1. These scripts are rarely portable. since they require to get, set and change values that are represented by objects that may change from distribution to distribution, or even from one release to the other inside the same distribution.
  2. There are quite multiple ways of accessing the kernel configuration and tunables: procfs, sysfs, existing syscalls or library routines, etc...
This raises the need for a standard, well defined API to manipulate the kernel configuration and tunables for software products to relay on.

The goal of the libtune API is to unify the various ways Linux developers have to access kernel tunables, system information, resource consumptions. The libtune API is built on top of the existing mechanisms, instead of replacing them, in order to maintain backward compatibility.

In the following chapters, we first present the supported kernel and distros supported today. Then, the API interfaces are  presented. Follows a chapter about the tunables that are supported today.
Finally, a howto is given:

2. Supported kernels and distros

kernels: 2.6.5, 2.6.9, 2.6.11, 2.6.15 to 2.6.23.
distros: fedora and Suse

3. The libtune API interfaces

3.1. Getting information (tun_get)

#include <libtune.h>
size_t tun_get(int
keyword, void *name_identifier, void *data_identifier, char **out_buff, size_t *out_sz)

3.1.1. Description

This routine is used to get a tunable value: given a keyword that uniquely identifies a tunable, it returns its value (as read from the underlying /proc or /sys file). See next chapters to have a list of the supported tunables.
The value is returned as a buffer of characters (out_buff), whose size is out_sz.
For the tunables that correspond to a pseudo-file with a variable part, that variable part can be provided through the name_identifier parameter (ex: a <cpu_id> for the TUN_CPULIMITS tunable that corresponds to the /proc/acpi/processor/CPU<cpu_id>/limit pseudo-file).
For the tunables that correspond to a pseudo-file with a content split into blocks of data related to an identifier, that identifier can be provided through the data_identifier parameter (ex: a <cpu_id> for the TUN_SIBLINGS tunable that corresponds to the "Siblings" field for <cpu_id> in the pseudo-file /proc/cpuinfo).

3.1.2. Parameters

This routine takes the following parameters:

3.1.3. Returned values

On  success,  tun_get() returns the number of characters read, including the terminating null character, but not including the EOF character. This value can be used to handle embedded null characters in the data read.
tun_get() returns -1 on failure, and errno is set:

EINVAL
keyword is invalid

name_identifier is a NULL pointer, while the tunable asked for needs a name identifier

data_identifier is a NULL pointer, while the tunable asked for needs a data identifier

name_identifier is an empty string, while the tunable asked for needs a string name identifier

data_identifier is an empty string, while the tunable asked for needs a string data identifier

outbuf is a NULL pointer

out_sz is a NULL pointer
ENODATA
The value looked for could not be found
EPERM
the calling application does not have the neccessary rights to get the needed tunable value
ENOENT
the underlying file does not exist.
ENOMEM
if the API failed to allocate memory

3.2. Setting information (tun_set)

#include <libtune.h>
size_t tun_set(int
keyword, void *name_identifier, void *data_identifier, char *in_buff, size_t in_sz, char **out_buff, size_t *out_sz)

3.2.1. Description

This routine is used to set a tunable value: given a keyword that uniquely identifies a tunable, it sets its value to the string contained in in_buff, whose size is in_sz (by writing that value into the underlying /proc or /sys file). See next chapters to have a list of the supported tunables.
The previous tunable value is returned as a buffer of characters (out_buff), whose size is out_sz. This is done only if the corresponding pseudo-file is readable.
For the tunables that depend on an identifier (pid, CPU id, etc), that identifier can be provided through the identifier parameter.
For the tunables that correspond to a pseudo-file with a variable part, that variable part can be provided through the name_identifier parameter, as for the tun_get() interface.
For the tunables that correspond to a pseudo-file with a content split into blocks of data related to an identifier, that identifier can be provided through the data_identifier parameter, as for the tun_get() interface. Note: the libtune currently does not support to set values for this kind of tunables, so the data_identifier should be set to NULL. This is because the pseudo-file that are built on this model and that are supportted today by the libtune are statistic files.

3.2.2. Parameters

This routine takes the following parameters:

3.2.3. Returned values

On  success,  tun_set() returns the number of output characters, including the terminating null character, but not including the EOF character. This value can be used to handle embedded null characters in the data read.
tun_set() returns -1 on failure, and errno is set:
EINVAL
keyword is invalid

name_identifier is a NULL pointer, while the tunable asked for needs a name identifier

data_identifier is a NULL pointer, while the tunable asked for needs a data identifier

name_identifier is an empty string, while the tunable asked for needs a string name identifier

data_identifier is an empty string, while the tunable asked for needs a string data identifier

in_buff is a NULL pointer

in_sz has a 0 value

outbuf is a NULL pointer

out_sz is a NULL pointer

keyword is one of TUN_H_OP_MAX, TUN_S_OP_MAX, TUN_H_CHILD_MAX, TUN_S_CHILD_MAX, TUN_S_STK_MAX, TUN_S_DATA_MAX, TUN_S_VM_MAX and the input buffer is not a string of digits
EPERM
the calling application does not have the neccessary rights to set the needed tunable value
ENOENT
the underlying file does not exist.
ENOMEM
if the API failed to allocate memory
ERANGE
keyword is one of TUN_H_OP_MAX, TUN_S_OP_MAX, TUN_H_CHILD_MAX, TUN_S_CHILD_MAX, TUN_S_STK_MAX, TUN_S_DATA_MAX, TUN_S_VM_MAX and the input buffer contains a value that is out of range

3.3. Locating information (tun_locate)

#include <libtune.h>
int tun_locate(int keyword, char **location, int *loc_sz)

3.3.1. Description

This routine can be used to locate the underlying pseudo-file of a tunable: given a keyword, it returns in the string pointed to by location the path to the underlying pseudo-file. The path size is stored into loc_sz.
This routine is only meaningful for indexes that correspond to information that is managed through pseudo files.

3.3.2. Parameters

This routine takes the following parameters:

3.3.3. Returned values


EINVAL
keyword is invalid

outbuf is a NULL pointer

out_sz is a NULL pointer
ENOMEM
if the API failed to allocate memory

3.4. Getting the key word for a location (tun_get_kwd)

#include <libtune.h>
char *
tun_get_kwd(char *location, int *keyword)

3.4.1. Description

This is the reverse operation of the preceding one: given a location, it returns the associated keyword (to use for example in a set / get operation). It also returns a string that gives the corresponding constant name. Actually, since many tunables may have the same location, it is recommended to call this routine several times in order to get back all the possible keywords and constant names that correspond to the same location.
Example of tunables that have the same underlying location:

3.4.2. Parameters

This routine takes the following parameters:

3.4.3. Returned values

If successful, tun_get_kwd() returns a pointer to the next constant name for the specified location (this string is malloc'ed by the library and should then be freed by the calling application), or NULL if the location is not found anymore (in that case, *keyword is not updated and errno is set to ENOENT).
Note: if the location corresponds to a keyword that has been generated by the daemon, an empty string is returned ("").
On failure, ((char *) -1) is returned, *keyword is not updated and errno is set:

EINVAL
location is a NULL pointer

keyword points to an invalid value

location is an empty string

keyword is a NULL pointer
ENOMEM
if the API failed to allocate memory

3.5. Getting all the valid key words (tun_lst_all)

#include <libtune.h>
int tun_lst_all(int *keyword)

3.5.1. Description

This is an interface that can be used to get all the valid tunables present in the TUNDB database: given a keyword, it returns the next valid one in the supported tunables. This interface, combined with tun_help() (see below) is useful to know what are the tunables covered by the libtune API.

3.5.2. Parameters

This routine takes the following parameters:

3.5.3. Returned values

If successful, tun_lst_all() returns 0 and *keyword is filled with the next valid tunable value.
If there ane nomore valid tunables, TUN_ILLEGAL is returned.
On failure, -1 is returned, *keyword is not updated and errno is set:

EINVAL
keyword is a NULL pointer

keyword points to an invalid value

3.6. Getting help information (tun_help)

#include <libtune.h>
int tun_help(int keyword, char **help, size_t *help_sz)

3.6.1. Description

This routine can be used, given a keyword value, to return the corresponding help string into the string pointed to by help. The string size is stored into help_sz.

3.6.2. Parameters

This routine takes the following parameters:

3.6.3. Returned values


EINVAL
keyword is invalid

help is a NULL pointer

help_sz is a NULL pointer
ENOMEM
if the API failed to allocate memory

4. Supported tunables

Constant name
Tunable meaning
id parameter in the API interfaces
location
TUN_SHMMIN Minimum shm segment size (in bytes)

N/A
TUN_H_OP_MAX
Max number of open fds (hard limit)
N/A
TUN_S_OP_MAX Max number of open fds (soft limit)
N/A
TUN_H_CHILD_MAX Max number of processes (hard limit)
N/A
TUN_S_CHILD_MAX Max number of processes (soft limit)
N/A
TUN_S_STK_MAX stack size (soft limit)
N/A
TUN_S_DATA_MAX size of data segment (soft limit)
N/A
TUN_S_VM_MAX size of virtual memory (soft limit)
N/A
TUN_SEMMSL Max number of semaphores per id
/proc/sys/kernel/sem
TUN_SEMMNS Max number of semaphores in the system
/proc/sys/kernel/sem
TUN_SEMOPM Max number of operations per semop call
/proc/sys/kernel/sem
TUN_SEMMNI Max number of semaphore identifiers
/proc/sys/kernel/sem
TUN_REC_PACKS Number of receive packets for <interface> Network interface (string)
/proc/net/dev
TUN_MEMSPACE
Total memory space

/proc/meminfo
TUN_SWAPTOT Total swap space
/proc/meminfo
TUN_SWAPFREE
Free swap area
/proc/meminfo
TUN_HPGTOT Total number of huge pages
/proc/meminfo
TUN_HPGFREE Number of free huge pages
/proc/meminfo
TUN_HPGSZ Huge page size
/proc/meminfo
TUN_CTX_SW Number of context switches
/proc/stat
TUN_CPUPHYSID Physical id for <cpuid> CPU id (integer)
/proc/cpuinfo
TUN_SIBLINGS Number of sibling CPUs for CPU <cpuid> CPU id (integer)
/proc/cpuinfo
TUN_SHMMNI Maximum number of shm segment ids
/proc/sys/kernel/shmmni
TUN_SEM All semaphore parameters
/proc/sys/kernel/sem
TUN_CMDLINE Complete command line for process <pid> Process id (integer)
/proc/<PID>/cmdline
TUN_STAT Statistics for process <pid> Process id (integer)
/proc/<PID>/stat
TUN_MEMINFO Memory statistics
/proc/meminfo
TUN_SLEEPSTATE Sleep state
/sys/power/state
TUN_CPULIMITS limits for CPU <cpuid> CPU id (integer)
/proc/acpi/processor/CPU<CPUID>/limit
TUN_FILEMAX Max number of files

/proc/sys/fs/file-max
TUN_CPUINFO CPU info
/proc/cpuinfo
TUN_FIN_TIMEOUT Timeout for a FIN packet before the socket is forcibly closed
/proc/sys/net/ipv4/tcp_fin_timeout
TUN_MAX_BACKLOG Maximum # of queued connection requests which have still not received an ACK from the connecting client
/proc/sys/net/ipv4/tcp_max_syn_backlog
TUN_TW_REUSE Allow to reuse TIME-WAIT sockets for new connections
/proc/sys/net/ipv4/tcp_tw_reuse
TUN_LOC_P_RANGE Local port range used by TCP and UDP
/proc/sys/net/ipv4/ip_local_port_range
TUN_IPV4_RMEM Min-default-max memory size of the TCP receive buffers
/proc/sys/net/ipv4/tcp_rmem
TUN_IPV4_WMEM Min-default-max memory size of the TCP send buffers
/proc/sys/net/ipv4/tcp_wmem
TUN_WIN_SCALING Enable TCP to negociate the use of window scaling during connection set up

/proc/sys/net/ipv4/tcp_window_scaling
TUN_MTU_SIZE MTU size for <interface> Network interface (string)
/proc/sys/net/ipv6/conf/<interface>/mtu
TUN_PARTITIONS Disks info
/proc/partitions
TUN_NET_DEV Network device status info
/proc/net/dev
TUN_RMEM_MAX Max receive buffer size
/proc/sys/net/core/rmem_max
TUN_WMEM_MAX Max send buffer size
/proc/sys/net/core/wmem_max
TUN_NET_BACKLOG Max # of received buffers processed before congestion

/proc/sys/net/core/netdev_max_backlog
TUN_OVC_MEM Kernel policy for memory allocation

/proc/sys/vm/overcommit_memory
TUN_OVC_RATIO Percentage of memory added to the swap to get the max address space allowed to be committed

/proc/sys/vm/overcommit_ratio
TUN_SWAPPINESS Swappiness

/proc/sys/vm/swappiness
TUN_NR_HUGE_PG Number of configured huge pages
/proc/sys/vm/nr_hugepages
TUN_P_STAT Kernel and system statistics
/proc/stat
TUN_SHMALL
Max # of shm segment pages system wide

/proc/sys/kernel/shmall
TUN_SHMMAX
Max size, in bytes, of a shm segment

/proc/sys/kernel/shmmax
TUN_MSGMNI
Max # of msg queue ids

/proc/sys/kernel/msgmni
TUN_THREADS_MAX
Max # of threads

/proc/sys/kernel/threads-max
TUN_MIN_ADV_MSS
Min MSS value

/proc/sys/net/ipv4/route/min_adv_mss

4.1. RedHat specific tunables

Constant name
Tunable meaning
location
>= FC4 location
TUN_EXEC_SHIELD Security level for the exec-shield functionality - Red Hat specific
/proc/sys/kernel/exec-shield /proc/sys/kernel/exec-shield
TUN_EXEC_SHIELD_R Controls whether to randomize VM mappings - Red Hat specific
/proc/sys/kernel/exec-shield-randomize /proc/sys/kernel/randomize_va_space

4.2. SuSE specific tunables

Constant name
Tunable meaning
id parameter in the API interfaces
location
TUN_MAPPED_BASE Shared memory address map for <pid> - SuSE specific
Process id (integer)
/proc/<PID>/mapped_base

5. "Manual" howto

In the following chapters, we explain how to manually enhance the source tree in order to support more kernel releases, distros, distro families.

5.1. How to add support for a new kernel release

Assume you want to add suport for the 2.6.Z kernel release
  1. Create the directory db/include/basedbs/base-2.6.Z
  2. Create the db/include/basedbs/base-2.6.Z/libtuninitdb_base.h include file.
    This file should contain the database definition (TUNDB_K[] array) for the available tunables in 2.6.Z kernel release.
  3. It should be copied from templates/base/libtuninitdb_base.h and enhanced if needed.
    Each TUNDB_K[] index corresponds to a supported tunable (defined in include/libtune.h) and contains the following information:
  4. Create the distro specific include file (see the Howto for a new distribution).

5.2. How to add support for a new distribution family

Assume you want to add support for Fedora Core X.
  1. Create the directory db/include/distrodbs/distro-fcX
  2. Create the db/include/distrodbs/distro-fcX/libtuninitdb_distro.h include file.
    This file should contain the database definition (TUNDB_D[] array) for the available tunables in Fedora Core X family. It should be copied from templates/distro/libtuninitdb_distro.h and enhanced if needed.
    Each TUNDB_D[] index corresponds to a supported tunable (defined in include/libtune.h) and contains the following information:
If a family other than the ones already supported is to be supported, scripts/get_distro.sh should be changed to detect it and output a pseudo for that distro family. In that case, the <family_pseudo><family_release> directory should be created under db/include/distrodbs, <family_pseudo> being the result of get_distro.sh -f and <family_release> being the result of get_distro.sh -r:
# cd scripts
# F=`./get_distro.sh -f`
# R=`./get_distro.sh -r`
# cd ..
#
mkdir -p db/include/distrodbs/distro-${F}${R}

Today, the values that can be returned by scripts/get_distro.sh for ${R} are:
Distro
Distro family
Pseudo ($F)
RedHat


Fedora Core
fc
Red Hat Linux
RH
Red Hat Enterprise Linux
RHEL
SuSE

SuSE Linux
SL
SuSE Linux Enterprise Server
SLES

5.3. How to add support for a tunable

5.3.1. Kernel specific tunable

Assume you want to add the tunable TUN_BLAH_BLAH for the 2.6.Z kernel
  1. if this is a brand new tunable (i.e. it was not yet supported), define the tunable constant value into include/libtune.h, applying the following rule:
    1. take TUN_NEXT_K value for TUN_BLAH_BLAH constant value
    2. increment TUN_NEXT_K (this is important for the automatic scripts)
  2. (optional) define the following values:
  3. add the tune_t structure for TUN_BLAH_BLAH at the appropriate index of TUNDB_K[] array into db/include/basedbs/base-2.6.Z/libtuninitdb_base.h:

 5.3.2. Distro-dependent tunable

Assume you want to add the tunable TUN_BLAH_BLAH for the Red Hat Fedora Core X distribution:
  1. define the tunable value into include/libtune.h, applying the following rule:
    1. take TUN_NEXT_D value for TUN_BLAH_BLAH constant value
    2. increment TUN_NEXT_D (this is important for the automatic scripts)
  2. (optional) define the following values:
  3. add the tune_t structure for TUN_BLAH_BLAH at the appropriate index of TUNDB_D[] array into db/include/distrodbs/distro-fcX/libtuninitdb_distro.h (see previous chapter for the rules to apply)

6. "Automatic" howto

A set of scripts has been recently added to the delivery. With the help of these scripts it is now possible to automatically do all the operations described in the previous chapter (add support for a new kernel release, a new distro family, or a new tunable).

6.1. Adding support for a new kernel release (add_kernel.sh)

6.1.1. In the source tree

This is done by calling the script add_kernel.sh. If you want to add suport for the 2.6.30 kernel release:
# cd scripts
# ./add_support.sh 2.6.30
#
The effect of this command is to create the file db/include/base-2.6.30/libtuninitdb_base.h as described in chapter 5.1.

6.1.2. In the installed files

This is done by calling the script add_kernel.sh. If you want to add suport for the 2.6.30 kernel release:
# cd /usr/share/libtune/bin
# ./add_kernel.sh 2.6.30
#
The effect of this command is to create the following 2 files:

6.2. Adding support for a new distro family (add_distro.sh)

6.2.1. In the source tree

This is done by calling the script add_distro.sh.
If you want to add support for the Fedora Core 20 distro family (the characters in bold are those typed by the user, while the others are those output by the tool):
# cd scripts
# ./add_distro.sh fc 20
#../db/include/distrodbs/distro-fc20/libtuninitdb_distro.h has been successfully created
The effect of this command is to create the file db/include/distrodbs/distro-fc20/libtuninit_distro.h as described in chapter 5.2.

6.2.2. In the installed files

This is done by calling the script add_distro.sh.
If you want to add support for the Fedora Core 20 distro family (the characters in bold are those typed by the user, while the others are those output by the tool):
# cd /usr/share/libtune/bin
# ./add_distro.sh fc 20
# /usr/share/libtune/distrodbs/distro-fc20/libtuninitdb_distro.h has been successfully created
/usr/share/libtune/distrodbs/distro-fc20/tundb_distro has been successfully created

The effect of this command is to create the following 2 files:

6.3. Adding support for a new tunable (new_tunable.sh)

As for the previous commands, support can be added into one of:
The effect of the script is to update libtune.h (actually include/libtune.h if changing the source tree or /usr/include/libtune.h if changing the installed files). This script only needs to know if the tunable is kernel or distro-dependent (see 5.3).
 
If you want to add the kernel-dependent TUN_BLAH_BLAH_K tunable in the installed files (the characters in bold are those typed by the user, while the others are those output by the tool):
# cd /usr/share/libtune/bin
# ./new_tunable.sh BLAH_BLAH_K

*************** DEPENDENCY ***************

Is the tunable

1 ) kernel dependent
2 ) distro dependent
Answer: 1
TUN_BLAH_BLAH_K has been correctly added to /usr/include/libtune.h
Original /usr/include/libtune.h has been saved into /usr/include/libtune.h_ref_24580
# diff /usr/include/libtune.h /usr/include/libtune.h_ref_24580
105a106
> #define TUN_BLAH_BLAH_K      0x00036
107c108
< #define TUN_NEXT_K    0x00036
---
> #define TUN_NEXT_K    0x00037

6.4. Adding support for an existing tunable

Again, support can be added into one of:
The effect of the script is to update (see 5.3):
Support can be added for a tunable only after it has been defined into libtune.h (i.e. new_tunable.sh has been called - see 6.3). This is the only way for the automatic scripts to add the tunable description structure at the right index into the tunables database.
Support for a tunable may be added within an existing kernel release or distro. This is a first information that will be asked for by the script.
The next questions are common whether we are adding a kernel dependent tunable or a distro-dependent tunable. The only thing that differs is the changed files (see before).

If you want to add the kernel-dependent TUN_BLAH_BLAH_K tunable within the newly supported 2.6.30 kernel release (the characters in bold are those typed by the user, while the others are those output by the tool):

# ./add_tunable.sh BLAH_BLAH_K
TUN_BLAH_BLAH_K goes to kernel DB
Enter an existing kernel release:
1 ) 2.6.9
2 ) 2.6.17
3 ) 2.6.5
4 ) 2.6.16
5 ) 2.6.11
6 ) 2.6.30
Answer: 6

What file do you want to update
        1 ) database binary file
        2 ) database header file
        3 ) both files
Answer: 3
The following files will be updated
        /usr/share/libtune/basedbs/base-2.6.30/libtuninitdb_base.h
        /
usr/share/libtune/basedbs/base-2.6.30/tundb_kernel

************* TUNABLE CHARACTERISTICS ***************



*************** STRATEGY ROUTINE ***************

1 ) Get/set a given field in a file made of a single line
2 ) Get/set a given field within a given line in a file made
    of several lines
3 ) Get/set a value in a file made of a single block. This block
    is made of several lines that contain an identifier and the
    actual value.
4 ) Get/set a value in a file made of several blocks. Each block
    is identified by a unique identifier, and it is made of
    several lines that contain an identifier and the actual value.
5 ) Get/set the entire file contents
6 ) Other (no pseudo-file support)
Answer: 1
Enter the field number within a line to access the tunable
(should start at 0):
1


*************** FILE NAME ATTRIBUTE ***************

1 ) The pathname is a fixed string
2 ) Per process pathname (a pid is needed to build the path)
3 ) Per integer id (an id (int) is needed to build the path)
4 ) Per string id (an id (string) is needed to build the path)
5 ) Per user pathname (a uid is needed to build the path)
Answer: 1



*************** LOCATION PATH ***************
Enter the absolute path to the pseudo-file
(printf conversion sequences - %. - are recognized):
/proc/blah_blah_k


************** FILE CONTENTS ATTRIBUTE **************


1 ) System wide setting
2 ) Per object setting (object identified by an int)
3 ) Per object setting (object identified by a string)
Answer: 1



*************** HELP STRING ***************

Enter the help string in a single line format
(escape sequences are recognized and not interpreted):
help string for BLAH_BLAH_K

TUN_BLAH_BLAH_K has been correctly added to /usr/share/libtune/basedbs/base-2.6.30/tundb_kernel
Original /
usr/share/libtune/basedbs/base-2.6.30/tundb_kernel has been saved into /usr/share/libtune/basedbs/base-2.6.30/tundb_kernel_ref_24666

TUN_BLAH_BLAH_K has been correctly added to /
usr/share/libtune/basedbs/base-2.6.30/libtuninitdb_base.h
Original /
usr/share/libtune/basedbs/base-2.6.30/libtuninitdb_base.h has been saved into /usr/share/libtune/basedbs/base-2.6.30/libtuninitdb_base.h_ref_24666
# diff
/usr/share/libtune/basedbs/base-2.6.30/libtuninitdb_base.h_ref_24666 \
/usr/share/libtune/basedbs
/base-2.6.30/libtuninitdb_base.h
142a143,146
>       {ATTR_NAME_SYS_WIDE|ATTR_CONT_SYS_WIDE, 6,
>               "/proc/blah_blah_k",
>               "help string for blah_blah_k",
>               "TUN_BLAH_BLAH_K"},
#

6.5. Removing a tunable support

Again, support can be removed from one of:
The effect of the script is to update (see 5.3):
Support for a tunable may be removed from an existing kernel release or distro. This is a first information that will be asked for by the script.
The next questions are common whether we are removing a kernel dependent tunable or a distro-dependent tunable. The only thing that differs is the changed files (see before).

If you want to remove the kernel-dependent TUN_BLAH_BLAH_K tunable from the newly supported 2.6.30 kernel release (the characters in bold are those typed by the user, while the others are those output by the tool):
# ./remove_tunable.sh  BLAH_BLAH_K
TUN_BLAH_BLAH_K will be removed from kernel DB
Enter an existing kernel release:
1 ) 2.6.9
2 ) 2.6.17
3 ) 2.6.5
4 ) 2.6.16
5 ) 2.6.11
6 ) 2.6.30
Answer: 6

What file do you want to update
        1 ) database binary file
        2 ) database header file
        3 ) both files
Answer: 3
The following files will be updated
        /usr/share/libtune/basedbs/base-2.6.30/libtuninitdb_base.h
        /
usr/share/libtune/basedbs/base-2.6.30/tundb_kernel
TUN_BLAH_BLAH_K has been correctly removed from /
usr/share/libtune/basedbs/base-2.6.30/tundb_kernel
Original /
usr/share/libtune/basedbs/base-2.6.30/tundb_kernel has been saved into /usr/share/libtune/basedbs/base-2.6.30/tundb_kernel_ref_24845

TUN_BLAH_BLAH_K has been correctly removed from /
usr/share/libtune/basedbs/base-2.6.30/libtuninitdb_base.h
Original /
usr/share/libtune/basedbs/base-2.6.30/libtuninitdb_base.h has been saved into /usr/share/libtune/basedbs/base-2.6.30/libtuninitdb_base.h_ref_24845
# diff /
usr/share/libtune/basedbs/base-2.6.30/libtuninitdb_base.h_ref_24845 \ /usr/share/libtune/basedbs/base-2.6.30/libtuninitdb_base.h
143,146c143,144
<       {ATTR_NAME_SYS_WIDE|ATTR_CONT_SYS_WIDE, 6,
<               "/proc/blah_blah_k",
<               "help string for blah_blah_k",
<               "TUN_BLAH_BLAH_K"},
---
>       {ATTR_NONE, 0, "", "", ""},
#

6.6. Getting the list of supported tunables

The script get_tunedb scans the installed binary database and outputs the list of supported tunables.
If called without option, it ouput both the kernel-dependent and distro-dependent tunable.
If called with the -k option, it only outputs the kernel-dependent tunables
If called with the -d option, it only outputs the distro-dependent tunables.
For each tunable, the following values are output:
Here is the ouput for the distro-dependent tunables of a database installed on SLES 10 family:
# ./usr/bin/get_tunedb  -d

TUN_MAPPED_BASE      (0xC02)
        /proc/%d/mapped_base
        Shared memory address map for <pid>

6.7. Note

All the automatically generated files are copied from template files (under the template directory). The template files, as well as the generated ones should carefully be changed in order for the script to remain working correctly.

End of document