KPTOOL(1) KPTOOL(1) NAME kptool - view or change the contents of a keeper database SYNOPSIS kptool [option] [key] DESCRIPTION kptool allows the contents of the keeper database to be listed, or modified. Keeper is a library which gives a simple interface for storing and retrieving configuration data. For example to save and restore the settings in a program. The data is stored in text files in readable form, but the exact for- mat of the files must be considered unknown. The data should only be modified through the interface provided by the library. The configuration data is accessed by means of a key-path. The format of this path is described in the following sec- tion. KEY FORMAT The key-path is used to identify a single configuration data. This has the following general format: section/path/.../file:/path/.../name The key path is very similar to a file path. The only dif- ference is that it is split into two parts by a colon (:). The path before and after the colon can have arbitary num- ber of components. The colon should be placed after that part of the path, which represents a single program's data. (The placing of the colon only affects the representation of the data on disk, and not how the data is accessed. I.e. the path before the colon determines a configuration file, while the path after the colon determines a single entry in the file.) Keeper has three sections for storing configuration: local, user and global. Keeper can also present the union of any of these sections, so for example it is possible to store a default value in the global section, and override it with a value in the user section. Local Denoted by "l" at the beginning of the key path. This is for data that is specific to the local machine. User Denoted by "u" at the beginning of the key path. This is Version 1.0 20 Feb 2000 1 KPTOOL(1) KPTOOL(1) the user's data. This section is probably the most useful. Global Denoted by "g" at the beginning of the key path. This is data that is shared across all machines in a LAN. For this reason the data should reside in a directory which is mounted from an NFS server. The default directory is /home/keeper , but this can be changed, by setting the value of the key l/keeper/globaldir to the desired direc- tory. If the key path begins with more then one letter, then these sections are checked in order for the requested key. This way if you specify "ug" as a section, first the user section is checked, and if the key is not found the global section is checked. This way the global section could con- tain the default values for an application, which could be overridden by the user. Note: this only applies to getting a key's value. When setting a key's value, it is only stored in the first specified section. Access rights to the keys in the database are determined by the normal file access rights in the filesystem. Keeper does not impose further limitations on the access, since these could be bypassed by accessing the database directly. Files and directories in the keeper database are normally created with read-write access to the owner (user) and read access to everybody else. If private information needs to be stored, the following method can be used. If a path component in the key ends with a '-' character, that component (file or directory) is created with read-write access only to the owner (user), and no access to every- body else. This rule of course, only applies to the path components before the colon. OPTIONS -h --help Get help. Prints a list of options with a short description. -l List keys. This option list the name, type and value of keys found in the database. If no key argument is given, then the whole database is listed. If a directory key is given, then the directory is recursively listed. -s Type Value Set the value of a key. A key argument must be specified after this option. If the key does not exist, it is created, together with any missing directories. An existing key's value can be set to a different type as it was previously, but you Version 1.0 20 Feb 2000 2 KPTOOL(1) KPTOOL(1) cannot set the value of a directory key. -g Type Get the value of key. A key argument must be speci- fied after this option. The value is formatted according to the type, and it is printed on the standard output, with a newline at the end. -r Remove a key. A key argument must be specified after this option. This removes the key from the database. Directory keys cannot be removed, but directories are automatically removed when they become empty. -t Get the type of a key's value. A key argument must be specified after this option. This option prints the type of the key on the standard output, with a newline at the end. See the list of types in the next section. If the type of the key is unknown, then UNKNOWN is printed. -i Import part of a database from a file. A filename argument must be specified after this option. With this option multiple keys can be imported from a text file. The file has the same syntax as the out- put of the -l option. --recursive-remove Remove a key recursively. A key argument must be specified after this options. This removes the key from the database. If the key is a directory, the contents of it are recursively removed also. Use this option with care! TYPES The following type codes can be used after the -s or -g options. Invoking the program with the -t option prints one of these codes. D Type is data. When setting a data type, a hexadec- imal byte list should be specified as the value (e.g. 537a4d). The value of this type of key is printed also in this way. S Type is string. A single string argument should be specified when setting a string value. If it con- tains spaces or other special characters inter- preted by the shell, the value should be enclosed in double quotes. I Type is integer. A decimal integer should be spec- ified if setting a value. The value should not exceed the minimum and maximum values that can be represented by a signed 32-bit integer. Version 1.0 20 Feb 2000 3 KPTOOL(1) KPTOOL(1) F Type is float. When setting a float type, a float- ing point number should be specified as the value. The number is internally stored in double precision float format DIR Type is key directory. This type is only valid with the -g option. In this case the names of the keys that are contained in the directory are listed, one per line. ERRORS When kptool encounters an error during an operation on the keeper database, it prints one of the following error mes- sages: Key does not exist This means that an attempt was made to list, get or remove a nonexistent key. Access denied You have no permission to execute that operation on the database. Bad key This error can be caused by a variety of reasons: The format of the key is wrong; Trying to set a value of a directory key; Trying to remove a direc- tory key; etc. Bad type This error happens, when a wrong type is specified for the get option. Bad database This message is printed if the database contains some inconsistency. This cannot happen, unless the database was manually modified. Not enough resources If the disk is full which contains the database, or some other resoruce is exhausted, then this error message is shown. EXAMPLES Set the path to the global database to /mnt/share/keeper: kptool -s S /mnt/share/keeper l/keeper/globaldir List the saved menu accelerators of gkeeper: kptool -l ug/SerSoft/gkeeper:/menus Set a private key: Version 1.0 20 Feb 2000 4 KPTOOL(1) KPTOOL(1) kptool -s S Hello u/MacroSoft/someprog-:/password SEE ALSO keeper(3) http://www.inf.bme.hu/~mszeredi/keeper/index.html BUGS None known. AUTHOR Miklos Szeredi (EMAIL: mszeredi@inf.bme.hu) Version 1.0 20 Feb 2000 5