libpmemobj

package: libpmemobj-devel

title: libpmemobj(7)

text:
# libpmemobj(7)

## NAME
libpmemobj - persistent memory transactional object store

## SYNOPSIS

```
#include <libpmemobj.h>
cc -std=gnu99 ... -lpmemobj -lpmem

```

### Library API versioning:

```
const char *pmemobj_check_version(

    unsigned major_required,

    unsigned minor_required);

```

### Managing library behavior:

```
void pmemobj_set_funcs(

    void *(*malloc_func)(size_t size),

    void (*free_func)(void *ptr),

    void *(*realloc_func)(void *ptr, size_t size),

    char *(*strdup_func)(const char *s));

```

### Error handling:

```
const char *pmemobj_errormsg(void);

```

### Other library functions:
A description of other libpmemobj functions can be found on the following manual pages:

- control and statistics: pmemobj_ctl_get(3)

- create, open, close and validate: pmemobj_open(3)

- low-level memory manipulation: pmemobj_memcpy_persist(3)

- locking: pmemobj_mutex_zero(3)

- persistent object identifier: OID_IS_NULL(3)

- type-safety: TOID_DECLARE(3)

- layout declaration: POBJ_LAYOUT_BEGIN(3)

- non-transactional atomic allocations: pmemobj_alloc(3)

- root object management: pmemobj_root(3)

- object containers: pmemobj_first(3)

- non-transactional persistent atomic circular doubly-linked list: pmemobj_list_insert(3), POBJ_LIST_HEAD(3)

- transactional object manipulation: pmemobj_tx_begin(3), pmemobj_tx_add_range(3), pmemobj_tx_alloc(3)

- delayed atomicity actions: pmemobj_action(3) (EXPERIMENTAL)

## DESCRIPTION
libpmemobj provides a transactional object store in persistent memory (pmem) for applications that require transactions and persistent memory management using direct access storage (DAX), which is storage that supports load/store access without paging blocks from a block storage device. Some types of non-volatile memory DIMMs (NVDIMMs) provide this type of byte addressable access to storage. A persistent memory aware file system is typically used to expose the direct access to applications. Memory mapping a file from this type of file system results in load/store, non-paged access to pmem. libpmemobj builds on this type of memory mapped file using the low-level pmem support provided by libpmem(7), handling the transactional updates, flushing changes to persistence, and managing recovery for the application.

libpmemobj requires the -std=gnu99 compilation flag to build properly.

libpmemobj is one of a collection of persistent memory libraries available. The other is libpmem(7), low-level persistent memory support.

Under normal usage, libpmemobj will never print messages or intentionally cause the process to exit. The only exception to this is the debugging information, when enabled, as described under DEBUGGING AND ERROR HANDLING, below.

## LIBRARY API VERSIONING
This section describes how the library API is versioned, allowing applications to work with an evolving API.

The pmemobj_check_version() function is used to see if the installed libpmemobj supports the version of the library API required by an application. The easiest way to do this is for the application to supply the compile-time version information, supplied by defines in <libpmemobj.h>, like this:

```
reason = pmemobj_check_version(PMEMOBJ_MAJOR_VERSION, PMEMOBJ_MINOR_VERSION);
if (reason != NULL) {

    /* version check failed, reason string tells you why */
}

```

Any mismatch in the major version number is considered a failure, but a library with a newer minor version number will pass this check since increasing minor versions imply backwards compatibility.

An application can also check specifically for the existence of an interface by checking for the version where that interface was introduced. These versions are documented in this man page as follows: unless otherwise specified, all interfaces described here are available in version 1.0 of the library. Interfaces added after version 1.0 will contain the text introduced in version x.y in the section of this manual describing the feature.

On success, pmemobj_check_version() returns NULL. Otherwise, the return value is a static string describing the reason the version check failed. The string returned by pmemobj_check_version() must not be modified or freed.

## MANAGING LIBRARY BEHAVIOR
The pmemobj_set_funcs() function allows an application to override memory allocation calls used internally by libpmemobj. Passing in NULL for any of the handlers will cause the libpmemobj default function to be used. The library does not make heavy use of the system malloc functions, but it does allocate approximately 4-8 kilobytes for each memory pool in use.

By default, libpmemobj supports up to 1024 parallel transactions/allocations. For debugging purposes it is possible to decrease this value by setting the PMEMOBJ_NLANES environment variable to the desired limit.

## ERROR HANDLING
If an error is detected during the call to a libpmemobj function, the application may retrieve an error message describing the reason for the failure from pmemobj_errormsg(). This function returns a pointer to a static buffer containing the last error message logged for the current thread. If errno was set, the error message may include a description of the corresponding error code as returned by strerror(3). The error message buffer is thread-local; errors encountered in one thread do not affect its value in other threads. The buffer is never cleared by any library function; its content is significant only when the return value of the immediately preceding call to a libpmemobj function indicated an error, or if errno was set. The application must not modify or free the error message string, but it may be modified by subsequent calls to other library functions.

In parallel to the above mechanism, all logging messages are written to syslog(3) and/or stderr(3) or passed to the user-provided logging function. Please see pmemobj_log_set_function(3) for details. The influx of the reported messages can be controlled by setting a respective threshold value. Please see pmemobj_log_set_threshold(3) for details.

## DEBUGGING
Two versions of libpmemobj are typically available on a development system. The normal version, accessed when a program is linked using the -lpmemobj option, is optimized for performance. That version skips checks that impact performance and never logs any trace information or performs any run-time assertions.

A second version of libpmemobj, accessed when a program uses the libraries under /usr/lib/pmdk_debug, contains run-time assertions and trace points. The typical way to access the debug version is to set the environment variable LD_LIBRARY_PATH to /usr/lib/pmdk_debug or /usr/lib64/pmdk_debug, as appropriate.

## LOGGING (DEPRECATED)
Debugging output is controlled using the following environment variables. These variables have no effect on the non-debug version of the library.

•

PMEMOBJ_LOG_LEVEL

The value of the PMEMOBJ_LOG_LEVEL environment variable enables trace points in the debug version of the library, as follows:

- 0 - This is the default level when PMEMOBJ_LOG_LEVEL is not set. No log messages are emitted at this level.

- 1 - Additional details on any errors detected are logged, in addition to returning the errno-based errors as usual. The same information may be retrieved using pmemobj_errormsg().

- 2 - A trace of basic operations is logged.

- 3 - Enables a very verbose amount of function call tracing in the library.

- 4 - Enables voluminous and fairly obscure tracing information that is likely only useful to the libpmemobj developers.

Unless the PMEMOBJ_LOG_FILE environment variable is set, the debugging output is written to stderr.

•

PMEMOBJ_LOG_FILE

Specifies the name of a file where all logging information should be written. If the last character in the name is “-”, the PID of the current process will be appended to the file name when the log file is created. If PMEMOBJ_LOG_FILE is not set, logging output is written to stderr.

Whenever either PMEMOBJ_LOG_LEVEL or PMEMOBJ_LOG_FILE environment variable is set the messages are not passed via the routes described in the ERROR HANDLING section except for the pmemobj_errormsg() which works unconditionally.

See also libpmem(7) to get information about other environment variables affecting libpmemobj behavior.

## EXAMPLE
See https://pmem.io/pmdk/libpmemobj for examples using the libpmemobj API.

## ACKNOWLEDGEMENTS
libpmemobj builds on the persistent memory programming model recommended by the SNIA NVM Programming Technical Work Group: https://snia.org/nvmp

## SEE ALSO
OID_IS_NULL(3), pmemobj_alloc(3), pmemobj_ctl_exec(3), pmemobj_ctl_get(3), pmemobj_ctl_set(3), pmemobj_first(3), pmemobj_list_insert(3), pmemobj_memcpy_persist(3), pmemobj_mutex_zero(3), pmemobj_open(3), pmemobj_root(3), pmemobj_tx_add_range(3), pmemobj_tx_alloc(3), pmemobj_tx_begin(3), POBJ_LAYOUT_BEGIN(3), POBJ_LIST_HEAD(3), strerror(3), TOID_DECLARE(3), libpmem(7) and https://pmem.io


libpmempool

package: libpmempool-devel

title: libpmempool(7)

text:
# libpmempool(7)

## NAME
libpmempool - persistent memory pool management library

## SYNOPSIS

```
#include <libpmempool.h>
cc -std=gnu99 ... -lpmempool -lpmem

```

### Library API versioning:

```
const char *pmempool_check_version(

    unsigned major_required,

    unsigned minor_required);

```

### Error handling:

```
const char *pmempool_errormsg(void);

```

### Other library functions:
A description of other libpmempool functions can be found on the following manual pages:

- health check functions: pmempool_check_init(3)

- pool set synchronization and transformation: pmempool_sync(3)

- pool set management functions: pmempool_rm(3)

- toggle or query pool set features: pmempool_feature_query(3)

## DESCRIPTION
libpmempool provides a set of utilities for off-line analysis and manipulation of a pool. A pool in this manpage means a pmemobj pool independent of the underlying storage. Some libpmempool functions are required to work without any impact on the pool but some may create a new or modify an existing pool.

libpmempool is for applications that need high reliability or built-in troubleshooting. It may be useful for testing and debugging purposes also.

libpmempool introduces functionality of pool set health check, synchronization, transformation and removal.

## CAVEATS
libpmempool relies on the library destructor being called from the main thread. For this reason, all functions that might trigger destruction (e.g. dlclose(3)) should be called in the main thread. Otherwise some of the resources associated with that thread might not be cleaned up properly.

libpmempool requires the -std=gnu99 compilation flag to build properly.

## LIBRARY API VERSIONING
This section describes how the library API is versioned, allowing applications to work with an evolving API.

The pmempool_check_version() function is used to see if the installed libpmempool supports the version of the library API required by an application. The easiest way to do this for the application is to supply the compile-time version information, supplied by defines in <libpmempool.h>, like this:

```
reason = pmempool_check_version(PMEMPOOL_MAJOR_VERSION,

                                PMEMPOOL_MINOR_VERSION);
if (reason != NULL) {

    /* version check failed, reason string tells you why */
}

```

Any mismatch in the major version number is considered a failure, but a library with a newer minor version number will pass this check since increasing minor versions imply backwards compatibility.

An application can also check specifically for the existence of an interface by checking for the version where that interface was introduced. These versions are documented in this man page as follows: unless otherwise specified, all interfaces described here are available in version 1.0 of the library. Interfaces added after version 1.0 will contain the text introduced in version x.y in the section of this manual describing the feature.

When the version check performed by pmempool_check_version() is successful, the return value is NULL. Otherwise the return value is a static string describing the reason for failing the version check. The string returned by pmempool_check_version() must not be modified or freed.

## DEBUGGING AND ERROR HANDLING
If an error is detected during the call to a libpmempool function, the application may retrieve an error message describing the reason for the failure from pmempool_errormsg(). This function returns a pointer to a static buffer containing the last error message logged for the current thread. If errno was set, the error message may include a description of the corresponding error code as returned by strerror(3). The error message buffer is thread-local; errors encountered in one thread do not affect its value in other threads. The buffer is never cleared by any library function; its content is significant only when the return value of the immediately preceding call to a libpmempool function indicated an error, or if errno was set. The application must not modify or free the error message string, but it may be modified by subsequent calls to other library functions.

Two versions of libpmempool are typically available on a development system. The normal version, accessed when a program is linked using the -lpmempool option, is optimized for performance. That version skips checks that impact performance and never logs any trace information or performs any run-time assertions.

A second version of libpmempool, accessed when a program uses the libraries under /usr/lib/pmdk_debug, contains run-time assertions and trace points. The typical way to access the debug version is to set the environment variable LD_LIBRARY_PATH to /usr/lib/pmdk_debug or /usr/lib64/pmdk_debug, as appropriate. Debugging output is controlled using the following environment variables. These variables have no effect on the non-debug version of the library.

•

PMEMPOOL_LOG_LEVEL

The value of PMEMPOOL_LOG_LEVEL enables trace points in the debug version of the library, as follows:

- 0 - This is the default level when PMEMPOOL_LOG_LEVEL is not set. No log messages are emitted at this level.

- 1 - Additional details on any errors detected are logged (in addition to returning the errno-based errors as usual). The same information may be retrieved using pmempool_errormsg().

- 2 - A trace of basic operations is logged.

- 3 - Enables a very verbose amount of function call tracing in the library.

- 4 - Enables voluminous and fairly obscure tracing information that is likely only useful to the libpmempool developers.

Unless PMEMPOOL_LOG_FILE is set, debugging output is written to stderr.

•

PMEMPOOL_LOG_FILE

Specifies the name of a file where all logging information should be written. If the last character in the name is “-”, the PID of the current process will be appended to the file name when the log file is created. If PMEMPOOL_LOG_FILE is not set, output is written to stderr.

## EXAMPLE
The following example illustrates how the libpmempool API is used. The program detects the type and checks consistency of given pool. If there are any issues detected, the pool is automatically repaired.

```
#include <stddef.h>
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
#include <libpmempool.h>
#define PATH "./pmem-fs/myfile"
#define CHECK_FLAGS (PMEMPOOL_CHECK_FORMAT_STR|PMEMPOOL_CHECK_REPAIR|\

                     PMEMPOOL_CHECK_VERBOSE)
int
main(int argc, char *argv[])
{

    PMEMpoolcheck *ppc;

    struct pmempool_check_status *status;

    enum pmempool_check_result ret;

    /* arguments for check */

    struct pmempool_check_args args = {

        .path       = PATH,

        .backup_path    = NULL,

        .pool_type  = PMEMPOOL_POOL_TYPE_DETECT,

        .flags      = CHECK_FLAGS

    };

    /* initialize check context */

    if ((ppc = pmempool_check_init(&args, sizeof(args))) == NULL) {

        perror("pmempool_check_init");

        exit(EXIT_FAILURE);

    }

    /* perform check and repair, answer 'yes' for each question */

    while ((status = pmempool_check(ppc)) != NULL) {

        switch (status->type) {

        case PMEMPOOL_CHECK_MSG_TYPE_ERROR:

            printf("%s\n", status->str.msg);

            break;

        case PMEMPOOL_CHECK_MSG_TYPE_INFO:

            printf("%s\n", status->str.msg);

            break;

        case PMEMPOOL_CHECK_MSG_TYPE_QUESTION:

            printf("%s\n", status->str.msg);

            status->str.answer = "yes";

            break;

        default:

            pmempool_check_end(ppc);

            exit(EXIT_FAILURE);

        }

    }

    /* finalize the check and get the result */

    ret = pmempool_check_end(ppc);

    switch (ret) {

        case PMEMPOOL_CHECK_RESULT_CONSISTENT:

        case PMEMPOOL_CHECK_RESULT_REPAIRED:

            return 0;

        default:

            return 1;

    }
}

```

See https://pmem.io/pmdk/libpmempool for more examples using the libpmempool API.

## ACKNOWLEDGEMENTS
libpmempool builds on the persistent memory programming model recommended by the SNIA NVM Programming Technical Work Group: https://snia.org/nvmp

## SEE ALSO
dlclose(3), pmempool_check_init(3), pmempool_feature_query(3), pmempool_rm(3), pmempool_sync(3), strerror(3), libpmem(7), libpmemobj(7)** and https://pmem.io

branch: sisyphus


libpolyxmass

package: libpolyxmass

title: libpolyxmass(7)

text:
# libpolyxmass(7)

## NAME
libpolyxmass — a library package for the GNU polyxmass project.

## SYNOPSIS
libpolyxmass

## DESCRIPTION
This manual page documents briefly the libpolyxmass package. This package contains a library that is used in the GNU polyxmass program. Its function is to house helper functions and chemistry-related functions to be used by the GNU polyxmass program.

## SEE ALSO
polyxmass (1), polyxmass-common (7), polyxmass-data (7), polyxmass-doc (7).

The GNU polyxmass program is documented fully in the GNU polyxmass User Manual (/usr/share/doc/polyxmass-doc/pdf/polyxmass.pdf), available in the polyxmass-doc.

## AUTHOR
This manual page was written by Filippo Rusconi <polyxmass-maintainer@polyxmass.org>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or any later version, published by the Free Software Foundation.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL.


quvi-object

package: libquvi-devel

title: quvi-object(7)

summary: Overview of the libquvi quvi\-object

text:
# quvi-object(7)

## NAME
quvi-object - Overview of the libquvi quvi-object

## DESCRIPTION
quvi-object is a collection of libquvi functions provided for the libquvi-scripts(7). These functions vary from HTTP functions to cryptographic functions. All of the quvi-object functions are implemented in C.

Note The quvi-object should not be confused with the quvi-modules(7) which are a selection of importable modules implemented in Lua. These modules are intended to be loaded (require) from the libquvi-scripts(7).

## OPTIONS
Each of the quvi-object functions may be passed a dictionary defining the additional option properties. The following options are supported by all of the functions:

qoo_croak_if_error=<boolean>

By default the library terminates the process if an error occurs. By setting this option to false, it will register the error and continues execution, leaving the error handling for the script to determine. See also "RETURN VALUES".

The qoo prefix is short for quvi object option. The functions will ignore any unknown options, e.g. the crypto functions would ignore the HTTP options.

Note The options have been defined in the quvi/const of the quvi-modules(7)

### Crypto
These options are specific to the quvi.crypto.* functions of the quvi-object.

qoo_crypto_algorithm=<value>

Specifies the algorithm that should be used. The value is expected to be a string, e.g. sha1 or aes256.

qoo_crypto_cipher_flags=<value>

Specifies the cipher flags (bit OR’d, see quvi-modules-3rdparty(7) for bit operations) to be used with the cipher. These values are identical to those defined by libgcrypt. See the quvi/const of the quvi-modules(7) for a complete list of the available cipher flags.

qoo_crypto_cipher_mode=<value>

Specifies the cipher mode to be used. These are identical to the values defined by libgcrypt. See the quvi/const of the quvi-modules(7) for a complete list of the available cipher modes.

qoo_crypto_cipher_key=<value>

Used to specify the cipher key. It should be noted that the key is expected to be passed in hexadecimal form. See quvi/hex of the quvi-modules(7) for the conversion functions. NOTE: The key derivation is left for the script to do

NOTE: The key is not a pass{word,phrase}

See also: http://www.di-mgt.com.au/cryptokeys.html#passwordpassphraseandkey

### HTTP
These options are specific to the quvi.http.* functions of the quvi-object.

qoo_fetch_from_charset=<charset>

Instructs the library to convert from this charset to UTF-8. Using this option may be required with the websites that use a specific (non-UTF8) encoding. The purpose of this option is to make sure that the data is encoded to unicode (UTF-8) before any of it is parsed and returned to the application using libquvi.

By default, libquvi converts the data which is in the encoding used for the strings by the C runtime in the current locale into UTF-8. IF this fails, and the from charset option is set, the library will then try to convert to UTF-8 using the from charset value.

qoo_http_cookie_mode=<value>

Modify the cookie settings for the libcurl session handle. This feature wraps the cookie features provided by libcurl_easy_setopt(3). See the quvi/const of the quvi-modules(7) for a complete list of the available cookie modes. See also libcurl-tutorial(3) which covers the use of cookies with the library in greater detail.

## RETURN VALUES
Each quvi-object function will return a dictionary containing the following values:

error_message

The error message, or an empty value.

quvi_code

The code returned by the library. See also quvi/const of quvi-modules(7).

Refer to the function documentation for the information about the additional values returned in the dictionary.

## FUNCTIONS

### Base64
quvi.base64.encode(<plaintext>[,qoo])

Encode the plaintext to base64 format. The plaintext is expected to be passed in hexadecimal form. See quvi/hex of the quvi-modules(7) for the conversion functions. The second argument (qoo) is expected to be a dictionary of additional quvi object options, if defined at all.

The function will return the base64 value in the dictionary.

quvi.base64.decode(<base64>)

Decode the base64 value to plaintext. The function will return the plaintext value in the dictionary. The value is returned in hexadecimal form.

### Crypto
The crypto facility of the quvi-object wraps the libgcrypt symmetric cryptography and the hash (message digest) functions.

Note The availability of the algorithms is determined by libgcrypt, and how it was built

quvi.crypto.encrypt(<plaintext>, <qoo>)

Encrypt the plaintext. The plaintext is expected to be passed in hexadecimal form. See quvi/hex of the quvi-modules(7) for the conversion functions. The second argument (qoo) is expected to be a dictionary containing the cipher options.

The function will return the ciphertext value in the dictionary. The value is returned in hexadecimal form.

quvi.crypto.decrypt(<ciphertext>, <qoo>)

Decrypt the ciphertext. The ciphertext is expected to be passed in hexadecimal form. See quvi/hex of the quvi-modules(7) for the conversion functions. The second argument (qoo) is expected to be a dictionary containing the cipher options.

The function will return the plaintext value in the dictionary. This value is returned in hexadecimal form.

quvi.crypto.hash(<value>, <qoo>)

Generate a hash from the value. The value is expected to be passed in hexadecimal format. See quvi/hex of the quvi-modules(7) for the conversion functions. The second argument (qoo) is expected to be a dictionary containing the hash options, e.g. the algorithm that should be used.

The function will return the digest value in the dictionary. The value is returned in hexadecimal form.

### HTTP
The HTTP functions will return response_code along the other "RETURN VALUES", and the values specific to the HTTP function.

quvi.http.cookie(<VALUE>,<qoo>)

Modify the libcurl session handle cookie settings that libquvi currently uses. The second argument (qoo) is expected to be a dictionary containing the cookie options, e.g. the cookie mode that should be used.

The complete list of the available cookie modes can be found in the quvi/const module of the quvi-modules(7). The mode names are named after their equivalent CURLOPT_COOKIE{SESSION,FILE,LIST,JAR} variable names. For a description of each option, see libcurl_easy_setopt(3).

This function will not return any additional values in the dictionary.

Note libquvi will ignore any calls to quvi.http.cookie unless QUVI_OPTION_ALLOW_COOKIES is QUVI_TRUE

Note libcurl will parse the received cookies and use them in the subsequent HTTP requests only if libquvi QUVI_OPTION_ALLOW_COOKIES is QUVI_TRUE

quvi.http.fetch(<URL>[,qoo])

Fetch an URL over an HTTP connection. The second argument (qoo) is expected to be a dictionary of additional quvi object options, if defined at all.

The function will return the data value among the values in the returned dictionary.

quvi.http.header(<VALUE>[,qoo])

Add, remove or replace internally used libcurl HTTP headers. The second argument (qoo) is expected to be a dictionary of additional quvi object options, if defined at all.

This function essentially wraps CURLOPT_HTTPHEADER, and will not return any additional values in the dictionary. See curl_easy_setopt(3) for the full description of CURLOPT_HTTPHEADER.

Note To clear the custom headers, pass "" as the VALUE; the custom headers are also cleared automatically when a support script function parse is called

quvi.http.metainfo(<URL>[,qoo])

Query the HTTP metainfo for the URL. The second argument (qoo) is expected to be a dictionary of additional quvi object options, if defined at all.

The function will return the content_length and the content_type values among the values in the returned dictionary.

quvi.http.resolve(<URL>[,qoo])

Resolve an URL redirection. The second argument (qoo) is expected to be a dictionary of additional quvi object options, if defined at all.

The function will return the resolved_url among the values in the returned dictionary. If the URL did not redirect to another location, the value of the resolved_url is left empty.

## EXAMPLES

### Base64
•Base64 encode a string:

```
local H = require 'quvi/hex'
local s = H.to_hex('foo') -- Pass in hexadecimal form
local r = quvi.base64.encode(s)
print(r.base64)
```

•Reverse the process:

```
local r = quvi.base64.decode(r.base64)
local s = H.to_str(r.plaintext)
```

### Crypto
•Encrypt plaintext:

```
local plaintext = 'f34481ec3cc627bacd5dc3fb08f273e6'
local key = '00000000000000000000000000000000'
local C = require 'quvi/const'
local o = {

  [C.qoo_crypto_cipher_mode] = C.qoco_cipher_mode_cbc,

  [C.qoo_crypto_algorithm] = 'aes',

  [C.qoo_crypto_cipher_key = key
}
local r = quvi.crypto.encrypt(plaintext, o)
print(r.ciphertext)
```

•Reverse the process:

```
local r = quvi.crypto.decrypt(r.ciphertext, o)
print(r.plaintext)
```

•Generate a hash (message digest):

```
local H = require 'quvi/hex'
local s = H.to_hex('foo') -- Pass in hexadecimal form
local C = require 'quvi/const'
local o = { [C.qoo_crypto_algorithm] = 'sha1' }
local r = quvi.crypto.hash(s, o)
print(r.digest)
```

•Same as above, but use the shorthand function:

```
local A = require 'quvi/hash'
local r = A.sha1sum('foo')
print(r)
```

### HTTP
•Dump the cookies in the memory to stdout:

```
local C = require 'quvi/const'
local o = { [C.qoo_http_cookie_mode] = C.qohco_mode_jar }
local r = quvi.http.cookie('-', o)
```

•Identical to the above but use the wrapper module:

```
local K = require 'quvi/http/cookie'
local r = K.jar('-')
```

•Fetch an URL:

```
local r = quvi.http.fetch('http://example.com')
```

r.data would now hold the contents. If an error occurred, e.g. connection failed, the library would exit the process with an error.

•Same as above, but handle the error in the script:

```
local C = require 'quvi/const'
local o = { [C.qoo_croak_if_error] = false }
local r = quvi.http.fetch('http://example.com', o)
if r.quvi_code ~= C.qerr_ok then

  local s =

    string.format('quvi.http.fetch: %s (libquvi=%d, http/%d)',

                  r.error_message, r.quvi_code, r.response_code)

  error(s)
end
```

By setting qoo_croak_if_error to false, we tell the library to only register that an error occurred and return the control to the script. Handling of the error is then left for the script to do.

Note

Typically, the scripts would not need to handle the error

•Force conversion from ISO-8859-1 to UTF-8:

```
local C = require 'quvi/const'
local o = { [C.qoo_fetch_from_charset] = 'ISO-8859-1' }
local r = quvi.http.fetch('http://example.com', o)
```

•Override user-agent header in the HTTP request:

```
local r = quvi.http.header('User-Agent: foo/1.0')
r = quvi.http.fetch(...)
```

•Disable an internal header in the HTTP request:

```
local r = quvi.http.header('Accept:')
r = quvi.http.fetch(...)
```

•Send a cookie in the HTTP request:

```
local r = quvi.http.header('Cookie: foo=1')
r = quvi.http.fetch(...)
```

•Query metainfo for an URL:

```
local r = quvi.http.metainfo('http://is.gd/SKyg8m')
print(r.content_length, r.content_type)
```

•Resolve URL redirection:

```
local r = quvi.http.resolve('http://is.gd/SKyg8m')
if #r.resolved_url >0 then

  print('new location:', r.resolved_url)
end
```

## SEE ALSO
libquvi-scripts(7), libquvi(3), quvi-modules(7), quvi-modules-3rdparty(7)

## FURTHER RESOURCES
Home

http://quvi.sourceforge.net/

Development code

git://repo.or.cz/libquvi.git

gitweb

http://repo.or.cz/w/libquvi.git

C API reference

The latest C API reference documentation may be viewed online at http://quvi.sourceforge.net/r/api/0.9/.

GLib

http://developer.gnome.org/glib/stable/glib-Base64-Encoding.html

libcurl

http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTUSERAGENT http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE

libgcrypt reference manual

http://www.gnupg.org/documentation/manuals/gcrypt/

## AUTHORS
Toni Gundogdu <legatvs@gmail.com>

Author.

## REPORTING BUGS
Report bugs to the quvi-devel mailing list <quvi-devel@lists.sourceforge.net> where the development and the maintenance is primarily done. You do not have to be subscribed to the list to send a message there.

## LICENSE
libquvi is Free Software licensed under the GNU Affero GPLv3+

## LIBQUVI
Part of the libquvi(3) suite


libquvi-scripts

package: libquvi-scripts

title: libquvi-scripts(7)

summary: Overview of the library scripts

text:
# libquvi-scripts(7)

## NAME
libquvi-scripts - Overview of the library scripts

## DESCRIPTION
libquvi-scripts contains the Lua scripts for libquvi that it uses to parse the different properties, such as the media properties.

## TYPES

### Common scripts
The common scripts are modules that may be loaded from other scripts, e.g. the quvi-modules(7).

These scripts are typically installed at

$prefix/share/libquvi-scripts/$major_ver.$minor_ver/common/

### Media scripts
The media scripts are responsible for parsing the media properties, e.g. the media stream URLs. There is usually a media script for each supported website.

These scripts are typically installed at

$prefix/share/libquvi-scripts/$major_ver.$minor_ver/media/

### Playlist scripts
The playlist scripts are responsible for parsing the playlist properties. There is usually a playlist script for each supported website.

These scripts are typically installed at

$prefix/share/libquvi-scripts/$major_ver.$minor_ver/playlist/

### Scan scripts
The scan scripts are used to scan an URL for embedded media URLs.

These scripts are typically installed at

$prefix/share/libquvi-scripts/$major_ver.$minor_ver/scan/

### Subtitlte scripts
The subtitle scripts are responsible for retrieving subtitle data for the media as well as exporting the data to another format, e.g. SubRip.

These scripts are typically installed at

$prefix/share/libquvi-scripts/$major_ver.$minor_ver/subtitle/ $prefix/share/libquvi-scripts/$major_ver.$minor_ver/subtitle/export/

### Utility scripts
The utility scripts are used by libquvi to perform misc. tasks, such as parsing file extension from a content-type, or converting HTML entities to UTF-8 characters.

These scripts are typically installed at

$prefix/share/libquvi-scripts/$major_ver.$minor_ver/util/

## ENVIRONMENT
LIBQUVI_SCRIPTS_VERBOSE

When defined, enables the output from any libquvi scripts using the debug facility (quvi/debug module).

## SEE ALSO
libquvi(3), quvi(1)

## FURTHER RESOURCES
Home

http://quvi.sourceforge.net/

Development code

git://repo.or.cz/libquvi-scripts.git

gitweb

http://repo.or.cz/w/libquvi-scripts.git

## AUTHORS
Toni Gundogdu <legatvs@gmail.com>

Author.

## REPORTING BUGS
Report bugs to the quvi-devel mailing list <quvi-devel@lists.sourceforge.net> where the development and the maintenance is primarily done. You do not have to be subscribed to the list to send a message there.

## LICENSE
libquvi-scripts is Free Software licensed under the GNU Affero GPLv3+

## LIBQUVI-SCRIPTS
Part of the libquvi-scripts(7) suite


quvi-modules

title: quvi-modules(7)

summary: Overview of the loadable quvi modules

text:
# quvi-modules(7)

## NAME
quvi-modules - Overview of the loadable quvi modules

## DESCRIPTION
quvi-modules are a selection of importable modules implemented in Lua. These modules are intended to be loaded (require) from the libquvi-scripts(7).

Many of the modules are documented within the code. Refer to the individual modules for their detailed description of different available functions.

The modules are usually installed at

$prefix/share/libquvi-scripts/$major_ver.$minor_ver/common/quvi/

## MODULES
quvi/http/cookie

A set of functions that wrap most of the quvi.http.cookie function features. See quvi-object(7).

quvi/const

Constants. Technically, (due to Lua language specification) these are not immutable values. The constants are used to interact with libquvi, e.g. specifying function operation modes and checking for returned libquvi return codes.

quvi/debug

An message output facility intended to be used for debugging purposes. By default, all output from scripts using this facility remain disabled. To enable the output, define the LIBQUVI_SCRIPTS_VERBOSE environment variable.

quvi/entity

HTML entity conversion module. Converts the standard HTML entities (to ASCII), and any numeric HTML entities to UTF-8 (using the quvi/html module).

quvi/hash

Wrapper functions for some of the common hash (message digest) functions provided by the quvi-object(7). Note that these functions convert the given data into hexadecimal form before passing it to the hash functions.

quvi/hex

Functions for converting values from and to hexadecimal form. These are typically used together with the quvi-object(7) crypto functions.

quvi/html

Converts numeric HTML entities to UTF-8. See also quvi/entity, which uses this module.

quvi/lxph

LuaExpat wrapper/utility functions for parsing XML, see also quvi-modules-3rdparty(7).

quvi/stream

Media stream related functions.

quvi/time

Time related functions.

quvi/util

Misc. utility functions.

quvi/youtube

Functions common to YouTube.

## SEE ALSO
libquvi-scripts(7), libquvi(3), quvi-object(7), quvi-modules-3rdparty(7)

## FURTHER RESOURCES
Home

http://quvi.sourceforge.net/

Development code

git://repo.or.cz/libquvi-scripts.git

gitweb

http://repo.or.cz/w/libquvi-scripts.git

## AUTHORS
Toni Gundogdu <legatvs@gmail.com>

Author.

## REPORTING BUGS
Report bugs to the quvi-devel mailing list <quvi-devel@lists.sourceforge.net> where the development and the maintenance is primarily done. You do not have to be subscribed to the list to send a message there.

## LICENSE
libquvi-scripts is Free Software licensed under the GNU Affero GPLv3+

## LIBQUVI-SCRIPTS
Part of the libquvi-scripts(7) suite


title: quvi-modules-3rdparty(7)

text:
# quvi-modules-3rdparty(7)

## NAME
quvi-modules-3rdparty - Overview of the loadable 3rd party modules

## DESCRIPTION
This is a brief list of the loadable 3rd party modules that the the libquvi-scripts(7) use. For more information about these modules, refer to their corresponding reference documentation.

## 3RD PARTY MODULES
LuaBitOp

Lua BitOp is a C extension module for Lua 5.1/5.2 which adds bitwise operations on numbers. http://bitop.luajit.org/

LuaExpat

LuaExpat is a SAX XML parser based on the Expat library. http://matthewwild.co.uk/projects/luaexpat/

LuaJSON

JSON parser/encoder for Lua, parses JSON using LPEG for speed and flexibility. http://www.eharning.us/wiki/luajson/

LuaSocket

LuaSocket is a Lua extension library that is composed by two parts: a C core that provides support for the TCP and UDP transport layers, and a set of Lua modules that add support for functionality commonly needed by applications that deal with the Internet. http://w3.impa.br/~diego/software/luasocket/

## SEE ALSO
libquvi-scripts(7), libquvi(3), quvi-object(7), quvi-modules(7)

## FURTHER RESOURCES
Home

http://quvi.sourceforge.net/

Development code

git://repo.or.cz/libquvi-scripts.git

gitweb

http://repo.or.cz/w/libquvi-scripts.git

## AUTHORS
Toni Gundogdu <legatvs@gmail.com>

Author.

## REPORTING BUGS
Report bugs to the quvi-devel mailing list <quvi-devel@lists.sourceforge.net> where the development and the maintenance is primarily done. You do not have to be subscribed to the list to send a message there.

## LICENSE
libquvi-scripts is Free Software licensed under the GNU Affero GPLv3+

## LIBQUVI-SCRIPTS
Part of the libquvi-scripts(7) suite


rsocket

package: librdmacm

title: rsocket(7)

summary: RDMA socket API

text:
# rsocket(7)

## NAME
rsocket - RDMA socket API

## SYNOPSIS
\#include <rdma/rsocket.h>

## DESCRIPTION
RDMA socket API and protocol

## NOTES
Rsockets is a protocol over RDMA that supports a socket-level API for applications. Rsocket APIs are intended to match the behavior of corresponding socket calls, except where noted. Rsocket functions match the name and function signature of socket calls, with the exception that all function calls are prefixed with an 'r'.

The following functions are defined:

rsocket

rbind, rlisten, raccept, rconnect

rshutdown, rclose

rrecv, rrecvfrom, rrecvmsg, rread, rreadv

rsend, rsendto, rsendmsg, rwrite, rwritev

rpoll, rselect

rgetpeername, rgetsockname

rsetsockopt, rgetsockopt, rfcntl

Functions take the same parameters as that used for sockets. The follow capabilities and flags are supported at this time:

PF_INET, PF_INET6, SOCK_STREAM, SOCK_DGRAM

SOL_SOCKET - SO_ERROR, SO_KEEPALIVE (flag supported, but ignored), SO_LINGER, SO_OOBINLINE, SO_RCVBUF, SO_REUSEADDR, SO_SNDBUF

IPPROTO_TCP - TCP_NODELAY, TCP_MAXSEG

IPPROTO_IPV6 - IPV6_V6ONLY

MSG_DONTWAIT, MSG_PEEK, O_NONBLOCK

Rsockets provides extensions beyond normal socket routines that allow for direct placement of data into an application's buffer. This is also known as zero-copy support, since data is sent and received directly, bypassing copies into network controlled buffers. The following calls and options support direct data placement.

riomap, riounmap, riowrite

off_t riomap(int socket, void *buf, size_t len, int prot, int flags, off_t offset)

Riomap registers an application buffer with the RDMA hardware

associated with an rsocket. The buffer is registered either for local only access (PROT_NONE) or for remote write access (PROT_WRITE). When registered for remote access, the buffer is mapped to a given offset. The offset is either provided by the user, or if the user selects -1 for the offset, rsockets selects one. The remote peer may access an iomapped buffer directly by specifying the correct offset. The mapping is not guaranteed to be available until after the remote peer receives a data transfer initiated after riomap has completed.

In order to enable the use of remote IO mapping calls on an rsocket, an application must set the number of IO mappings that are available to the remote peer. This may be done using the rsetsockopt RDMA_IOMAPSIZE option. By default, an rsocket does not support remote IO mappings. riounmap

int riounmap(int socket, void *buf, size_t len)

Riounmap removes the mapping between a buffer and an rsocket.

riowrite

size_t riowrite(int socket, const void *buf, size_t count, off_t offset, int flags)

Riowrite allows an application to transfer data over an rsocket

directly into a remotely iomapped buffer. The remote buffer is specified through an offset parameter, which corresponds to a remote iomapped buffer. From the sender's perspective, riowrite behaves similar to rwrite. From a receiver's view, riowrite transfers are silently redirected into a pre- determined data buffer. Data is received automatically, and the receiver is not informed of the transfer. However, iowrite data is still considered part of the data stream, such that iowrite data will be written before a subsequent transfer is received. A message sent immediately after initiating an iowrite may be used to notify the receiver of the iowrite.

In addition to standard socket options, rsockets supports options specific to RDMA devices and protocols. These options are accessible through rsetsockopt using SOL_RDMA option level.

RDMA_SQSIZE - Integer size of the underlying send queue.

RDMA_RQSIZE - Integer size of the underlying receive queue.

RDMA_INLINE - Integer size of inline data.

RDMA_IOMAPSIZE - Integer number of remote IO mappings supported

RDMA_ROUTE - struct ibv_path_data of path record for connection.

Note that rsockets fd's cannot be passed into non-rsocket calls. For applications which must mix rsocket fd's with standard socket fd's or opened files, rpoll and rselect support polling both rsockets and normal fd's.

Existing applications can make use of rsockets through the use of a preload library. Because rsockets implements an end-to-end protocol, both sides of a connection must use rsockets. The rdma_cm library provides such a preload library, librspreload. To reduce the chance of the preload library intercepting calls without the user's explicit knowledge, the librspreload library is installed into %libdir%/rsocket subdirectory.

The preload library can be used by setting LD_PRELOAD when running. Note that not all applications will work with rsockets. Support is limited based on the socket options used by the application. Support for fork() is limited, but available. To use rsockets with the preload library for applications that call fork, users must set the environment variable RDMAV_FORK_SAFE=1 on both the client and server side of the connection. In general, fork is supportable for server applications that accept a connection, then fork off a process to handle the new connection.

rsockets uses configuration files that give an administrator control over the default settings used by rsockets. Use files under /etc/rdma/rsocket as shown:

mem_default - default size of receive buffer(s)

wmem_default - default size of send buffer(s)

sqsize_default - default size of send queue

rqsize_default - default size of receive queue

inline_default - default size of inline data

iomap_size - default size of remote iomapping table

polling_time - default number of microseconds to poll for data before waiting

wake_up_interval - maximum number of milliseconds to block in poll. This value is used to safe guard against potential application hangs in rpoll().

All configuration files should contain a single integer value. Values may be set by issuing a command similar to the following example.

echo 1000000 > /etc/rdma/rsocket/mem_default

If configuration files are not available, rsockets uses internal defaults. Applications can override default values programmatically through the rsetsockopt routine.

## SEE ALSO
rdma_cm(7)


libsmbclient

package: libsmbclient-devel

title: libsmbclient(7)

text:
# libsmbclient(7)

## NAME
libsmbclient - An extension library for browsers and that can be used as a generic browsing API.

## SYNOPSIS
Browser URL: smb://[[[domain:]user[:password@]]server[/share[/path[/file]]]] [?options]

## DESCRIPTION
This tool is part of the samba(7) suite.

libsmbclient is a library toolset that permits applications to manipulate CIFS/SMB network resources using many of the standards POSIX functions available for manipulating local UNIX/Linux files. It permits much more than just browsing, files can be opened and read or written, permissions changed, file times modified, attributes and ACL's can be manipulated, and so on. Of course, its functionality includes all the capabilities commonly called browsing.

libsmbclient can not be used directly from the command line, instead it provides an extension of the capabilities of tools such as file managers and browsers. This man page describes the configuration options for this tool so that the user may obtain greatest utility of use.

## OPTIONS
What the URLs mean:

smb://

Shows all workgroups or domains that are visible in the network. The behavior matches that of the Microsoft Windows Explorer. The method of locating the list of workgroups (domains also) varies depending on the setting of the context variable (context->options.browse_max_lmb_count). It is the responsibility of the application that calls this library to set this to a sensible value. This is a compile-time option. This value determines the maximum number of local master browsers to query for the list of workgroups. In order to ensure that the list is complete for those present on the network, all master browsers must be queried. If there are a large number of workgroups on the network, the time spent querying will be significant. For small networks (just a few workgroups), it is suggested to set this value to 0, instructing libsmbclient to query all local master browsers. In an environment that has many workgroups a more reasonable setting may be around 3.

smb://name/

This command causes libsmbclient to perform a name look-up. If the NAME<1D> or NAME<1B> exists (workgroup name), libsmbclient will list all servers in the workgroup (or domain). Otherwise, a name look-up for the NAME<20> (machine name) will be performed, and the list of shared resources on the server will be displayed.

When libsmbclient is invoked by an application it searches for a directory called .smb in the $HOME directory that is specified in the users shell environment. It then searches for a file called smb.conf which, if present, will fully over-ride the system /etc/samba/smb.conf file. If instead libsmbclient finds a file called ~/.smb/smb.conf.append, it will read the system /etc/samba/smb.conf and then append the contents of the ~/.smb/smb.conf.append to it.

libsmbclient will check the users shell environment for the USER parameter and will use its value when if the user parameter was not included in the URL.

## PROGRAMMERS GUIDE
Watch this space for future updates.

## VERSION
This man page is part of version 4.22.10-alt1 of the Samba suite.

## AUTHOR
The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed.

The libsmbclient manpage page was written by John H Terpstra.


termkey

package: libtermkey

title: termkey(7)

summary: terminal keypress reading library

text:
# termkey(7)

## NAME
termkey - terminal keypress reading library

## DESCRIPTION
termkey is a library that allows programs to read and interpret keypress and other events from a terminal. It understands encoding schemes used by terminals to encode keypresses, and UTF-8 , allowing it to return events representing key events.

termkey operates in a pseudo object-oriented fashion. It provides one function, termkey_new(3), that returns a pointer to a newly-allocated structure. All other functions take this pointer as their first argument. A typical use of this library would consist of a call to termkey_new() to construct a new instance to represent the stdin stream, then use the termkey_waitkey(3) function to wait for and interpret key press events. The termkey_destroy(3) function can be used to deallocate resources used by the instance if the program has finished using it.

### Reading Events
Each instance of a termkey structure may be used in one of three ways by the program. It may be used synchronously, blocking to wait for keypresses from a filehandle. It may be used asynchronously, returning keypresses if they are available, while co-operating with a non-blocking program. Or it may be used abstractly, interpreting key press bytes fed to it directly by the containing program.

To obtain the next key event synchronously, a program may call termkey_waitkey(3). This will either return an event from its internal buffer, or block until a key is available, returning it when it is ready. It behaves similarly to getc(3), fgetc(3), or similar, except that it understands and returns entire key press events, rather than single bytes.

To work with an asynchronous program, two other functions are used. termkey_advisereadable(3) informs a termkey instance that more bytes of input may be available from its file handle, so it should call read(2) to obtain them. The program can then call termkey_getkey(3) to extract key press events out of the internal buffer, in a way similar to termkey_waitkey().

Finally, bytes of input can be fed into the termkey instance directly, by calling termkey_push_bytes(3). This may be useful if the bytes have already been read from the terminal by the application, or even in situations that don't directly involve a terminal filehandle. Because of these situations, it is possible to construct a termkey instance not associated with a file handle, by passing -1 as the file descriptor.

A termkey instance contains a buffer of pending bytes that have been read but not yet consumed by termkey_getkey(3). termkey_get_buffer_remaining(3) returns the number of bytes of buffer space currently free in the instance. termkey_set_buffer_size(3) and termkey_get_buffer_size(3) can be used to control and return the total size of this buffer.

### Key Events
Key events are stored in structures. Each structure holds details of one key event. This structure is defined as follows.

```
typedef struct {

    TermKeyType type;

    union {

        long       codepoint; /* TERMKEY_TYPE_UNICODE  */

        int        number;    /* TERMKEY_TYPE_FUNCTION */

        TermKeySym sym;       /* TERMKEY_TYPE_KEYSYM   */

    } code;

    int modifiers;

    char utf8[7];
} TermKeyKey;
```

The type field indicates the type of event, and determines which of the members of the code union is valid. It will be one of the following constants:

TERMKEY_TYPE_UNICODE

a Unicode codepoint. This value indicates that code.codepoint is valid, and will contain the codepoint number of the keypress. In Unicode mode (if the TERMKEY_FLAG_UTF8 bit is set) this will be its Unicode character number. In raw byte mode, this will contain a single 8-bit byte.

TERMKEY_TYPE_FUNCTION

a numbered function key. This value indicates that code.number is valid, and contains the number of the numbered function key.

TERMKEY_TYPE_KEYSYM

a symbolic key. This value indicates that code.sym is valid, and contains the symbolic key value.

TERMKEY_TYPE_MOUSE

a mouse button press, release, or movement. The code structure should be considered opaque; termkey_interpret_mouse(3) may be used to interpret it.

TERMKEY_TYPE_POSITION

a cursor position report. The code structure should be considered opaque; termkey_interpret_position(3) may be used to interpret it.

TERMKEY_TYPE_MODEREPORT

an ANSI or DEC mode value report. The code structure should be considered opaque; termkey_interpret_modereport(3) may be used to interpret it.

TERMKEY_TYPE_DCS

a DCS sequence including its terminator. The code structure should be considered opaque; termkey_interpret_string(3) may be used to interpret it.

TERMKEY_TYPE_OSC

a OSC sequence including its terminator. The code structure should be considered opaque; termkey_interpret_string(3) may be used to interpret it.

TERMKEY_TYPE_UNKNOWN_CSI

an unrecognised CSI sequence. The code structure should be considered opaque; termkey_interpret_csi(3) may be used to interpret it.

The modifiers bitmask is composed of a bitwise-or of the constants TERMKEY_KEYMOD_SHIFT, TERMKEY_KEYMOD_CTRL and TERMKEY_KEYMOD_ALT.

The utf8 field is only set on events whose type is TERMKEY_TYPE_UNICODE. It should not be read for other events.

Key events that represent special keys (type is TERMKEY_TYPE_KEYSYM) have with them as symbolic value that identifies the special key, in code.sym. termkey_get_keyname(3) may be used to turn this symbolic value into a string, and termkey_lookup_keyname(3) may be used to turn string names into symbolic values.

A pair of functions are also provided to convert between key events and strings. termkey_strfkey(3) converts a key event into a string, and termkey_strpkey(3) parses a string turning it into a key event.

Key events may be compared for equallity or ordering by using termkey_keycmp(3).

### Control Flags
Details of the behaviour of a termkey instance are controlled by two bitmasks of flags. termkey_set_flags(3) and termkey_get_flags(3) set or return the flags used to control the general behaviour, and termkey_set_canonflags(3) and termkey_get_canonflags(3) set or return the flags that control the key value canonicalisation behaviour performed by termkey_canonicalise(3).

The following control flags are recognised.

TERMKEY_FLAG_NOINTERPRET

Do not attempt to interpret C0 codes into keysyms. Instead report them as plain Ctrl-letter events.

TERMKEY_FLAG_CONVERTKP

Convert xterm's alternative keypad symbols into the plain ASCII codes they would represent.

TERMKEY_FLAG_RAW

Ignore locale settings; do not attempt to recombine UTF-8 sequences. Instead report only raw values.

TERMKEY_FLAG_UTF8

Ignore locale settings; force UTF-8 recombining on. This flag overrides TERMKEY_FLAG_RAW.

TERMKEY_FLAG_NOTERMIOS

Even if the terminal file descriptor fd represents a TTY device, do not call the tcsetattr(3) termios function on it to set it to canonical input mode.

TERMKEY_FLAG_SPACESYMBOL

Report space as being a symbolic key rather than a Unicode codepoint. Setting or clearing this flag in fact sets or clears the TERMKEY_CANON_SPACESYMBOL canonicalisation flag.

TERMKEY_FLAG_CTRLC

Disable the SIGINT behaviour of Ctrl-C. If this flag is provided, then Ctrl-C will be available as a normal keypress, rather than sending the process group a SIGINT. This flag only takes effect without TERMKEY_FLAG_NOTERMIOS; with it, none of the signal keys are disabled anyway.

TERMKEY_FLAG_EINTR

Without this flag, IO operations are retried when interrupted by a signal (EINTR). With this flag the TERMKEY_RES_ERROR result is returned instead.

TERMKEY_FLAG_NOSTART

This flag is only meaningful to the constructor functions termkey_new(3) and termkey_new_abstract(3). If set, the constructor will not call termkey_start(3) as part of the construction process. The user must call that at some future time before the instance will be usable.

The following canonicalisation flags are recognised.

TERMKEY_CANON_SPACESYMBOL

If this flag is set then a Unicode space character is represented using the TERMKEY_SYM_SPACE symbol. If this flag is not set, it is represented by the U+0020 Unicode codepoint.

TERMKEY_CANON_DELBS

If this flag is set then an ASCII DEL character is represented by the TERMKEY_SYM_BACKSPACE symbol. If not, it is represented by TERMKEY_SYM_DEL. An ASCII BS character is always represented by TERMKEY_SYM_BACKSPACE, regardless of this flag.

### Multi-byte Events
Special keys, mouse events, and UTF-8 encoded Unicode text, are all represented by more than one byte. If the start of a multi-byte sequence is seen by termkey_waitkey() it will wait a short time to see if the remainder of the sequence arrives. If the sequence remains unfinished after this timeout, it will be returned in its incomplete state. Partial escape sequences are returned as an Escape key (TERMKEY_SYM_ESCAPE) followed by the text contained in the sequence. Partial UTF-8 sequences are returned as the Unicode replacement character, U+FFFD.

The amount of time that the termkey instance will wait is set by termkey_set_waittime(3), and is returned by termkey_get_waittime(3). Initially it will be set to 50 miliseconds.

### Mouse Events
The TERMKEY_TYPE_MOUSE event type indicates a mouse event. The code field of the event structure should be considered opaque, though modifiers will be valid. In order to obtain the details of the mouse event, call termkey_interpret_mouse(3) passing the event structure and pointers to integers to store the result in.

termkey recognises three mouse protocols: the original X10 protocol (CSI M followed by three bytes), SGR encoding (CSI < ... M, as requested by CSI ? 1006 h), and rxvt encoding (CSI ... M, as requested by CSI ? 1015 h). Which encoding is in use is inferred automatically by termkey, and does not need to be specified explicitly.

### Position Events
The TERMKEY_TYPE_POSITION event type indicates a cursor position report. This is typically sent by a terminal in response to the Report Cursor Position command (CSI ? 6 n). The event bytes are opaque, but can be obtained by calling termkey_interpret_position(3) passing the event structure and pointers to integers to store the result in. Note that only a DEC CPR sequence (CSI ? R) is recognised, and not the non-DEC prefixed CSI R because the latter could be interpreted as the F3 function key instead.

### Mode Reports
The TERMKEY_TYPE_MODEREPORT event type indicates an ANSI or DEC mode report. This is typically sent by a terminal in response to the Request Mode command (CSI $p or CSI ? $p). The event bytes are opaque, but can be obtained by calling termkey_interpret_modereport(3) passing the event structure and pointers to integers to store the result in.

### Control Strings
The TERMKEY_TYPE_DCS and TERMKEY_TYPE_OSC event types indicate a DCS or OSC control string. These are typically sent by the terminal in response of similar kinds of strings being sent as queries by the application. The event bytes are opaque, but the body of the string itself can be obtained by calling termkey_interpret_string(3) immediately after this event is received. The underlying termkey instance itself can only store one pending string, so the application should be sure to call this function in a timely manner soon after the event is received; at the very least, before calling any other functions that will insert bytes into or remove key events from the instance.

### Unrecognised CSIs
The TERMKEY_TYPE_UNKNOWN_CSI event type indicates a CSI sequence that the termkey does not recognise. It will have been extracted from the stream, but is available to the application to inspect by calling termkey_interpret_csi(3). It is important that if the application wishes to inspect this sequence it is done immediately, before any other IO operations on the termkey instance (specifically, before calling termkey_waitkey() or termkey_getkey() again), otherwise the buffer space consumed by the sequence will be overwritten. Other types of key event do not suffer this limitation as the TermKeyKey structure is sufficient to contain all the information required.

## SEE ALSO
termkey_new(3), termkey_waitkey(3), termkey_getkey(3)


tickit

package: libtickit-devel

title: tickit(7)

summary: Terminal Interface Construction KIT

text:
# tickit(7)

## NAME
tickit - Terminal Interface Construction KIT

## SYNOPSIS

```
#include <tickit.h>

typedef struct Tickit;
```

## DESCRIPTION
tickit is a library for building full-screen interactive programs that use a terminal interface. A program using this library would start by creating a toplevel Tickit instance, from which one or more divisions of the terminal area, called "windows" are created. These form a heirarchial tree that subdivides the content area into independent regions that can be managed by different parts of the program structure. Each window can react to input events such as keyboard or mouse interaction.

As well as creating the initial root window, the toplevel Tickit instance also performs a few other jobs for the containing program. It can act as a containing event loop for the program, performing IO multiplexing tasks both for tickit's own needs and the needs of the program as a whole.

## FUNCTIONS
A new toplevel instance is created by using tickit_build(3), tickit_new_stdio(3) or tickit_new_stdtty(3). A toplevel instance stores a reference count to make it easier for applications to manage its lifetime. A new toplevel instance starts with a count of one, and it can be adjusted using tickit_ref(3) and tickit_unref(3). When the count reaches zero the instance is destroyed.

The toplevel instance manages a tree of TickitWindow instances. The root of this tree is obtained by tickit_get_rootwin(3) and thereafter can be divided further by other functions on the window, described more in tickit_window(7).

The TickitTerm instance behind the toplevel instance can be obtained by tickit_get_term(3), and is described more in tickit_term(7).

Event handling callback functions can be installed to be called at a later time, by using tickit_watch_io(3), tickit_watch_timer_after_msec(3), tickit_watch_timer_after_tv(3), tickit_watch_later(3), tickit_watch_signal(3) or tickit_watch_process(3). The main IO event loop is controlled using tickit_run(3) and tickit_stop(3).

The compile-time and run-time version of the library can be inspected using the macros and functions described in tickit_version(7).

## TYPICAL STRUCTURE
A typical program using this library would start by creating the toplevel instance, by calling tickit_new_stdtty(3), then obtain its root window on it by calling tickit_get_rootwin(3). This root window can then be sub-divided into regions of interest by calling tickit_window_new(3) to build a tree of windows. Window can then have some event handlers attached by calling tickit_window_bind_event(3) - each window will need to handle the TICKIT_WINDOW_ON_EXPOSE event, but might also wish to handle other kinds like geometry change for dynamic resizing, or keyboard or mouse to react to user input. Finally, once the initial window tree is created, the program would enter the main event loop by invoking tickit_run(3).

## COMMON TYPES
The flags argument to the various tickit_..._bind_event() functions should be zero, or a bitmask of the following constants.

```
typedef enum {
  TICKIT_BIND_FIRST,
  TICKIT_BIND_UNBIND,
  TICKIT_BIND_DESTROY,
  TICKIT_BIND_ONESHOT,
} TickitBindFlags;
```

TICKIT_BIND_FIRST indicates that this handler should be inserted at the start of the list, rather than the default position at the end.

TICKIT_BIND_UNBIND indicates that this handler should also be invoked at the time it is unbound, either due to a specific call to the tickit_..._unbind_event() function, or because the bound object is being destroyed.

TICKIT_BIND_DESTROY indicates that this handler should also be invoked at the time that the bound object is being destroyed.

TICKIT_BIND_ONESHOT indicates that the handler should be invoke at-most once, and unbound the first time it is invoked. When invoked it will receive both the TICKIT_EV_FIRE and TICKIT_EV_UNBIND flags at once.

Some API functions take or return the following enum type, to represent a tri-state extended boolean concept of true, false, or some third condition typically indicating a "don't care" or "unknown" state; the exact semantics will vary between specific uses and should be documented specifically.

```
typedef enum {
  TICKIT_YES = 1,
  TICKIT_NO = 0,
  TICKIT_MAYBE = -1,
} TickitMaybeBool;
```

The various tickit_*ctl_type() and tickit_pen_attrtype(3) functions return the following enum type, to indicate what type of value each individual control or attribute takes.

```
typedef enum {
  TICKIT_TYPE_NONE,
  TICKIT_TYPE_BOOL,
  TICKIT_TYPE_INT,
  TICKIT_TYPE_COLOUR,
} TickitType;
```

## COMMON EVENTS
Every object instance that supports events supports the following type of event, in addition to the specific ones listed for that kind of object:

TICKIT_..._ON_DESTROY

Invoked when the object instance is being destroyed. This will be the last time the application can use the stored data argument; it may perform any resource reclaiming operations that are required at this time.

## EVENT FLAGS
When an event handler function is invoked, it is passed a bitmask of flags to indicate the reason for its invocation.

```
typedef enum {
  TICKIT_EV_FIRE,
  TICKIT_EV_UNBIND,
  TICKIT_EV_DESTROY,
} TickitEventFlags;
```

TICKIT_EV_FIRE

This handler is being invoked because its associated event has occurred. The info pointer will point to a structure containing the relevant information.

TICKIT_EV_UNBIND

This handler is being invoked because it is being removed from the object. This will only be observed if it was bound with the TICKIT_BIND_UNBIND flag. The info pointer will be NULL.

TICKIT_EV_DESTROY

This handler is being invoked because the object instance itself is being destroyed. This will be observed if it was bound with the TICKIT_BIND_DESTROY flag, or because it is bound to the TICKIT_..._ON_DESTROY event. The info pointer will be NULL.

Any event handlers for this event will be invoked in reverse order; the newest is run first and the oldest last.

## CONTROLS
A toplevel instance has a number of runtime-configuration control options that affect its behaviour. These can be set using tickit_setctl_int(3), and queried using tickit_getctl_int(3). The individual controls have human-readable string names that can be obtained by tickit_ctl_name(3) and searched by name using tickit_ctl_lookup(3). The type of a control option can be queried using tickit_ctl_type(3).

The options are given in an enumeration called TickitCtl. The following control values are recognised:

TICKIT_CTL_USE_ALTSCREEN (bool)

The value is a boolean indicating whether the instance will activate the terminal alternate screen buffer mode when started.

## SEE ALSO
tickit_window(7), tickit_term(7), tickit_pen(7), tickit_rect(7), tickit_rectset(7), tickit_renderbuffer(7), tickit_string(7), tickit_utf8_count(3), tickit_version(7)


title: tickit_debug(7)

summary: debug logging support for libtickit

text:
# tickit_debug(7)

## NAME
Tickit_Debug - debug logging support for libtickit

## SYNOPSIS

```
$ TICKIT_DEBUG_FLAGS=W TICKIT_DEBUG_FILE=tickit.log a-tickit-program
```

## DESCRIPTION
The libtickit library contains a debug logging system that other parts of the library use to report on interesting events and behaviours, that may help developers to observe internal details and assist in the development and debugging of applications that use the library.

Debug messages themselves each have a flag name, which is a short string identifying the library component or event that caused that message. A given set of these flags can be enabled during a debugging session, causing only those messages to be printed. Messages pertaining to flags that are not enabled will not be printed.

## FLAGS
Each flag name starts with an upper-case letter indicating the library component it relates to, then lower-case letters to indicate the particular kind of event or message within that component.

### B
These messages relate to TickitRenderBuffer (tickit_renderbuffer(7)).

Bd

Drawing operations such as tickit_renderbuffer_text(3).

Bf

Flushing

Bs

Stack state save and restore.

Bt

### I
These messages relate to input-system events.

Ik

Keyboard keypresses.

Im

Mouse movement and button or wheel events.

Ir

Terminal resize. Transformations (translation, clipping and masking).

### W
These messages relate to windows.

W*

Window destroyed.

Wd

Damage to root window.

Wx

Window is exposed.

Wh

Window hierarchy changed.

Ws

Window scrolls.

Wsr

Window propagates a scrollrect to its underlying terminal.

## ENVIRONMENT
The debugging support is controlled by the following environment variables, which should be set before the application starts, or early during its initialisation before it has invoked any libtickit functions.

TICKIT_DEBUG_FLAGS

A comma-separated list of the flags or flag categories to enable for printing. Entire categories of flags can be enabled by list just the initial capital letter of its name. All the flags can be enabled at once by setting the name *.

TICKIT_DEBUG_FILE

Gives the name of a file to open in append mode to write logging lines to.

TICKIT_DEBUG_FD

Gives a file descriptor number to write logging lines to.

One technique that may be useful to observe logging in real-time while the application runs is to arrange for the application to run in a new terminal but have it log debugging output to an existing one. This may be achieved using

```
$ TICKIT_DEBUG_FD=3 TICKIT_DEBUG_FLAGS=... $TERM my-tickit-app 3>&2
```

This requests that libtickit log to file descriptor 3, which has been created by dup(2)ing the original shell's standard output. Debug logging will therefore be printed to the existing terminal where this command was executed, while the application itself draws its output to the newly-created one.

## FUNCTIONS
The debug system is initialised by calling tickit_debug_init(3). Messages can be logged using tickit_debug_logf(3) and tickit_debug_vlogf(3).

## SEE ALSO
tickit(7), tickit_term(7), tickit_renderbuffer(7), tickit_window(7)


title: tickit_pen(7)

text:
# tickit_pen(7)

## NAME
TickitPen - store a collection of terminal rendering attributes

## SYNOPSIS

```
#include <tickit.h>

typedef struct TickitPen;
```

## DESCRIPTION
A TickitPen instance stores a collection of terminal rendering attributes. For each known attribute, a pen instance may store a value for this attribute. A pen instance is used in the tickit_term_chpen(3) and tickit_term_setpen(3) functions.

## FUNCTIONS
A new TickitPen instance is created using the tickit_pen_new(3) function. A pen instance stores a reference count to make it easier for applications to manage the lifetime of pens. A new pen starts with a count of one, and it can be adjusted using tickit_pen_ref(3) and tickit_pen_unref(3). When the count reaches zero the instance is destroyed.

## ATTRIBUTES
The TickitPenAttr enumeration lists the attributes known by a pen. Each attribute has a type, as given by the TickitPenAttrType enumeration. The tickit_penattr_type(3) function gives the type of a given attribute. The tickit_penattr_name(3) function gives the name of a given attribute, which is also given below in parentheses. The tickit_penattr_lookup(3) function looks up an attribute constant from a string containing the name.

TICKIT_PEN_FG ("fg"), TICKIT_PEN_BG ("bg")

foreground and background colours. These are of type TICKIT_PENTYPE_COLOUR. This gives an integer from 0 to 255 to use as the colour index. It may also be set to the value -1, which sets the terminal's default, which may be a colour distinct from any of the others. Some terminals may not support more than 8 or 16 colours, however. When setting a pen colour on a terminal, it may be converted to one that is supported by the terminal tickit_term_setpen(3) or tickit_term_chpen(3) functions.

These colour attributes also support a secondary RGB8 (24-bit) specification, which some terminal drivers may prefer over the indexed version.

TICKIT_PEN_BOLD ("b"), TICKIT_PEN_ITALIC ("i"), TICKIT_PEN_REVERSE ("rv"), TICKIT_PEN_STRIKE ("strike"), TICKIT_PEN_BLINK ("blink")

boolean rendering attributes. These are of type TICKIT_PENTYPE_BOOL. They are either true or false. Most terminals should support at least bold, underline, reverse and blink, though italic and strikethrough are less commonly supported. Applications are advised not to use these two alone to distinguish significant parts of the user interface.

TICKIT_PEN_UNDER ("u")

underline. This is of type TICKIT_PENTYPE_INT. Its value is one of the values from the TickitPenUnderline enumeration. Most terminals should support the single underline value, however other values are less commonly supported, and may be drawn instead as a single underline. Applications are advised not to make use of underline style alone to distinguish significant parts of the user interface.

Valid values are:

TICKIT_PEN_UNDER_NONE

No underline.

TICKIT_PEN_UNDER_SINGLE

Single underline.

TICKIT_PEN_UNDER_DOUBLE

Double underline.

TICKIT_PEN_UNDER_WAVY

Single wavy underline, sometimes called "undercurl".

For backward-compatibility this attribute will also behave like a boolean-typed attribute. When set to any value other than none, it appears true as a boolean. Setting it to true as a booelan will set its value to single.

TICKIT_PEN_ALTFONT ("af")

alternate font index. This is of type TICKIT_PENTYPE_INT. It is a value 0 to 9, which selects from the terminal's available fonts. Few terminals actually support this in practice.

## FUNCTIONS
The values of attributes are set or queried on a pen instance by using functions depending on the type of the attribute. Boolean attributes use tickit_pen_set_bool_attr(3) and tickit_pen_get_bool_attr(3). Integer attributes use tickit_pen_set_int_attr(3) and tickit_pen_get_int_attr(3). Colour attributes use tickit_pen_set_colour_attr(3), tickit_pen_set_colour_attr_desc(3) and tickit_pen_get_colour_attr(3). The RGB8 secondary field for colours can be set with tickit_pen_set_colour_attr_rgb8(3), and queried with tickit_pen_has_colour_attr_rgb8(3) and tickit_pen_get_colour_attr_rgb8(3).

To test if an attribute has a value set, use tickit_pen_has_attr(3), and to remove the attribute entirely use tickit_pen_clear_attr(3). To test if a pen has any attributes set at all, use tickit_pen_is_nonempty(3), and to test if it has any attributes set to a non-default value use tickit_pen_is_nondefault(3). To remove all the attributes use tickit_pen_clear(3). To copy the value of one attribute from a pen into another pen use tickit_pen_copy_attr(3), to copy the entire pen use tickit_pen_copy(3), and to compare two pens for equality use tickit_pen_equiv_attr(3).

## EVENTS
A pen instance stores a list of event handlers. Each event handler is associated with one event type and stores a function pointer, and an arbitrary pointer containing user data. Event handlers may be installed using tickit_pen_bind_event(3) and removed using tickit_pen_unbind_event_id(3).

The event types recognised are:

TICKIT_PEN_ON_DESTROY

The pen instance is being destroyed.

TICKIT_PEN_ON_CHANGE

The stored attributes on the pen have changed. The info pointer will be NULL.


title: tickit_rect(7)

text:
# tickit_rect(7)

## NAME
TickitRect - utility structure representing a rectangular region

## SYNOPSIS

```
#include <tickit.h>

typedef struct {
  int top;
  int left;
  int lines;
  int cols;
} TickitRect;
```

## DESCRIPTION
A TickitRect structure represents a single non-empty rectangular region of the screen. It stores the position of the top left corner of the region, and its size in lines and columns.

## FUNCTIONS
A new TickitRect structure can be initialised using the tickit_rect_init_sized(3) and tickit_rect_init_bounded(3) functions. Its bottom right corner can be obtained using tickit_rect_bottom(3) and tickit_rect_right(3). Interactions between rectangles can be tested using the predicate functions tickit_rect_contains(3) and tickit_rect_intersects(3). New rectangles can be created from existing ones using tickit_rect_intersect(3) to form the intersection, tickit_rect_add(3) to form the union sum, and tickit_rect_subtract(3).


title: tickit_rectset(7)

summary: store a collection of rectangular areas

text:
# tickit_rectset(7)

## NAME
TickitRectSet - store a collection of rectangular areas

## SYNOPSIS

```
#include <tickit.h>

typedef struct TickitRectSet;
```

## DESCRIPTION
A TickitRectSet instance stores a collection of rectangular areas as non-overlapping regions. Mutation operations allow areas to be added or subtracted. Query operations allow testing for area containment, intersection, or iterating the stored regions.

## FUNCTIONS
A new TickitRectSet instance is created using the tickit_rectset_new(3) function, and destroyed using tickit_rectset_destroy(3).

Rectangular areas can be added using tickit_rectset_add(3) and subtracted using tickit_rectset_subtract(3). The TickitRectSet can be emptied of regions entirely by using tickit_rectset_clear(3). The entire set of regions can be uniformly moved using tickit_rectset_translate(3).

The stored regions can be queried by using tickit_rectset_rects(3) and tickit_rectset_get_rects(3). An area can be tested to see if it is entirely contained in the set using tickit_rectset_contains(3), or that it intersects at all using tickit_rectset_intersects(3).


title: tickit_renderbuffer(7)

text:
# tickit_renderbuffer(7)

## NAME
TickitRenderBuffer - store display content to be drawn to the terminal

## SYNOPSIS

```
#include <tickit.h>

typedef struct TickitRenderBuffer;
```

## DESCRIPTION
A TickitRenderBuffer instance stores content waiting to be drawn to the terminal. It provides an efficient place to build the eventual display, by applying drawing operations to it that can alter and overwrite the pending content, before eventually flushing it directly to the terminal in an efficient transfer of state. The buffer stores plain text content along with rendering attributes, and also stores line drawing information, allowing line segments to be merged correctly and rendered using Unicode characters.

The primary purpose for the render buffer is the storage of pending content to be displayed. The buffer consists of a grid of cells of the given size. Each cell has a state; neighbouring cells in the same state constitute a region. Each region is either in a skip state (where it will not affect the terminal display when it is flushed), or has either textual content or an instruction to erase the display. In both of these cases, the region has an associated TickitPen instance to give its display attributes. Text regions can be given either by UTF-8 strings, individual Unicode codepoint numbers, or are created as Unicode line-drawing characters by merging one or more effective line segments.

There are several advantages to using a TickitRenderBuffer over plain drawing requests directly to the terminal. Firstly, because the content is simply stored in memory until it is flushed to the terminal, it doesn't have to be rendered in screen order. It can be built up in any order that makes sense within the application, and when flushed to the terminal it will be performed in an efficient top-to-bottom, left-to-right order.

Secondly, the buffer understands horizontal and vertical line drawing using Unicode characters. While content is being built up, it will keep track of what kinds of lines meet in every cell in the buffer, so that when it is flushed to the terminal it can pick the appropriate Unicode line-drawing characters to render these with.

Thirdly, several features of the buffer are designed to easily support applications that divide the screen area into several possibly-overlapping regions that are managed by different parts of the application. Clipping, translation and masking support the concept of independent areas of the buffer, and stored pens and the state stack support the concept that these areas might be nested within each other, allowing rendering attributes to be inherited from outer regions into inner ones.

### VIRTUAL CURSOR
A TickitRenderBuffer instance maintains a virtual cursor position, that application code can use to render at. This is a virtual cursor, because it doesn't relate to the actual cursor in use on the terminal instance; it is simply a position stored by the buffer state.

Most of the content drawing functions come in pairs; one using and updating the cursor position, and a second that operates directly on the buffer contents, without regard to the virtual cursor. Functions of this latter form can be identified by the _at suffix on their name.

### PEN
A TickitPen instance can be set on a TickitRenderBuffer, acting as a default pen for subsequent drawing functions. This is optionally combined with a pen instance given to individual drawing functions; if both are present then the attributes are combined, with those of the given pen taking precedence over the ones in the stored pen.

### TRANSLATION
A translation offset can be applied to have the drawing functions store their output at some other location within the buffer. This translation only affects the drawing functions; the actual operation to flush the contents to the terminal is not affected.

### CLIPPING AND MASKING
All of the drawing functions are also subject to restriction of their output, to apply within a clipping region. Initially the entire buffer is available for drawing, but the area can be restricted to a smaller rectangular area at any time. Requests to draw content outside of this region will be ignored.

In addition to clipping, a buffer can also mask out arbitrary additional rectangular areas within the clipping region. These areas act with the clipping region by ignoring requests to draw inside them while preserving any existing content within them.

Masking and clipping are related but separate concepts. Both place restrictions on where output functions can alter the pending content. Whereas the clipping region is the rectangular area within which all drawing occurs, masking regions are areas in which drawing does not occur.

When combined with translation, these two features allow possibly-overlapping regions of content to be independently managed by separate pieces of code. To render each region of the screen, a render buffer can be set up with a translation offset and clipping rectangle to suit that region, thus avoiding the rendering code having to care about the exact on-screen geometry. By using masking regions, additionally these areas can be managed even when they overlap, by ensuring that areas already drawn by "higher" regions are masked off to ensure that "lower" regions do not overwrite them.

### SAVE STACK
As a further assistance to applications wishing to divide the screen area into nested regions, a set of functions exist to store the current auxiliary state of the buffer (that is, all of the mutable attributes listed above, but without the actual pending content) and later restore that state to its original values.

## FUNCTIONS
A new TickitRenderBuffer instance is created using tickit_renderbuffer_new(3). A render buffer instance stores a reference count to make it easier for applications to manage the lifetime of buffers. A new buffer starts with a count of one, and it can be adjusted using tickit_renderbuffer_ref(3) and tickit_renderbuffer_unref(3). When the count reaches zero the instance is destroyed.

Its size is fixed after creation and can be queried using tickit_renderbuffer_get_size(3). Its contents can be entirely reset back to its original state using tickit_renderbuffer_reset(3).

A translation offset can be set using tickit_renderbuffer_translate(3), and the clipping region restricted using tickit_renderbuffer_clip(3). Masks can be placed within the current clipping region using tickit_renderbuffer_mask(3).

The virtual cursor position can be set using tickit_renderbuffer_goto(3) and unset using tickit_renderbuffer_ungoto(3). It can be queried using tickit_renderbuffer_has_cursorpos(3) to determine if it is set, and tickit_renderbuffer_get_cursorpos(3) to return its position. A TickitPen instance can be set using tickit_renderbuffer_setpen(3).

The auxiliary state can be saved to the state stack using tickit_renderbuffer_save(3) and later restored using tickit_renderbuffer_restore(3). A stack state consisting of just the pen with no other state can be saved using tickit_renderbuffer_savepen(3).

The stored content of a buffer can be copied to another buffer using tickit_renderbuffer_blit(3). This is useful for allowing a window to maintain a backing buffer that can be drawn to at any time and then copied to a destination buffer for display.

The stored content can be flushed to a TickitTerm instance using tickit_renderbuffer_flush_to_term(3).

## DRAWING OPERATIONS
The following functions all affect the stored content within the buffer, taking into account the clipping, translation, masking, stored pen, and optionally the virtual cursor position.

tickit_renderbuffer_skip_at(3), tickit_renderbuffer_skip(3), tickit_renderbuffer_skip_to(3) and tickit_renderbuffer_skiprect(3) create a skipping region; a place where no output will be drawn.

tickit_renderbuffer_text_at(3) and tickit_renderbuffer_text(3) create a text region; a place where normal text is output.

tickit_renderbuffer_erase_at(3), tickit_renderbuffer_erase(3) and tickit_renderbuffer_erase_to(3) create an erase region; a place where existing terminal content will be erased. tickit_renderbuffer_eraserect(3) is a convenient shortcut that erases a rectangle, and tickit_renderbuffer_clear(3) erases the entire buffer area.

tickit_renderbuffer_char_at(3) and tickit_renderbuffer_char(3) place a single Unicode character directly.

tickit_renderbuffer_hline_at(3) and tickit_renderbuffer_vline_at(3) create horizontal and vertical line segments.

## SEE ALSO
tickit(7), tickit_pen(7), tickit_rect(7) tickit_term(7)


title: tickit_string(7)

summary: a reference-counted string buffer

text:
# tickit_string(7)

## NAME
TickitString - a reference-counted string buffer

## SYNOPSIS

```
#include <tickit.h>

typedef struct TickitString;
```

## DESCRIPTION
A TickitString instance stores a NUL-terminated character buffer (i.e. a plain C string) and a reference count. It allows string buffers to be efficiently shared while their usage is tracked, and reclaimed once no longer required.

## FUNCTIONS
A new TickitString instance is created by calling tickit_string_new(3). Once constructed, its buffer can be read by calling tickit_string_get(3) and its length queried by tickit_string_len(3). The buffer should be considered immutable; it cannot be modified.

A string instance maintains a reference count to make it easier for applications to share and manage the lifetime of these buffers. A new string starts with a count of one, and it can be adjusted using tickit_string_ref(3) and tickit_string_unref(3). When the count reaches zero the instance is destroyed.

## SEE ALSO
tickit(7)


title: tickit_term(7)

summary: abstraction of an interactive terminal

text:
# tickit_term(7)

## NAME
TickitTerm - abstraction of an interactive terminal

## SYNOPSIS

```
#include <tickit.h>

typedef struct TickitTerm;
```

## DESCRIPTION
A TickitTerm instance represents an interactive user terminal. It provides functions to draw content to the terminal, and to accept input and other events from it. It supports a variety of modes of operation; allowing both synchronous and asynchronous filehandle IO, and working abstractly via byte buffers.

## FUNCTIONS
A new TickitTerm instance is created using the tickit_term_build(3). A terminal instance stores a reference count to make it easier for applications to manage the lifetime of terminals. A new terminal starts with reference count of one, and it can be adjusted using tickit_term_ref(3) and tickit_term_unref(3). When the count reaches zero the instance is destroyed.

The tickit_term_open_stdio(3) function offers a convenient shortcut to creating a new instance set up to represent the standard input and output streams of the process.

Once built the terminal startup actions are performed, and the tickit_term_await_started_msec(3) function can be used to wait until this is complete. A running instance can be paused using tickit_term_pause(3) and resumed using tickit_term_resume(3). It can be stopped entirely ahead of application termination by tickit_term_teardown(3).

It supports UTF-8 if enabled; either by detection of a UTF-8 locale, explicitly by calling tickit_term_set_utf8(3).

The size of the terminal can be queried using tickit_term_get_size(3), or forced to a given size by tickit_term_set_size(3). If the application is aware that the size of a terminal represented by a tty(7) filehandle has changed (for example due to receipt of a SIGWINCH signal), it can call tickit_term_refresh_size(3) to update it. The type of the terminal is set at construction time but can be queried later using tickit_term_get_termtype(3).

## OUTPUT
A terminal instance can be used for outputting drawing and other commands. For drawing, the functions tickit_term_print(3), tickit_term_goto(3), tickit_term_move(3), tickit_term_scrollrect(3), tickit_term_chpen(3), tickit_term_setpen(3), tickit_term_clear(3) and tickit_term_erasech(3) can be used. Additionally for setting modes, the function tickit_term_setctl_int(3) can be used. If an output buffer is defined it will need to be flushed when drawing is complete by calling tickit_term_flush(3).

## INPUT
Input via a filehandle can be received either synchronously by calling tickit_term_input_wait_msec(3), or asynchronously by calling tickit_term_input_readable(3) and tickit_term_input_check_timeout_msec(3). Any of these functions may cause one or more events to be raised by invoking event handler functions.

## EVENTS
A terminal instance stores a list of event handlers. Each event handler is associated with one event type and stores a function pointer, and an arbitrary pointer containing user data. Event handlers may be installed using tickit_term_bind_event(3) and removed using tickit_term_unbind_event_id(3).

Fake events can be artificially injected into the event handler chain, as if they had been received from the controlling terminal, by tickit_term_emit_key(3) and tickit_term_emit_mouse(3). These may be useful for testing, event capture-and-replay, or other specialised cases.

The event types recognised are:

TICKIT_TERM_ON_DESTROY

The terminal instance is being destroyed.

TICKIT_TERM_ON_RESIZE

The terminal has been resized. info will point to a structure defined as:

```
typedef struct {
    int lines;
    int cols;
} TickitResizeEventInfo;

```

TICKIT_TERM_ON_KEY

A key has been pressed on the keyboard. info will point to a structure defined as:

```
typedef struct {
    TickitKeyEventType type;
    int mod;
    const char *str;
} TickitKeyEventInfo;

```

type is an enumeration that gives the specific type of key event.

TICKIT_KEYEV_KEY

a cursor control, arrow key, or function key. i.e. any of the keys that don't directly produce text.

TICKIT_KEYEV_TEXT

regular Unicode characters.

str will contain the name of the special key, including any applied modifiers, or a UTF-8 string of the Unicode character.

mod will contain a bitmask of TICKIT_MOD_SHIFT, TICKIT_MOD_ALT and TICKIT_MOD_CTRL.

This event only runs until a bound function returns a true value; this prevents later handler functions from observing it.

TICKIT_TERM_ON_MOUSE

A mouse button has been pressed or released, the mouse cursor moved while dragging a button, or the wheel has been scrolled. info will point to a structure defined as:

```
typedef struct {
    TickitMouseEventType type;
    int button;
    int mod;
    int line;
    int col;
} TickitMouseEventInfo;

```

type is an enumeration that gives the specific type of mouse event.

TICKIT_MOUSEEV_PRESS

A mouse button has been pressed.

TICKIT_MOUSEEV_DRAG

The mouse has been moved while a button is being held down.

TICKIT_MOUSEEV_RELEASE

A mouse button has been released.

TICKIT_MOUSEEV_WHEEL

The wheel has been rolled.

button gives the button index for button events, or one of TICKIT_MOUSEWHEEL_UP or TICKIT_MOUSEWHEEL_DOWN for wheel events.

line and col give the position of the mouse cursor for this event.

mod will contain a bitmask of TICKIT_MOD_SHIFT, TICKIT_MOD_ALT and TICKIT_MOD_CTRL.

This event only runs until a bound function returns a true value; this prevents later handler functions from observing it.

## CONTROLS
A terminal instance has a number of runtime-configuration control options that affect its behaviour. These can be set using tickit_term_setctl_int(3) and tickit_term_setctl_str(3), and queried using tickit_term_getctl_int(3). The individual controls have human-readable string names that can be obtained by tickit_termctl_name(3) and searched by name using tickit_termctl_lookup(3). The type of a control option can be queried using tickit_termctl_type(3).

The options are given in an enumeration called TickitTermCtl. The following control values are recognised:

TICKIT_TERMCTL_ALTSCREEN (bool)

The value is a boolean indicating whether the terminal alternate buffer mode should be enabled. When enabled, a temporary buffer is used for drawing, preserving the original contents of the screen. This mode is usually used by full-screen applications to preserve the shell's scrollback state.

TICKIT_TERMCTL_COLORS (int, read-only)

The value indicates how many colors are available. This value is read-only; it can be requested but not set.

On terminfo-driven terminals this will likely be 8, 16, or 256. On xterm-like terminals this will be 16,777,216 (i.e. 1 << 24) if the driver detects that the terminal supports 24-bit RGB8 ("true-color") palettes, or 256 if not.

TICKIT_TERMCTL_CURSORBLINK (bool)

The value is a boolean indicating whether the terminal text cursor should blink. When disabled, the cursor will appear in a steady state, if visible. When enabled, the cursor will appear blinking, if visible. If the cursor is invisible, this should not have any effect.

TICKIT_TERMCTL_CURSORSHAPE (int)

The value is an integer from the TickitCursorShape enumeration indicating what shape the terminal's text cursor should be. Values are:

TICKIT_CURSORSHAPE_BLOCK

A solid block filling the entire cell.

TICKIT_CURSORSHAPE_UNDER

An underline below the character.

TICKIT_CURSORSHAPE_LEFT_BAR

A vertical bar to the left of the character.

Note that not all terminals support setting this option, nor to all of the possible values.

TICKIT_TERMCTL_CURSORVIS (bool)

The value is a boolean indicating whether the terminal text cursor should be visible. When disabled the cursor position is not visible. Typically applications will hide the cursor while performing redrawing operations so as not to show a flickering effect as the cursor moves, and show it again when drawing is complete.

TICKIT_TERMCTL_ICON_TEXT (str)

The value is a string for the terminal to use as its minimised icon text.

TICKIT_TERMCTL_ICONTITLE_TEXT (str)

The value is a string for the terminal to use as its minimised icon text and main window title.

TICKIT_TERMCTL_KEYPAD_APP (bool)

The value is a boolean controlling the terminal's keypad mode. When enabled, the terminal is in keypad application mode; in this mode the numerical keypad will send different sequences that can be detected as distinct from regular ASCII text. When disabled, the keypad will send normal text.

TICKIT_TERMCTL_MOUSE (int)

The value is an integer from the TickitTermMouseMode enumeration indicating what mouse events should be sent. Values are:

BTICKIT_TERM_MOUSEMODE_CLICK

Report button press and release events.

TICKIT_TERM_MOUSEMODE_DRAG

Report button press and release events, and movement while a button is held.

TICKIT_TERM_MOUSEMODE_MOVE

Report all button press, release and motion events even with no buttons held.

TICKIT_TERM_MOUSEMODE_OFF

Report nothing.

TICKIT_TERMCTL_TITLE_TEXT (str)

The value is a string for the terminal to use as its main window title.

## SEE ALSO
tickit(7), tickit_renderbuffer(7)


title: tickit_version(7)

summary: libtickit version queries

text:
# tickit_version(7)

## NAME
tickit_version_* - libtickit version queries

## SYNOPSIS

```
#define TICKIT_VERSION_MAJOR
#define TICKIT_VERSION_MINOR
#define TICKIT_VERSION_PATCH

int tickit_version_major(void);
int tickit_version_minor(void);
int tickit_version_patch(void);
```

## DESCRIPTION
These three macros provide the version numbers of the development header at compiletime. The related functions return the version numbers from the running library. Between them they can be used to check at program startup that the library version is suitable to support the running program.

## RETURN VALUE
Each tickit_version_*() function returns a version integer.

## SEE ALSO
tickit(7)