Some more or less useful helper/convenience functions. More...

Functions
char *	caps_helper_config_path_create (const char *file_name)

int	caps_helper_config_dir_fd (void)

char *	caps_helper_driver_db_path_create (const char *file_name)

int	caps_helper_driver_db_dir_fd (void)

char *	caps_helper_driver_config_path_create (const char *file_name)

int	caps_helper_driver_config_dir_fd (void)

char *	caps_helper_driver_path_create (const char *file_name)

int	caps_helper_driver_dir_fd (void)

char *	caps_helper_device_db_path_create (const char *file_name)

int	caps_helper_device_db_dir_fd (void)

int	caps_helper_number_convert (const char *string)

int	caps_helper_boolean_check (const char *value, int set)

int	caps_helper_invisible_file_create (int *fd)

int	caps_helper_file_content_copy (int fd_to, int fd_from)

int	caps_helper_verbosity_setup (const char *keyword, bool overwrite)

Detailed Description

Used all over the CAPS universe to avoid re-invention the wheel again and again. Expect the list of these function will grow.

Function Documentation

◆ caps_helper_config_path_create()

char * caps_helper_config_path_create ( const char * file_name )

Get the CAPS Configuration Directory or a full qualified file name into it

Parameters

[in] file_name The filename to build a full qualified path (can be NULL)

Returns: Allocated buffer with the path, maybe expanded by the file_name to form a full qualified filename

An example for this directory could be "/etc/caps/". If filename in this example is 'foo' the function returns "/etc/caps/foo"

When debugging is enabled it is possible to set a different directory path via the environment variable CAPS_CONFIG_DIR.

Note: This function does not return on memory failures.

Postcondition: The returned string must be freed after use.

◆ caps_helper_config_dir_fd()

int caps_helper_config_dir_fd ( void )

Return a file descriptor to the CAPS Configuration Directory

Return values

fd	File descriptor of the directory
negative	Negative errno else

An example for this directory could be a file descriptor to "/etc/caps/".

When debugging is enabled it is possible to set a different directory path via the environment variable CAPS_CONFIG_DIR.

The file descriptor is intended to be used with the *at() functions (openat() etc.)

Postcondition: The returned file descriptor must be closed after use.

◆ caps_helper_driver_db_path_create()

char * caps_helper_driver_db_path_create ( const char * file_name )

Get the CAPS Printer Driver Database Directory or a full qualified file name into it

Parameters

[in] file_name The filename to build a full qualified path (can be NULL)

Returns: Allocated buffer with the path, maybe expanded by the file_name to form a full qualified filename

An example for this directory could be "/usr/share/caps/drivers". If filename in this example is 'foo' the function returns "/usr/share/caps/drivers/foo"

When debugging is enabled it is possible to set a different directory path via the environment variable CAPS_PRINTER_DRIVER_DB_DIR.

Note: This function does not return on memory failures.

Postcondition: The returned string must be freed after use.

◆ caps_helper_driver_db_dir_fd()

int caps_helper_driver_db_dir_fd ( void )

Return a file descriptor to the CAPS Printer Driver Database Directory

Return values

fd	File descriptor of the directory
negative	Negative errno else

An example for this directory could be a file descriptor to "/usr/share/caps/drivers".

When debugging is enabled it is possible to set a different directory path via the environment variable CAPS_PRINTER_DRIVER_DB_DIR.

The file descriptor is intended to be used with the *at() functions (openat() etc.)

Postcondition: The returned file descriptor must be closed after use.

◆ caps_helper_driver_config_path_create()

char * caps_helper_driver_config_path_create ( const char * file_name )

Get the CAPS Printer Driver Configuration Directory or a full qualified file name into it

Parameters

[in] file_name The filename to build a full qualified path (can be NULL)

Returns: Allocated buffer with the path, maybe expanded by the file_name to form a full qualified filename

An example for this directory could be "/etc/caps/drivers". If filename in this example is 'foo' the function returns "/etc/caps/drivers/foo"

When debugging is enabled it is possible to set a different directory path via the environment variable CAPS_DRIVER_CONFIGURATION_DIR.

Note: This function does not return on memory failures.

Postcondition: The returned string must be freed after use.

◆ caps_helper_driver_config_dir_fd()

int caps_helper_driver_config_dir_fd ( void )

Return a file descriptor to the CAPS Printer Driver Configuration Directory

Return values

fd	File descriptor of the directory
negative	Negative errno else

An example for this directory could be a file descriptor to "/etc/caps/drivers".

When debugging is enabled it is possible to set a different directory path via the environment variable CAPS_DRIVER_CONFIGURATION_DIR.

The file descriptor is intended to be used with the *at() functions (openat() etc.)

Postcondition: The returned file descriptor must be closed after use.

◆ caps_helper_driver_path_create()

char * caps_helper_driver_path_create ( const char * file_name )

Get the directory path of the CAPS Printer Driver Executables Directory or a full qualified file name into it

Parameters

[in] file_name The filename to build a fully qualified path (can be NULL)

Returns: Allocated buffer with the path, maybe expanded by the file_name to form a full qualified filename

An example for this directory could be "/usr/libexec/caps". If filename in this example is 'foo' the function returns "/usr/libexec/caps/foo"

When debugging is enabled it is possible to set a different directory path via the environment variable CAPS_DRIVER_DIR.

Note: This function does not return on memory failures.

Postcondition: The returned string must be freed after use.

◆ caps_helper_driver_dir_fd()

int caps_helper_driver_dir_fd ( void )

Return a file descriptor to the CAPS Printer Driver Executables Directory

Return values

fd	File descriptor of the directory
negative	Negative errno else

An example for this directory could be a file descriptor to "/usr/libexec/caps".

When debugging is enabled it is possible to set a different directory path via the environment variable CAPS_DRIVER_DIR.

The file descriptor is intended to be used with the *at() functions (openat() etc.)

Postcondition: The returned file descriptor must be closed after use.

◆ caps_helper_device_db_path_create()

char * caps_helper_device_db_path_create ( const char * file_name )

Get the CAPS Printer Device Database Directory or a full qualified file name into it

Parameters

[in] file_name The filename to build a fully qualified path (can be NULL)

Returns: Allocated buffer with the path, maybe expanded by the file_name to form a full qualified filename

An example for this directory could be "/var/lib/caps". If filename in this example is 'foo' the function returns "/var/lib/caps/foo"

When debugging is enabled it is possible to set a different directory path via the environment variable CAPS_PRINTER_DEVICE_DB_DIR.

Note: This function does not return on memory failures.

Postcondition: The returned string must be freed after use.

◆ caps_helper_device_db_dir_fd()

int caps_helper_device_db_dir_fd ( void )

Return a file descriptor to the CAPS Printer Device Database Directory

Return values

fd	File descriptor of the directory
negative	Negative errno else

An example for this directory could be a file descriptor to "/var/lib/caps".

When debugging is enabled it is possible to set a different directory path via the environment variable CAPS_PRINTER_DEVICE_DB_DIR.

The file descriptor is intended to be used with the *at() functions (openat() etc.)

Postcondition: The returned file descriptor must be closed after use.

◆ caps_helper_number_convert()

int caps_helper_number_convert ( const char * string )

This function is a try to read-in a positive ASCII number with error checking to avoid bogus values

Parameters

[in] string The ASCII string containing the positive number to convert

Return values

Positive	The number from the ASCII string
-EINVAL	`string` doesn't look like an ASCII number
-ERANGE	`string` contains an invalid number for an 'int'

If the string isn't a valid number, this function already emits a corresponding error message.

Precondition: The string must be terminated immediately with a trailing '\0' after the last character which forms the number (as every string in 'C')

Note: The ASCII number string can start with '0x' or '0' to support hex format and octal format.

◆ caps_helper_boolean_check()

int caps_helper_boolean_check	(	const char *	value,
		int	set
	)

Evaluate a boolean value based on a specific set of words

Parameters

[in]	value	The text of a boolean value (can be NULL, read below)
[in]	set	Check for a `true` or `false` set of words in `value` (read below)

Return values

1	E.g. true, `value` is part of `set`
0	E.g. false, `value` isn't part of `set`

If set is true (e.g. not 0)

a boolean value can be true if value words like true, on, yes or 1 are used.
if value has one of the listed words, 1 is returned, else 0

if set is false (e.g. 0)

a boolean value can be false if value words like false, off, no or 0 are used.
if value has one of the listed words, 1 is returned, else 0

If value

is NULL
points to an empty string
points to an unknown word

it evaluates to the word set true, on, yes, 1

Note: The value strings are case insensitive.

◆ caps_helper_invisible_file_create()

int caps_helper_invisible_file_create ( int * fd )

Create an invisible and self-removing file and return the file descriptor

Parameters

[out] fd Where to store the file descriptor

Return values

0	On success (`*fd` is valid)
-ENOSPC	Out of space in the CAPS Document Storage Directory
-EACCES	Insufficient directory setup of CAPS Document Storage Directory

Invisible in this file context means, only a file descriptor is created without a visible directory entry. When the file descriptor is closed, the file's content is automatically removed from the file system.

The file is created with read/write permissions.
The file is created in the CAPS Document Storage Directory, usually "/var/spool/caps"

When debugging is enabled it is possible to set a different directory path via the environment variable DOCUMENT_STORAGE_DIR.

Precondition: Matching permissions in the CAPS Document Storage Directory.

Note: The file is opened with read/write permissions.; This approach requires at least Linux 3.11 and support by the underlying filesystem driver, else it falls back to a traditional method (e.g. creating, and unlink while still opened).

Attention: If debugging is enabled, the files are kept instead and use file names of the form caps_temp_file_XXXXXX.

◆ caps_helper_file_content_copy()

int caps_helper_file_content_copy	(	int	fd_to,
		int	fd_from
	)

Copy the content from one file descriptor to a second one

Parameters

[in]	fd_to	Copy content to this file descriptor
[in]	fd_from	Copy content from this file descriptor

Return values

0	On success
-EBADF	At least on of the file descriptors is/are invalid for this operation
-EINVAL	The file descriptors point to the same file

Both file descriptors are not touched after the copy process.

Precondition: The fd_from file descriptor must be sought to the file's begin.; The fd_to file descriptor must have write permission.

Postcondition: Both read and write file offsets are incremented

Note: This function does not return in case of memory failure.

◆ caps_helper_verbosity_setup()

int caps_helper_verbosity_setup	(	const char *	keyword,
		bool	overwrite
	)

Setup the verbosity level, based on a keyword

Parameters

[in]	keyword	Keyword which describes the verbosity level (can be NULL).
[in]	overwrite	true to set the `keyword` value, false to only set higher verbosity

Return values

0	On success
-EINVAL	If the keyword is invalid
-ENOTSUP	If 'debug' isn't supported due to built without debugging support

Note: If keyword is NULL, the function returns immediately with value 0 and the verbosity level isn't changed; The keyword's case is ignored.

Keywords describing the verbosity level are:

'panic' -> LIBCAPS_PANIC
'error' -> LIBCAPS_ERROR
'warn' -> LIBCAPS_WARN
'info' -> LIBCAPS_INFO
'loud' -> LIBCAPS_LOUD
'noisy' -> LIBCAPS_NOISY
'debug' -> LIBCAPS_DEBUG

Note: If overwrite is false, a new verbosity value is set only if the currently set value is 'lower'. E.g. if the current setting is LIBCAPS_WARN and you set 'info' it will be set to LIBCAPS_INFO. But if you want to set it to LIBCAPS_ERROR instead, it won't be set.

Precondition: 'debug' verbosity (e.g. LIBCAPS_DEBUG) is only supported if debugging was enabled at build-time

Note: This function uses a keyword to set the verbosity. Refer caps_verbosity_level_set() for the same feature, but based on an integer/enum instead.

Functions

Detailed Description

Function Documentation

◆ caps_helper_config_path_create()

◆ caps_helper_config_dir_fd()

◆ caps_helper_driver_db_path_create()

◆ caps_helper_driver_db_dir_fd()

◆ caps_helper_driver_config_path_create()

◆ caps_helper_driver_config_dir_fd()

◆ caps_helper_driver_path_create()

◆ caps_helper_driver_dir_fd()

◆ caps_helper_device_db_path_create()

◆ caps_helper_device_db_dir_fd()

◆ caps_helper_number_convert()

◆ caps_helper_boolean_check()

◆ caps_helper_invisible_file_create()

◆ caps_helper_file_content_copy()

◆ caps_helper_verbosity_setup()