title: libpmem2(7)

text:
# libpmem2(7)

## NAME
libpmem2 - persistent memory support library

## SYNOPSIS

```
#include <libpmem2.h>
cc ... -lpmem2

```

## DESCRIPTION
libpmem2 provides low-level persistent memory (pmem) support for applications 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 the load/store, non-paged access to pmem.

This library is for applications that use persistent memory directly, without the help of any library-supplied transactions or memory allocation. Higher-level libraries that currently build on libpmem (previous variation of libpmem2) are available and are recommended for most applications, see:

•

libpmemobj(7), a general use persistent memory API, providing memory allocation and transactional operations on variable-sized objects.

•

libpmemblk(7), providing pmem-resident arrays of fixed-sized blocks with atomic updates.

•

libpmemlog(7), providing a pmem-resident log file.

The libpmem2 library provides a comprehensive set of functions for robust use of Persistent Memory. It relies on three core concepts: struct pmem2_src source, struct pmem2_config config and struct pmem2_map map:

•

source - an object describing the data source for mapping. The data source can be a file descriptor, a file handle, or an anonymous mapping. APIs dedicated for creating source are: pmem2_source_from_fd(3), pmem2_source_from_handle(3), pmem2_source_from_anon(3).

•

config - an object containing parameters that are used to create a mapping from a source. The configuration structure must always be provided to create a mapping, but the only required parameter to set in the config is granularity. The granularity should by set using dedicated libpmem2 function pmem2_config_set_required_store_granularity(3) which defines a maximum permitted granularity requested by the user. For more information about the granularity concept read GRANULARITY section below.

In addition to the granularity setting, libpmem2 provides multiple optional functions to configure target mapping, e.g., pmem2_config_set_length(3) to set length which will be used for mapping, or pmem2_config_set_offset(3) which will be used to map the contents from the specified location of the source, pmem2_config_set_sharing(3) which defines the behavior and visibility of writes to the mapping’s pages.

•

map - an object created by pmem2_map_new(3) using source and config as an input parameters. The map structure can be then used to directly operate on the created mapping through the use of its associated set of functions: pmem2_map_get_address(3), pmem2_map_get_size(3), pmem2_map_get_store_granularity(3) - for getting address, size and effective mapping granularity.

In addition to the basic functionality of managing the virtual address mapping, libpmem2 also provides optimized functions for modifying the mapped data. This includes data flushing as well as memory copying.

To get proper function for data flushing use: pmem2_get_flush_fn(3), pmem2_get_persist_fn(3) or pmem2_get_drain_fn(3). To get proper function for copying to persistent memory, use map getters: pmem2_get_memcpy_fn(3), pmem2_get_memset_fn(3), pmem2_get_memmove_fn(3).

The libpmem2 API also provides support for the badblock and unsafe shutdown state handling.

To read or clear badblocks, the following functions are provided: pmem2_badblock_context_new(3), pmem2_badblock_context_delete(3), pmem2_badblock_next(3) and pmem2_badblock_clear(3).

To handle unsafe shutdown in the application, the following functions are provided: pmem2_source_device_id(3), pmem2_source_device_usc(3). More detailed information about unsafe shutdown detection and unsafe shutdown count can be found in the libpmem2_unsafe_shutdown(7) man page.

## GRANULARITY
The libpmem2 library introduces the concept of granularity through which you may easily distinguish between different levels of storage performance capabilities available to the application as related to power-fail protected domain. The way data reaches this protected domain differs based on the platform and storage device capabilities.

Traditional block storage devices (SSD, HDD) must use system API calls such as msync(), fsync() on Linux, or FlushFileBuffers(),FlushViewOfFile() on Windows to write data reliably. Invoking these functions flushes the data to the medium with page granularity. In the libpmem2 library, this type of flushing behavior is called PMEM2_GRANULARITY_PAGE.

In systems with persistent memory support, a power-fail protected domain may cover different sets of resources: either the memory controller or the memory controller and CPU caches. For this reason, libpmem2 distinguishes two types of granularity for persistent memory: PMEM2_GRANULARITY_CACHE_LINE and PMEM2_GRANULARITY_BYTE.

If the power-fail protected domain covers only the memory controller, the CPU appropriate cache lines must be flushed for the data to be considered persistent. This granularity type is called PMEM2_GRANULARITY_CACHE_LINE. Depending on the architecture, there are different types of machine instructions for flushing cache lines (e.g., CLWB, CLFLUSHOPT, CLFLUSH for Intel x86_64 architecture). Usually, to ensure the ordering of stores, such instructions must be followed by a barrier (e.g., SFENCE).

The third type of granularity PMEM2_GRANULARITY_BYTE applies to platforms where power-fail protected domain covers both the memory controller and CPU caches. In such cases, cache flush instructions are no longer needed, and the platform itself guarantees the persistence of data. But barriers might still be required for ordering.

The library declares these granularity level in pmem2_granularity enum, which the application must set in pmem2_config to the appropriate level for a mapping to succeed. The software should set this config parameter to a value that most accurately represents the target hardware characteristics and the storage patterns of the application. For example, a database storage engine that operates on large logical pages that reside either on SSDs or PMEM should set this value to PMEM2_GRANULARITY_PAGE. The library will create mappings where the new map granularity is lower or equal to the requested one. For example, a mapping with PMEM2_GRANULARITY_CACHE_LINE can be created for the required granularity PMEM2_GRANULARITY_PAGE, but not vice versa.

## CAVEATS
libpmem2 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.

## ENVIRONMENT
libpmem2 can change its default behavior based on the following environment variables. These are primarily intended for testing and are generally not required.

•

PMEM2_FORCE_GRANULARITY=val

Setting this environment variable to val forces libpmem2 to use persist method specific for forced granularity and skip granularity autodetecting mechanism. The concept of the granularity is described in GRANULARITY section above. This variable is intended for use during library testing.

The val argument accepts following text values:

•

BYTE - force byte granularity.

•

CACHE_LINE - force cache line granularity.

•

PAGE - force page granularity.

Granularity values listed above are case-insensitive.

NOTE: The value of PMEM2_FORCE_GRANULARITY is not queried (and cached) at library initialization time, but read during each pmem2_map_new(3) call.

This means that PMEM2_FORCE_GRANULARITY may still be set or modified by the program until the first attempt to map a file.

•

PMEM_NO_CLWB=1

Setting this environment variable to 1 forces libpmem2 to never issue the CLWB instruction on Intel hardware, falling back to other cache flush instructions on that hardware instead (CLFLUSHOPT or CLFLUSH). Without this setting, libpmem2 will always use the CLWB instruction for flushing processor caches on platforms that support this instruction. This variable is intended for use during library testing, but may be required for some rare cases when using CLWB has a negative impact on performance.

•

PMEM_NO_CLFLUSHOPT=1

Setting this environment variable to 1 forces libpmem2 to never issue the CLFLUSHOPT instruction on Intel hardware, falling back to the CLFLUSH instructions instead. Without this environment variable, libpmem2 will always use the CLFLUSHOPT instruction for flushing processor caches on platforms that support the instruction, but where CLWB is not available. This variable is intended for use during library testing.

•

PMEM_NO_MOVNT=1

Setting this environment variable to 1 forces libpmem2 to never use the non-temporal move instructions on Intel hardware. Without this environment variable, libpmem2 will use the non-temporal instructions for copying larger ranges to persistent memory on platforms that support these instructions. This variable is intended for use during library testing.

•

PMEM_MOVNT_THRESHOLD=val

This environment variable allows overriding the minimum length of the pmem2_memmove_fn operations, for which libpmem2 uses non-temporal move instructions. Setting this environment variable to 0 forces libpmem2 to always use the non-temporal move instructions if available. It has no effect if PMEM_NO_MOVNT is set to 1. This variable is intended for use during library testing.

## DEBUGGING
Two versions of libpmem2 are typically available on a development system. The normal version, accessed when a program is linked using the -lpmem2 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 libpmem2, 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.

•

PMEM2_LOG_LEVEL

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

•

0 - This is the default level when PMEM2_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 pmem2_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 libpmem2 developers.

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

•

PMEM2_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 PMEM2_LOG_FILE is not set, output is written to stderr.

## EXAMPLE
The following example uses libpmem2 to flush changes made to raw, memory-mapped persistent memory.

WARNING: There is nothing transactional about the persist from pmem2_get_persist_fn(3) call in this example. Interrupting the program may result in a partial write to pmem. Use a transactional library such as libpmemobj(7) to avoid torn updates.

The above example is described in detail here (https://pmem.io/pmdk/libpmem2/).

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

## SEE ALSO
FlushFileBuffers(), fsync(2), msync(2), pmem2_config_set_length(3), pmem2_config_set_offset(3), pmem2_config_set_required_store_granularity(3), pmem2_config_set_sharing(3),pmem2_get_drain_fn(3), pmem2_get_flush_fn(3), pmem2_get_memcpy_fn(3), pmem2_get_memmove_fn(3), pmem2_get_memset_fn(3), pmem2_get_persist_fn(3),pmem2_map_get_store_granularity(3), pmem2_map_new(3), pmem2_source_from_anon(3), pmem2_source_from_fd(3), pmem2_source_from_handle(3), libpmem2_unsafe_shutdown(7), libpmemblk(7), libpmemlog(7), libpmemobj(7) and <https://pmem.io>


title: libpmem2_unsafe_shutdown(7)

text:
# libpmem2_unsafe_shutdown(7)

## NAME
libpmem2_unsafe_shutdown - libpmem2 unsafe shutdown

## DESCRIPTION
In systems with the persistent memory support, a power-fail protected domain covers a set of resources from which the platform will flush data to the persistent medium in case of a power-failure. Data stored on the persistent medium is preserved across power cycles.

The hardware guarantees the feature to flush all data stored in the power-fail protected domain to the persistent medium. However, nothing is infallible, and Persistent Memory hardware can expose a monotonically increasing unsafe shutdown counter (USC) that is incremented every time a failure of the mechanism above is detected. This allows software to discover situations where a running application was interrupted by a power failure that led to an unsafe shutdown. Undiscovered unsafe shutdowns might cause silent data corruption.

Note: The unsafe shutdown may corrupt data stored on a device, in a file, in a set of files, and a mapping spanning only a part of a file. For the sake of simplicity, all of the above cases will be called file below.

## UNSAFE SHUTDOWN DETECTION
Software can detect an unsafe shutdown by watching for the change between unsafe shutdown count value across application startups. Any changes can be indicative of unsafe shutdown occurrence.

Applications can implement a detection mechanism by storing the USC retrieved from pmem2_source_device_usc(3) in Persistent Memory. Then, on subsequent startups, the stored value must be compared with a newly retrieved one.

However, this detection method can result in false-positives. Moving the file to different Persistent Memory devices with possibly different USC values would lead to false unsafe shutdown detection.

Additionally, relying on USC value alone could result in the detection of unsafe shutdown events that occur when such a shutdown has no chance of impacting the data used by the application, e.g., when nothing is actively using the file.

Applications can avoid false-positives associated with moving the file by storing device identification, obtained through pmem2_source_device_id(3), alongside the USC. This enables the software to check if the underlying device has changed, and reinitialize the stored USC in such cases.

The second behavior, detection of possibly irrelevant unsafe shutdown events, if undesirable, can be prevented by storing a flag indicating whether the file is in use, alongside all the rest of the relevant information.

The application should use pmem2_deep_flush(3) when storing any data related to unsafe shutdown detection for higher reliability. This helps ensure that the detection mechanism is not reliant on the correct functioning of the same hardware features it is designed to safeguard.

General-purpose software should not assume the presence of USC on the platform, and should instead appropriately handle any PMEM2_E_NOSUPP it encounters. Doing otherwise might cause the software to be unnecessarily restrictive about the hardware it supports and would prevent, e.g., testing on emulated PMEM.

## SEE ALSO
pmem2_deep_flush(3), pmem2_persist_fn(3), pmem2_source_device_id(3), pmem2_source_device_usc(3) and <https://pmem.io>


libpmemblk

package: libpmemblk-devel

title: libpmemblk(7)

text:
# libpmemblk(7)

## NAME
libpmemblk - persistent memory resident array of blocks

## SYNOPSIS

```
#include <libpmemblk.h>
cc ... -lpmemblk -lpmem

```

### Library API versioning:

```
const char *pmemblk_check_version(

    unsigned major_required,

    unsigned minor_required);

```

### Managing library behavior:

```
void pmemblk_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 *pmemblk_errormsg(void);

```

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

pmemblk_bsize(3), pmemblk_create(3), pmemblk_ctl_exec(3), pmemblk_ctl_get(3), pmemblk_ctl_set(3), pmemblk_read(3), pmemblk_set_zero(3),

## DESCRIPTION
libpmemblk provides an array of blocks in persistent memory (pmem) such that updates to a single block are atomic. This library is intended for applications 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 the load/store, non-paged access to pmem. libpmemblk builds on this type of memory mapped file.

This library is for applications that need a potentially large array of blocks, all the same size, where any given block is updated atomically (the update cannot be torn by program interruption such as power failures). This library builds on the low-level pmem support provided by libpmem(7), handling the transactional update of the blocks, flushing to persistence, and recovery for the application. libpmemblk is one of a collection of persistent memory libraries available, the others are:

•

libpmemobj(7), a general use persistent memory API, providing memory allocation and transactional operations on variable-sized objects.

•

libpmemlog(7), providing a pmem-resident log file.

•

libpmem(7), low-level persistent memory support.

Under normal usage, libpmemblk 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.

To use the atomic block arrays supplied by libpmemblk, a memory pool is first created using the pmemblk_create() function described in pmemblk_create(3). The other libpmemblk functions operate on the resulting block memory pool using the opaque handle, of type PMEMblkpool*, that is returned by pmemblk_create() or pmemblk_open(). Internally, libpmemblk will use either pmem_persist(3) or msync(2) when it needs to flush changes, depending on whether the memory pool appears to be persistent memory or a regular file (see the pmem_is_pmem(3) function in libpmem(7) for more information). There is no need for applications to flush changes directly when using the block memory API provided by libpmemblk.

## CAVEATS
libpmemblk 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.

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

The pmemblk_check_version() function is used to determine whether the installed libpmemblk 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 <libpmemblk.h>, like this:

```
reason = pmemblk_check_version(PMEMBLK_MAJOR_VERSION,

                               PMEMBLK_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 pmemblk_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 pmemblk_check_version() must not be modified or freed.

## MANAGING LIBRARY BEHAVIOR
The pmemblk_set_funcs() function allows an application to override memory allocation calls used internally by libpmemblk. Passing in NULL for any of the handlers will cause the libpmemblk 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.

## DEBUGGING AND ERROR HANDLING
The pmemblk_errormsg() 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 libpmemblk 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 libpmemblk are typically available on a development system. The normal version, accessed when a program is linked using the -lpmemblk option, is optimized for performance. That version skips checks that impact performance and never logs any trace information or performs any run-time assertions. If an error is detected in a call to libpmemblk, the error message describing the failure may be retrieved with pmemblk_errormsg() as described above.

A second version of libpmemblk, 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 LD_LIBRARY_PATH environment variable 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.

•

PMEMBLK_LOG_LEVEL

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

•

0 - This is the default level when PMEMBLK_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 pmemblk_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 libpmemblk developers.

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

•

PMEMBLK_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 PMEMBLK_LOG_FILE is not set, the logging output is written to stderr.

See also libpmem(7) for information on other environment variables that may affect libpmemblk behavior.

## EXAMPLE
The following example illustrates how the libpmemblk API is used.

```
#include <fcntl.h>
#include <errno.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <libpmemblk.h>
/* size of the pmemblk pool -- 1 GB */
#define POOL_SIZE ((size_t)(1 << 30))
/* size of each element in the pmem pool */
#define ELEMENT_SIZE 1024
int
main(int argc, char *argv[])
{

    const char path[] = "/pmem-fs/myfile";

    PMEMblkpool *pbp;

    size_t nelements;

    char buf[ELEMENT_SIZE];

    /* create the pmemblk pool or open it if it already exists */

    pbp = pmemblk_create(path, ELEMENT_SIZE, POOL_SIZE, 0666);

    if (pbp == NULL)

        pbp = pmemblk_open(path, ELEMENT_SIZE);

    if (pbp == NULL) {

        perror(path);

        exit(1);

    }

    /* how many elements fit into the file? */

    nelements = pmemblk_nblock(pbp);

    printf("file holds %zu elements", nelements);

    /* store a block at index 5 */

    strcpy(buf, "hello, world");

    if (pmemblk_write(pbp, buf, 5) < 0) {

        perror("pmemblk_write");

        exit(1);

    }

    /* read the block at index 10 (reads as zeros initially) */

    if (pmemblk_read(pbp, buf, 10) < 0) {

        perror("pmemblk_read");

        exit(1);

    }

    /* zero out the block at index 5 */

    if (pmemblk_set_zero(pbp, 5) < 0) {

        perror("pmemblk_set_zero");

        exit(1);

    }

    /* ... */

    pmemblk_close(pbp);
}

```

See <https://pmem.io/pmdk/libpmemblk> for more examples using the libpmemblk API.

## BUGS
Unlike libpmemobj(7), data replication is not supported in libpmemblk. Thus, specifying replica sections in pool set files is not allowed.

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

## SEE ALSO
msync(2), dlclose(3), pmemblk_bsize(3), pmemblk_create(3), pmemblk_ctl_exec(3), pmemblk_ctl_get(3), pmemblk_ctl_set(3), pmemblk_read(3), pmemblk_set_zero(3), pmem_is_pmem(3), pmem_persist(3), strerror(3), libpmem(7), libpmemlog(7), libpmemobj(7) and <https://pmem.io>


libpmemlog

package: libpmemlog-devel

title: libpmemlog(7)

text:
# libpmemlog(7)

## NAME
libpmemlog - persistent memory resident log file

## SYNOPSIS

```
#include <libpmemlog.h>
cc ... -lpmemlog -lpmem

```

### Library API versioning:

```
const char *pmemlog_check_version(

    unsigned major_required,

    unsigned minor_required);

```

### Managing library behavior:

```
void pmemlog_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:

```
int pmemlog_check(const char *path);

```

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

pmemlog_append(3), pmemlog_create(3), pmemlog_ctl_exec(3), pmemlog_ctl_get(3), pmemlog_ctl_set(3), pmemlog_nbyte(3), pmemlog_tell(3)

## DESCRIPTION
libpmemlog provides a log file in persistent memory (pmem) such that additions to the log are appended atomically. This library is intended for applications 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 the load/store, non-paged access to pmem. libpmemlog builds on thistype of memory mapped file.

This library is for applications that need a persistent log file updated atomically (the updates cannot be torn by program interruption such as power failures). This library builds on the low-level pmem support provided by libpmem(7), handling the transactional update of the log, flushing to persistence, and recovery for the application.

libpmemlog is one of a collection of persistent memory libraries available. The others are:

•

libpmemobj(7), a general use persistent memory API, providing memory allocation and transactional operations on variable-sized objects.

•

libpmemblk(7), providing pmem-resident arrays of fixed-sized blocks with atomic updates.

•

libpmem(7), low-level persistent memory support.

Under normal usage, libpmemlog 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.

To use the pmem-resident log file provided by libpmemlog, a memory pool is first created. This is done with the pmemlog_create(3) function. The other functions mentioned above in SYNOPSIS section then operate on the resulting log memory pool.

Once created, the memory pool is represented by an opaque handle, of type PMEMlogpool*, which is passed to most of the other functions from libpmemlog. Internally, libpmemlog will use either pmem_persist(3) or msync(2) when it needs to flush changes, depending on whether the memory pool appears to be persistent memory or a regular file (see the pmem_is_pmem(3) function in libpmem(7) for more information). There is no need for applications to flush changes directly when using the log memory API provided by libpmemlog.

## CAVEATS
libpmemlog 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.

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

The pmemlog_check_version() function is used to determine whether the installed libpmemlog 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 provided by defines in <libpmemlog.h>, like this:

```
reason = pmemlog_check_version(PMEMLOG_MAJOR_VERSION,

                               PMEMLOG_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, pmemlog_check_version() returns NULL. Otherwise, the return value is a static string describing the reason the version check failed. The string returned by pmemlog_check_version() must not be modified or freed.

## MANAGING LIBRARY BEHAVIOR
The pmemlog_set_funcs() function allows an application to override memory allocation calls used internally by libpmemlog. Passing in NULL for any of the handlers will cause the libpmemlog 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.

## DEBUGGING AND ERROR HANDLING
The pmemlog_errormsg() 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 libpmemlog 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 libpmemlog are typically available on a development system. The normal version, accessed when a program is linked using the -lpmemlog 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 libpmemlog, 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.

•

PMEMLOG_LOG_LEVEL

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

•

0 - This is the default level when PMEMLOG_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 pmemlog_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 libpmemlog developers.

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

•

PMEMLOG_LOG_FILE

Specifies the name of a file name 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 PMEMLOG_LOG_FILE is not set, logging output is written to stderr.

See also libpmem(7) for information about other environment variables affecting libpmemlog behavior.

## EXAMPLE
The following example illustrates how the libpmemlog API is used.

```
#include <stdio.h>
#include <fcntl.h>
#include <errno.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <libpmemlog.h>
/* size of the pmemlog pool -- 1 GB */
#define POOL_SIZE ((size_t)(1 << 30))
/*

 * printit -- log processing callback for use with pmemlog_walk()

 */
int
printit(const void *buf, size_t len, void *arg)
{

    fwrite(buf, len, 1, stdout);

    return 0;
}
int
main(int argc, char *argv[])
{

    const char path[] = "/pmem-fs/myfile";

    PMEMlogpool *plp;

    size_t nbyte;

    char *str;

    /* create the pmemlog pool or open it if it already exists */

    plp = pmemlog_create(path, POOL_SIZE, 0666);

    if (plp == NULL)

        plp = pmemlog_open(path);

    if (plp == NULL) {

        perror(path);

        exit(1);

    }

    /* how many bytes does the log hold? */

    nbyte = pmemlog_nbyte(plp);

    printf("log holds %zu bytes", nbyte);

    /* append to the log... */

    str = "This is the first string appended";

    if (pmemlog_append(plp, str, strlen(str)) < 0) {

        perror("pmemlog_append");

        exit(1);

    }

    str = "This is the second string appended";

    if (pmemlog_append(plp, str, strlen(str)) < 0) {

        perror("pmemlog_append");

        exit(1);

    }

    /* print the log contents */

    printf("log contains:");

    pmemlog_walk(plp, 0, printit, NULL);

    pmemlog_close(plp);
}

```

See <https://pmem.io/pmdk/libpmemlog> for more examples using the libpmemlog API.

## BUGS
Unlike libpmemobj(7), data replication is not supported in libpmemlog. Thus, specifying replica sections in pool set files is not allowed.

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

## SEE ALSO
msync(2), pmemlog_append(3), pmemlog_create(3), pmemlog_ctl_exec(3), pmemlog_ctl_get(3), pmemlog_ctl_set(3), pmemlog_nbyte(3), pmemlog_tell(3), strerror(3), libpmem(7), libpmemblk(7), libpmemobj(7) and <https://pmem.io>


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 others are:

•

libpmemblk(7), providing pmem-resident arrays of fixed-sized blocks with atomic updates.

•

libpmemlog(7), providing a pmem-resident log file.

•

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.

## DEBUGGING AND 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.

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. 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 PMEMOBJ_LOG_LEVEL 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 PMEMOBJ_LOG_FILE is set, 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.

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), libpmemblk(7), libpmemlog(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, pmemblk pool, pmemlog pool or BTT layout, 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), libpmemblk(7), libpmemlog(7), libpmemobj(7) and <https://pmem.io>**


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.21.9-alt3.p11.1 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)