#include <dk.h>
#include <dktypes.h>
Go to the source code of this file.
Defines | |
#define | DK_APP_PREF_EXCL_CMD 1 |
Preferences: Exclude command line settings. | |
#define | DK_APP_PREF_EXCL_PROG 2 |
Preferences: Exclude programs own settings. | |
#define | DK_APP_PREF_EXCL_USER 4 |
Preferences: Exclude users settings. | |
#define | DK_APP_PREF_EXCL_SYSTEM 8 |
Preferences: Exclude system settings. | |
#define | DK_APP_IDE_NONE 0 |
Logging: Do not behave as any of the programs below. | |
#define | DK_APP_IDE_GCC 1 |
Logging: Behave like gcc. | |
#define | DK_APP_IDE_MSVC 2 |
Logging: Behave like MS VC. | |
#define | DK_APP_IDE_WORKSHOP 3 |
Logging: Behave like Workshop compiler. | |
#define | DK_APP_IDE_TASM 4 |
Logging: Behave like tasm. | |
#define | DK_APP_PNC_LANGUAGE 2 |
File search: Take care of users language. | |
#define | DK_APP_PNC_REGION 1 |
File search: Take care of users region. | |
#define | DK_APP_PNC_ENCODING 4 |
File search: Take care of users encoding. | |
#define | DK_APP_LOG_NO_STDOUT 1 |
Logging: No logging to standard output. | |
#define | DK_APP_LOG_NO_STDERR 2 |
Logging: No logging to standard error output. | |
#define | DK_APP_LOG_NO_STDIO (DK_APP_LOG_NO_STDOUT | DK_APP_LOG_NO_STDERR) |
Logging: No logging to standard output or standard error output. | |
Functions | |
dk_app_t * | dkapp_open_ext1 (\int c, char *v[], char *g, char *e, int s, int n) |
Create application support structure. | |
int | dkapp_silence_check (int argc, char **argv) |
Check command line arguments for --/log/off. | |
dk_app_t * | dkapp_open (int c, char *v[]) |
Create application support structure (obsoleted). | |
int | dkapp_set_groupname (dk_app_t *a, char *n) |
Set application group name for application opened with dkapp_open(). | |
void | dkapp_set_silent (dk_app_t *a, int f) |
Set silence flag for application opened with dkapp_open(). | |
void | dkapp_set_nostdio (dk_app_t *a, int f) |
Set no-standard-output flag for application opened with dkapp_open(). | |
void | dkapp_close (dk_app_t *a) |
Destroy application support structure and release memory. | |
char * | dkapp_get_appname (dk_app_t *a) |
Retrieve application name. | |
int | dkapp_get_argc (dk_app_t *a) |
Retrieve number of ``real'' command line arguments (command line options to overwrite preferences removed). | |
char ** | dkapp_get_argv (dk_app_t *a) |
Retrieve array of ``real'' command line arguments (command line options to overwrite preferences removed). | |
int | dkapp_get_pref (dk_app_t *a, char *k, char *b, size_t l, int x) |
Get preference. | |
int | dkapp_get_pref_env (\dk_app_t *a, char *k, char *b, size_t l, int x, char *e) |
Get preference or environment variable contents. | |
int | dkapp_set_pref (dk_app_t *a, char *k, char *v) |
Set preference value. | |
int | dkapp_get_bool_pref (dk_app_t *a, char *k) |
Retrieve boolean value from preferences. | |
unsigned long | dkapp_get_ul_pref (dk_app_t *a, char *k) |
Retrieve unsigned long value from preferences. | |
char * | dkapp_get_str_pref (dk_app_t *a, char *k) |
Retrieve string value from preferences. | |
void | dkapp_unconfigure (dk_app_t *a) |
Set unconfigure flag for the application. | |
int | dkapp_transform_string (dk_app_t *a, char *d, size_t l, char *s) |
Transform string (substitute placeholders). | |
int | dkapp_transform_string_ext1 (dk_app_t *a, char *d, size_t l, char *s, int f) |
Transform string, correct slashes/backslashes in file names if necessary. | |
int | dkapp_tmpnam (dk_app_t *a, char *b, size_t s) |
Create name for temporary file. | |
int | dkapp_log_msg (dk_app_t *a, int p, char **m, int n) |
Log multi-part message. | |
void | dkapp_set_source_filename (dk_app_t *a, char *n) |
Set name of source file to use in log messages (error position). | |
void | dkapp_set_source_lineno (dk_app_t *a, unsigned long l) |
Set line number to use in log messages (error position). | |
char * | dkapp_get_source_filename (dk_app_t *a) |
Retrieve source file name for error positions. | |
unsigned long | dkapp_get_source_lineno (dk_app_t *a) |
Retrieve source line number for error positions. | |
int | dkapp_llmax_get (dk_app_t *a) |
Retrieve maximum log message priority found. | |
int | dkapp_get_min_loglevel (dk_app_t *a) |
Get the minimum log priority required by all log destinations. | |
int | dkapp_ide_type (char *s) |
Get key indicating which output style to simulate. | |
void | dkapp_set_keep_temp (dk_app_t *a, int p) |
Set log message priority required to not delete the temporary directory at the end of the application. | |
void | dkapp_llmax_set (dk_app_t *a, int p) |
Overwrite maximum log message priority found. | |
int | dkapp_log_level_in_use (dk_app_t *a, int p) |
Check whether or not a log priority was already used. | |
int | dkapp_find_file (dk_app_t *a, char *n, char *b, size_t s) |
Search for file. | |
int | dkapp_find_cfg (dk_app_t *a, char *n, char *b, size_t s) |
Search for configuration file. | |
char * | dkapp_find_file_dup (dk_app_t *a, char *n) |
Search for file, return copy of file name. | |
char * | dkapp_find_cfg_dup (dk_app_t *a, char *n) |
Search for configuration file, return copy of file name. | |
dk_stream_t * | dkapp_read_file_ext1 (dk_app_t *a, char *n, int *t) |
Open a file for reading, return stream. | |
dk_stream_t * | dkapp_read_file (dk_app_t *a, char *n) |
Open a file for reading, return stream. | |
dk_stream_t * | dkapp_read_cfg (dk_app_t *a, char *n) |
Search for file and open file for reading. | |
dk_stream_t * | dkapp_write_file (dk_app_t *a, char *n) |
Open file for writing. | |
char * | dkapp_find_string (dk_app_t *a, char *t, char *k, char *d) |
Find string (use for localization). | |
void | dkapp_find_multi (dk_app_t *a, dk_string_finder_t *f, char *t) |
Find multiple strings (use for localization). | |
void | dkapp_init_key_value (\dk_app_t *a, dk_key_value_t *k, size_t s, char *n, char **b) |
Find multiple strings. | |
char ** | dkapp_find_key_value (dk_app_t *a, dk_key_value_t *k, size_t s, char *n) |
Find multiple strings. | |
void | dkapp_help (dk_app_t *a, char *n, char **d) |
Show localized help text. | |
dk_stream_t * | dkapp_stream_openfile (dk_app_t *a, char *n, char *m) |
Open a file for use with dk_stream_t API (plain file), apply security checks before opening the file. | |
dk_stream_t * | dkapp_stream_opengz (dk_app_t *a, char *n, char *m) |
Open a file for use with dk_stream_t API (gzip compressed file, requires gzip support), apply security checks before opening the file. | |
dk_stream_t * | dkapp_stream_openbz2 (dk_app_t *a, char *n, char *m) |
Open a file for use with dk_stream_t API (bzip2 compressed file, requires bzip2 support), apply security checks before opening the file. | |
FILE * | dkapp_fopen (dk_app_t *a, char *n, char *m) |
Open a file, apply security checks before opening the file. | |
int | dkapp_get_relaxed_fopen_check (dk_app_t *a) |
Get security checks ignored by dkapp_fopen(), dkapp_stream_openfile(), dkapp_stream_opengz() and dkapp_stream_openbz2(). | |
unsigned char * | dkapp_get_stdout_codepage (dk_app_t *a) |
Get pointer to codepage. | |
char * | dkapp_fne_one (dk_app_t *a, dk_fne_t *f, char *p) |
Check whether a file name expander matches exactly one entry, report error if necessary. | |
void | dkapp_stdout (dk_app_t *a, char *s) |
Print a string to standard output, do codepage translations if necessary. | |
void | dkapp_stderr (dk_app_t *a, char *s) |
Print string to standard error output, do codepage translations if necessary. | |
void | dkapp_fputs (dk_app_t *a, char *s, FILE *f) |
Print string to file, do codepage translations if necessary. | |
size_t | dkapp_prlen (dk_app_t *a, char *s) |
Get number of glyphs to print. | |
void | dkapp_info_no_openssl_support (dk_app_t *a) |
Information message: No OpenSSL support available. | |
void | dkapp_err_traverse_dir (dk_app_t *a, char *n) |
Error message: Failed to traverse directory. | |
void | dkapp_err_stat_failed (dk_app_t *a, char *n) |
Error message: Failed to obtain information about file. | |
void | dkapp_err_cwd (dk_app_t *a) |
Error message: Failed to find current working directory. | |
void | dkapp_err_memory (dk_app_t *a, size_t e, size_t n) |
Error message: Failed to allocate memory. | |
void | dkapp_err_matchfile (dk_app_t *a, char *n) |
Error message: No file name is matching the name pattern. | |
void | dkapp_err_matchdir (dk_app_t *a, char *n) |
Error message: No directory name is matching the pattern. | |
void | dkapp_err_fopenr (dk_app_t *a, char *n) |
Error message: Failed to open file for reading. | |
void | dkapp_err_fopenw (dk_app_t *a, char *n) |
Error message: Failed to open file for writing. | |
void | dkapp_err_fwrite (dk_app_t *a, char *n) |
Error message: Error while writing to file. | |
void | dkapp_err_fread (dk_app_t *a, char *n) |
Error message: Error while reading from file. | |
void | dkapp_err_nowrite (dk_app_t *a, char *n, int r) |
Error message: Additional security checks deny write operations to file. | |
void | dkapp_err_tcpip (dk_app_t *a) |
Error message: TCP/IP protocol not available. | |
void | dkapp_err_no_such_file (dk_app_t *a, char *n) |
Error message: No such file. | |
void | dkapp_err_multiple_files (dk_app_t *a, char *p) |
Error message: Pattern matches multiple files. | |
void | dkapp_err_not_a_regular_file (dk_app_t *a, char *n) |
Error message: Not a regular file. | |
void | dkapp_info_file_does_not_exist (dk_app_t *a, char *n) |
Informational message: File does not exist. | |
void | dkapp_err_invalid_permissions (dk_app_t *a, char *n) |
Error message: Invalid permissions to file. | |
void | dkapp_err_invalid_owner (dk_app_t *a, char *n) |
Error message: Invalid file owner. | |
void | dkapp_err_not_a_device (dk_app_t *a, char *n) |
Error message: Not a device. | |
void | dkapp_err_no_zlib_support_for (dk_app_t *a, char *n) |
Error message: No zlib support available. | |
void | dkapp_err_no_bzlib_support_for (dk_app_t *a, char *n) |
Error message: No bzip2 support available. | |
int | dkapp_rand_types_from_string (dk_app_t *a, char *s) |
Convert string containing list of allowed PRNG types to key. | |
int | dkapp_rand_begin (dk_app_t *a, int r) |
Initialize random number generation seed PRNG. | |
size_t | dkapp_rand_bytes (dk_app_t *a, void *b, size_t s) |
Obtain random bytes. | |
size_t | dkapp_rand_bytes_non_crypto (dk_app_t *a, void *b, size_t s) |
Obtain random bytes for non-cryptographic purposes. | |
int | dkapp_rand_end (dk_app_t *a) |
End random number generation, save seed and close PRNG. |
Preferences are persistent key/value pairs of strings stored in configuration files or registry entries. Command line arguments can be used to overwrite the stored preferences. The key consists of a scope and a name. The scope activates or deactivates a preference for combinations of user name, application name and host name. A scope is valid if the scope user name matches the current user name, the application name matches the current application name and the host name matches the current host name. Wildcards (``*'') may be used in the configuration files or registry entries to match any name.
If user ``joe'' runs application ``dosomething'' on the host ``pc'', the following scopes are searched to find a preference: *|*|*, *|*|pc, *|dosomething|*, *|dosomething|pc, joe|*|*, joe|*|pc, joe|dosomething|*, joe|dosomething|pc.
The last scope has highest priority, preferences in this scope overwrite preferences defined in other scope.
Note: In scope names in registry entries or configuration files use slashes ``/'' instead of the pipe symbols ``|'' used in the paragraph above. The pipe symbol was used as a separator here because combinations of slashes and asterisks are treated as opening and closing comments in header files.
File search is based on the users preferred language and region and can be used for internationalization.
The search order is described in dklibs - File search.
To build file names one can use macros as described in dlibs - Preferences, section "Macros in preferences" and run a string transformation.
Log output can be written to multiple destinations:
Unless otherwise stated, int functions in this module return a positive number to indicate success or a true condition, 0 to indicate an error or an unfullfilled condition. Pointer functions return valid pointers on success, NULL on error.
Some functions return pointers to internal data or other memory managed the the application support structure. This memory is released during dkapp_close(), so do not attempt to use the pointers after the application support structure was destroyed.
dk_app_t *a; /* Application structure. */ int f_s; /* Flag: Run silently. */ f_s = dkapp_silence_check(argc, argv); a = dkapp_open_ext1(argc, argv, "tests", "/etc", f_s, 0); if(a) { ... dkapp_close(a); }
Example: Opening and closing an application. The program already inspected the command line arguments and found that the programs normal output goes to stdout so stdout can not be used for logging.
dk_app_t *a; int f_s; a = dkapp_open_ext1(argc, argv, "tests", "/etc", f_s, DK_APP_LOG_NO_STDOUT); if(a) { ... dkapp_close(a); }
Example: Show all command line options without application preferences.
dk_app_t *a; int c; /* Number of command line arguments (argc). */ char **v; /* Command line arguments array (argv). */ char **p; /* Used to traverse v. */ a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { c = dkapp_get_argc(a); v = dkapp_get_argv(a); p = v; p++; for(int i = 1; i < argc; i++) { printf("Argument %03d: \"%s\"\n", *(p++)); } dkapp_close(a); }
Example: Retrieve some preferences, show values. The pk array contains the preferences names.
/* Example preference key. */ char *pk[] = { "/ui/lang", "/ui/lang/env", "/test-preference", NULL }; dk_app_t *a; char **p; /* Used to traverse pk. */ char b[256]; /* Buffer for results. */ a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { p = pk; while(*p) { if(dkapp_get_pref(a, *p, b, sizeof(b), 0)) { printf("Key \"%s\" -> Value \"%s\"\n", *p, b); } else { printf("No value for key \"%s\"\n", *p); } p++; } dkapp_close(a); }
Example: Get value from preferences/environment mix. Search order is: Command line options to overwrite preferences, environment variable, preferences.
dk_app_t *a; char b[256]; a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { if(dkapp_get_pref_env(a, "/ui/lang", b, sizeof(b), 0, "LANG")) { printf("Language setting: \"%s\"\n", b); } else { printf("Failed to find language definition.\n"); } dkapp_close(a); }
Example: Transform a file name.
dk_app_t *a; char b[256]; a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { if(dkapp_transform_string_ext1(a, b, sizeof(b), "$(temp.dir)/$process.pid)", 1)) { printf("New file name: \"%s\"\n", b); } else { printf("Failed to transform string.\n"); } dkapp_close(a); }
Example: Create a name for a temporary file. The file is placed in a process-specific directory which is removed completely during dkapp_close().
dk_app_t *a; char b[256]; a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { if(dkapp_tmpnam(a, b, sizeof(b)) { printf("Name for temporary file: \"%s\"\n", b); } else { printf("Failed to create temporary file name.\n"); } dkapp_close(a); }
Example: Write a log message.
dk_app_t *a; char b[256]; char *m[4]; /* Message parts pointers array. */ a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { if(dkapp_tmpnam(a, b, sizeof(b)) { m[0] = "Temporary file name: \""; m[1] = b; m[2] = "\"."; dkapp_log_msg(a, DK_LOG_LEVEL_INFO, m, 3); } else { m[0] = "Failed to find temporary file name!"; dkapp_log_msg(a, DK_LOG_LEVEL_ERROR, m, 1); } dkapp_close(a); }
Example: Find data/resource file and read line by line. See Search order for dkapp_find_file() and dkapp_find_cfg() for details about the search order.
dk_app_t *a; char b[256]; a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { dk_stream_t *s; s = dkapp_read_file(a, "x.txt"); if(s) { while(dkstream_gets(s, b, sizeof(b))) { fputs(b, stdout); } dkstream_close(s); } dkapp_close(a); }
Example: Find configuration file and read line by line.
dk_app_t *a; char b[256]; a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { dk_stream_t *s; s = dkapp_read_cfg(a, "x.txt"); if(s) { while(dkstream_gets(s, b, sizeof(b))) { fputs(b, stdout); } dkstream_close(s); } dkapp_close(a); }
Example: Use localized texts.
static dk_key_value_t kv[] = { { "/m/00", "Hello." }, { "/m/01", "Goodbye." } }; static size_t szkv = sizeof(kv)/sizeof(dk_key_value_t); dk_app_t *a; a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { char **m; m = dkapp_find_key_value(a, kv, szkv, "test"); if(m) { fputs(m[0], stdout); fputc('\n', stdout); fputs(m[1], stdout); fputc('\n', stdout); dk_delete(m); } else { printf("Failed to find localized strings.\n"); } dkapp_close(a); }
Example: Get number of glyphs to print. For some encodings -- i.e. UTF-8 -- the number of glyphs to print differs from the string length.
> static dk_key_value_t kv[] = { { "/m/00", "Hello." }, { "/m/01", "Goodbye." } }; static size_t szkv = sizeof(kv)/sizeof(dk_key_value_t); dk_app_t *a; a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { char **m; m = dkapp_find_key_value(a, kv, szkv, "test"); if(m) { printf( "Number of glyphs in \"%s\": %lu\n", m[0], (unsigned long)dkapp_prlen(a, m[0]) ); dk_delete(m); } else { printf("Failed to find localized strings.\n"); } dkapp_close(a); }
Example: Print a string to standard output, do codepage translations if necessary.
dk_app_t *a; a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { dkapp_stdout(a, "This is a test.\n"); dkapp_close(a); }
Example: Show a localized help text on standard output, do codepage translations if necessary.
static char *help_text[] = { "This text is only shown if the help.txt file", "is not found.", NULL }; dk_app_t *a; a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { dkapp_help(a, "help.txt", help_text); dkapp_close(a); }
Example: Open a file as stream for writing, apply security checks. Note: The exact file name must be specified here, no search is done.
dk_app_t *a; a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { dk_stream_t *s; /* Stream for write operations. */ s = dkapp_stream_openfile(a, "x.txt", "w"); if(s) { dkstream_puts(s, "This is a test.\n"); dkstream_close(s); } dkapp_close(a); }
Example: Open a file for writing, apply security checks.
dk_app_t *a; a = dkapp_open_ext1(argc, argv, "tests", "/etc", 0, DK_APP_LOG_NO_STDOUT); if(a) { FILE *f; f = dkapp_fopen(a, "x.txt", "w"); if(f) { fputs("This is a test.\n", f); fclose(f); } dkapp_close(a); }
#define DK_APP_IDE_GCC 1 |
Logging: Behave like gcc.
#define DK_APP_IDE_MSVC 2 |
Logging: Behave like MS VC.
#define DK_APP_IDE_NONE 0 |
Logging: Do not behave as any of the programs below.
#define DK_APP_IDE_TASM 4 |
Logging: Behave like tasm.
#define DK_APP_IDE_WORKSHOP 3 |
Logging: Behave like Workshop compiler.
#define DK_APP_LOG_NO_STDERR 2 |
Logging: No logging to standard error output.
#define DK_APP_LOG_NO_STDIO (DK_APP_LOG_NO_STDOUT | DK_APP_LOG_NO_STDERR) |
Logging: No logging to standard output or standard error output.
#define DK_APP_LOG_NO_STDOUT 1 |
Logging: No logging to standard output.
#define DK_APP_PNC_ENCODING 4 |
File search: Take care of users encoding.
#define DK_APP_PNC_LANGUAGE 2 |
File search: Take care of users language.
#define DK_APP_PNC_REGION 1 |
File search: Take care of users region.
#define DK_APP_PREF_EXCL_CMD 1 |
Preferences: Exclude command line settings.
#define DK_APP_PREF_EXCL_PROG 2 |
Preferences: Exclude programs own settings.
#define DK_APP_PREF_EXCL_SYSTEM 8 |
Preferences: Exclude system settings.
#define DK_APP_PREF_EXCL_USER 4 |
Preferences: Exclude users settings.
void dkapp_close | ( | dk_app_t * | a | ) |
Destroy application support structure and release memory.
a | Pointer to the structure. |
void dkapp_err_cwd | ( | dk_app_t * | a | ) |
Error message: Failed to find current working directory.
a | Application support structure. |
void dkapp_err_fopenr | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: Failed to open file for reading.
a | Application support structure. | |
n | File name. |
void dkapp_err_fopenw | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: Failed to open file for writing.
a | Application support structure. | |
n | File name. |
void dkapp_err_fread | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: Error while reading from file.
a | Application support structure. | |
n | File name. |
void dkapp_err_fwrite | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: Error while writing to file.
a | Application support structure. | |
n | File name. |
void dkapp_err_invalid_owner | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: Invalid file owner.
a | Application support structure. | |
n | File name. |
void dkapp_err_invalid_permissions | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: Invalid permissions to file.
a | Application support structure. | |
n | File name. |
void dkapp_err_matchdir | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: No directory name is matching the pattern.
a | Application support structure. | |
n | Directory name. |
void dkapp_err_matchfile | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: No file name is matching the name pattern.
a | Application support structure. | |
n | File name pattern. |
void dkapp_err_memory | ( | dk_app_t * | a, | |
size_t | e, | |||
size_t | n | |||
) |
Error message: Failed to allocate memory.
a | Application support structure. | |
e | Element size. | |
n | Number of elements. |
void dkapp_err_multiple_files | ( | dk_app_t * | a, | |
char * | p | |||
) |
Error message: Pattern matches multiple files.
a | Application support structure. | |
p | File name pattern. |
void dkapp_err_no_bzlib_support_for | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: No bzip2 support available.
a | Application support structure. | |
n | File name. |
void dkapp_err_no_such_file | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: No such file.
a | Application support structure. | |
n | File name. |
void dkapp_err_no_zlib_support_for | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: No zlib support available.
a | Application support structure. | |
n | File name. |
void dkapp_err_not_a_device | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: Not a device.
a | Application support structure. | |
n | File name. |
void dkapp_err_not_a_regular_file | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: Not a regular file.
a | Application support structure. | |
n | File name. |
void dkapp_err_nowrite | ( | dk_app_t * | a, | |
char * | n, | |||
int | r | |||
) |
Error message: Additional security checks deny write operations to file.
a | Application support structure. | |
n | File name. | |
r | Key for the failed security check. |
void dkapp_err_stat_failed | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: Failed to obtain information about file.
a | Application support structure. | |
n | File name. |
void dkapp_err_tcpip | ( | dk_app_t * | a | ) |
Error message: TCP/IP protocol not available.
a | Application support structure. |
void dkapp_err_traverse_dir | ( | dk_app_t * | a, | |
char * | n | |||
) |
Error message: Failed to traverse directory.
a | Application support structure. | |
n | Directory name. |
int dkapp_find_cfg | ( | dk_app_t * | a, | |
char * | n, | |||
char * | b, | |||
size_t | s | |||
) |
Search for configuration file.
See ``Search order for dkapp_find_file() and dkapp_find_cfg()'' for a list of directories searched.
a | Application support structure. | |
n | File name to search for. | |
b | Buffer to receive the result. | |
s | Size of b in bytes. |
char* dkapp_find_cfg_dup | ( | dk_app_t * | a, | |
char * | n | |||
) |
Search for configuration file, return copy of file name.
This function searches for a file and creates a copy of the file name found in dynamically allocated memory. Use dk_delete() to release the memory after usage. See ``Search order for dkapp_find_file() and dkapp_find_cfg()'' for a list of directories searched.
a | Application support structure. | |
n | File name to search for. |
int dkapp_find_file | ( | dk_app_t * | a, | |
char * | n, | |||
char * | b, | |||
size_t | s | |||
) |
Search for file.
This function searches for a file. See ``Search order for dkapp_find_file() and dkapp_find_cfg()'' for a list of directories searched.
a | Application support structure. | |
n | File name to search for. | |
b | Buffer to receive the result. | |
s | Size of b in bytes. |
char* dkapp_find_file_dup | ( | dk_app_t * | a, | |
char * | n | |||
) |
Search for file, return copy of file name.
This function searches for a file and creates a copy of the file name found in dynamically allocated memory. Use dk_delete() to release the memory after usage. See ``Search order for dkapp_find_file() and dkapp_find_cfg()'' for a list of directories searched.
a | Application support structure. | |
n | File name to search for. |
char** dkapp_find_key_value | ( | dk_app_t * | a, | |
dk_key_value_t * | k, | |||
size_t | s, | |||
char * | n | |||
) |
Find multiple strings.
a | Application support structure. | |
k | Array of key/value pairs, each element must be initialized to contain a string key and a default string. | |
s | The number of elements in k. | |
n | String table name. |
void dkapp_find_multi | ( | dk_app_t * | a, | |
dk_string_finder_t * | f, | |||
char * | t | |||
) |
Find multiple strings (use for localization).
The function attempts to load string table t (if not yet loaded). Now it attempts to find all the strings configured in f.
a | Application support structure | |
f | Configuration of all strings to search for. | |
t | String table name. |
char* dkapp_find_string | ( | dk_app_t * | a, | |
char * | t, | |||
char * | k, | |||
char * | d | |||
) |
Find string (use for localization).
The function attempts to read string table t and searches for a string for key k. On success a pointer to the string is returned, the string is placed in memory maintained by the application support structure. After dkapp_close() you must not longer use it.
a | Application support structure. | |
t | String table name. | |
k | String key. | |
d | Default value (if table not found, string not found or out of memory). |
Check whether a file name expander matches exactly one entry, report error if necessary.
The function returns a copy of the file name placed in dynamically allocated memory on success. Use dk_delete() to release the memory.
a | Application support structure. | |
f | File name expander. | |
p | Pattern to match. |
FILE* dkapp_fopen | ( | dk_app_t * | a, | |
char * | n, | |||
char * | m | |||
) |
Open a file, apply security checks before opening the file.
a | Application support structure. | |
n | File name. | |
m | File open mode (i.e. "r", "w"...). |
void dkapp_fputs | ( | dk_app_t * | a, | |
char * | s, | |||
FILE * | f | |||
) |
Print string to file, do codepage translations if necessary.
a | Application support structure. | |
s | String to print. | |
f | Destination file. |
char* dkapp_get_appname | ( | dk_app_t * | a | ) |
Retrieve application name.
This function returns the application name without leading directory name and without trailing ``.exe'' (on Windows systems).
a | Application support structure. |
int dkapp_get_argc | ( | dk_app_t * | a | ) |
Retrieve number of ``real'' command line arguments (command line options to overwrite preferences removed).
a | Application support structure. |
char** dkapp_get_argv | ( | dk_app_t * | a | ) |
Retrieve array of ``real'' command line arguments (command line options to overwrite preferences removed).
a | Application support structure. |
int dkapp_get_bool_pref | ( | dk_app_t * | a, | |
char * | k | |||
) |
Retrieve boolean value from preferences.
a | Application support structure. | |
k | Preference name. |
int dkapp_get_min_loglevel | ( | dk_app_t * | a | ) |
Get the minimum log priority required by all log destinations.
If -- for instance -- the minimum log priority required by any destination is "warning" there is no need to load string tables for localized debug messages.
a | Application support structure. |
int dkapp_get_pref | ( | dk_app_t * | a, | |
char * | k, | |||
char * | b, | |||
size_t | l, | |||
int | x | |||
) |
Get preference.
a | Application support structure. | |
k | Key (preference name without scope). | |
b | Buffer to receive result. | |
l | Length of buffer b. | |
x | Scopes to exclude (0 or combination of DK_APP_PREF_EXCL_xxx constants). |
int dkapp_get_pref_env | ( | \dk_app_t * | a, | |
char * | k, | |||
char * | b, | |||
size_t | l, | |||
int | x, | |||
char * | e | |||
) |
Get preference or environment variable contents.
Search order is:
a | Application support structure. | |
k | Key (preference name without scope). | |
b | Buffer to receive result. | |
l | Length of buffer b. | |
x | Scopes to exclude (0 or combination of DK_APP_PREF_EXCL_xxx constants). | |
e | Name of environment variable to test. |
int dkapp_get_relaxed_fopen_check | ( | dk_app_t * | a | ) |
Get security checks ignored by dkapp_fopen(), dkapp_stream_openfile(), dkapp_stream_opengz() and dkapp_stream_openbz2().
You can use command line options to set preferences to ignore some of the additional security checks applied when opening files. This is not recommended.
a | Application support structure. |
char* dkapp_get_source_filename | ( | dk_app_t * | a | ) |
Retrieve source file name for error positions.
a | Application support structure. |
unsigned long dkapp_get_source_lineno | ( | dk_app_t * | a | ) |
Retrieve source line number for error positions.
a | Application support structure. |
unsigned char* dkapp_get_stdout_codepage | ( | dk_app_t * | a | ) |
Get pointer to codepage.
a | Application support structure. |
char* dkapp_get_str_pref | ( | dk_app_t * | a, | |
char * | k | |||
) |
Retrieve string value from preferences.
On success the function returns a pointer to a copy of the value in dynamically allocated memory. Use dk_delete() to release the memory after usage.
a | Application support structure. | |
k | Preference name |
unsigned long dkapp_get_ul_pref | ( | dk_app_t * | a, | |
char * | k | |||
) |
Retrieve unsigned long value from preferences.
a | Application support structure. | |
k | Preference name. |
void dkapp_help | ( | dk_app_t * | a, | |
char * | n, | |||
char ** | d | |||
) |
Show localized help text.
The function searches for file n and prints its contents to standard output. If the file is not found the elements of the string array d are shown instead. The final element in d must be a NULL pointer.
a | Application support structure. | |
n | File name of help file. | |
d | Array of pointers to strings (last element must be NULL). |
int dkapp_ide_type | ( | char * | s | ) |
Get key indicating which output style to simulate.
s | Name of program to imitate: "gcc", "msvc", "workshop" or "tasm". |
void dkapp_info_file_does_not_exist | ( | dk_app_t * | a, | |
char * | n | |||
) |
Informational message: File does not exist.
a | Application support structure. | |
n | File name. |
void dkapp_info_no_openssl_support | ( | dk_app_t * | a | ) |
Information message: No OpenSSL support available.
a | Application support structure. |
void dkapp_init_key_value | ( | \dk_app_t * | a, | |
dk_key_value_t * | k, | |||
size_t | s, | |||
char * | n, | |||
char ** | b | |||
) |
Find multiple strings.
a | Application support structure. | |
k | Array of key/value pairs, each element must be initialized to contain a string key and a default string. | |
s | The number of elements in k. | |
n | String table name. | |
b | Array of string pointers to receive the results, must have s elements. The array elements are either set to the strings found in the string table or to the defaults provided in k. |
int dkapp_llmax_get | ( | dk_app_t * | a | ) |
Retrieve maximum log message priority found.
a | Application support structure. |
void dkapp_llmax_set | ( | dk_app_t * | a, | |
int | p | |||
) |
Overwrite maximum log message priority found.
Normally there should be no reason to use this function. But you may use this function together with dkapp_set_keep_temp() if you want to keep the temporary directory after the application exits.
a | Application support structure. | |
p | New maximum priority value. |
int dkapp_log_level_in_use | ( | dk_app_t * | a, | |
int | p | |||
) |
Check whether or not a log priority was already used.
This function checks whether there already were log messages of priority p or above.
a | Application support structure. | |
p | Log priority. |
int dkapp_log_msg | ( | dk_app_t * | a, | |
int | p, | |||
char ** | m, | |||
int | n | |||
) |
Log multi-part message.
Write a multi-part log message to the different log destinations.
a | Application support structure. | |
p | Log priority. | |
m | Pointer to array of pointers to messages parts. | |
n | Number of array elements in m. |
dk_app_t* dkapp_open | ( | int | c, | |
char * | v[] | |||
) |
dk_app_t* dkapp_open_ext1 | ( | \int | c, | |
char * | v[], | |||
char * | g, | |||
char * | e, | |||
int | s, | |||
int | n | |||
) |
Create application support structure.
This function creates a new application support structure and returns a pointer to it. Memory needed for the structure is allocated dynamically. Use dkapp_close() to destroy the structure and release the memory after usage.
c | The argc argument of the main() function. | |
v | The argv argument of the main() function. | |
g | Pointer to string, program group name. | |
e | System configuration directory (usually ``/etc''). | |
s | Flag, run silently. | |
n | Use no standard output/standard error output. |
size_t dkapp_prlen | ( | dk_app_t * | a, | |
char * | s | |||
) |
Get number of glyphs to print.
Some encodings -- i.e. UTF-8 -- use multiple bytes for one character/glyph.
a | Application support structure. | |
s | String. |
int dkapp_rand_begin | ( | dk_app_t * | a, | |
int | r | |||
) |
Initialize random number generation seed PRNG.
a | Application support structure. | |
r | Key to indicate which PRNG types are allowed (or-combination of DK_RAND_TYPE_xxx). |
size_t dkapp_rand_bytes | ( | dk_app_t * | a, | |
void * | b, | |||
size_t | s | |||
) |
Obtain random bytes.
a | Application support structure. | |
b | Buffer to receive the bytes. | |
s | Length of b in bytes. |
size_t dkapp_rand_bytes_non_crypto | ( | dk_app_t * | a, | |
void * | b, | |||
size_t | s | |||
) |
Obtain random bytes for non-cryptographic purposes.
a | Application support structure. | |
b | Buffer to receive the bytes. | |
s | Length of b in bytes. |
int dkapp_rand_end | ( | dk_app_t * | a | ) |
End random number generation, save seed and close PRNG.
a | Application support structure. |
int dkapp_rand_types_from_string | ( | dk_app_t * | a, | |
char * | s | |||
) |
Convert string containing list of allowed PRNG types to key.
a | Application support structure. | |
s | Comma-separated list of allowed PRNG types, may include ``openssl'', ``random'', ``rand48'' and ``rand'' or simply ``all''. |
dk_stream_t* dkapp_read_cfg | ( | dk_app_t * | a, | |
char * | n | |||
) |
Search for file and open file for reading.
See ``Search order for dkapp_find_file() and dkapp_find_cfg()'' for a list of directories searched.
a | Application support structure. | |
n | File name. |
dk_stream_t* dkapp_read_file | ( | dk_app_t * | a, | |
char * | n | |||
) |
Open a file for reading, return stream.
a | Application support structure. | |
n | File name. |
dk_stream_t* dkapp_read_file_ext1 | ( | dk_app_t * | a, | |
char * | n, | |||
int * | t | |||
) |
Open a file for reading, return stream.
a | Application support structure. | |
n | File name. | |
t | Pointer to variable to store sub directory type. |
int dkapp_set_groupname | ( | dk_app_t * | a, | |
char * | n | |||
) |
Set application group name for application opened with dkapp_open().
As the group name is unknown while dkapp_open() is running there might be problems finding files in dkapp_open(). I recommend to use dkapp_open_ext1() instead od dkapp_open() and dkapp_set_groupname() to avoid this problem.
a | Application support structure. | |
n | Application group name. |
void dkapp_set_keep_temp | ( | dk_app_t * | a, | |
int | p | |||
) |
Set log message priority required to not delete the temporary directory at the end of the application.
Normally the applications temporary directory (and all it's contents) is removed by dkapp_close() at the end of the application. For debugging purposes you might want to keep the directory for inspection if there were log messages of specific priorities (i.e. errors or worse).
a | Application support structure. | |
p | Log message priority required to keep temporary directory. |
void dkapp_set_nostdio | ( | dk_app_t * | a, | |
int | f | |||
) |
Set no-standard-output flag for application opened with dkapp_open().
When using dkapp_open() and dkapp_set_nostdio() the application will probably report errors to standard output and standard error output while dkapp_open() is running. I recommend to use dkapp_open_ext1() instead and set the no-standard-output flag there.
a | Application support structure. | |
f | New flag value. |
int dkapp_set_pref | ( | dk_app_t * | a, | |
char * | k, | |||
char * | v | |||
) |
Set preference value.
The preference is set in the user|application|* scope. On Windows system the new value is written to the registry immediately. On other systems the configuration entry is kept in memory, the configuration file is updated at the end of the application by the dkapp_close() function.
a | Application support structure. | |
k | Preference name (without scope). | |
v | Preference value. |
void dkapp_set_silent | ( | dk_app_t * | a, | |
int | f | |||
) |
Set silence flag for application opened with dkapp_open().
When using dkapp_open() and dkapp_set_silent() the application will _not_ be in silent mode while dkapp_open() is running. Errors from dkapp_open() will be reported. I recommend to use dkapp_open_ext1() and set the silence flag there.
a | Application support structure. | |
f | New silence flag value. |
void dkapp_set_source_filename | ( | dk_app_t * | a, | |
char * | n | |||
) |
Set name of source file to use in log messages (error position).
Specify the error position (file and line number) before calling dkapp_log_msg() if necessary.
The pointer is stored ``as is'' in the application support structure, no copy is created. As long as the file name in the error position remains the same do not change the buffer n points to.
a | Application support structure. | |
n | Name of source file or NULL (do not show error position). |
void dkapp_set_source_lineno | ( | dk_app_t * | a, | |
unsigned long | l | |||
) |
Set line number to use in log messages (error position).
Specify the error position (file and line number) before calling dkapp_log_msg().
a | Application support structure. | |
l | The line number (or 0 if the line number is not known). |
int dkapp_silence_check | ( | int | argc, | |
char ** | argv | |||
) |
Check command line arguments for --/log/off.
This function can be used to set the s parameter for dkapp_open_ext1().
argc | The argc parameter from the main() function. | |
argv | The argv parameter from the main() function. |
void dkapp_stderr | ( | dk_app_t * | a, | |
char * | s | |||
) |
Print string to standard error output, do codepage translations if necessary.
a | Application support structure. | |
s | String to print. |
void dkapp_stdout | ( | dk_app_t * | a, | |
char * | s | |||
) |
Print a string to standard output, do codepage translations if necessary.
a | Application support structure. | |
s | String to print. |
dk_stream_t* dkapp_stream_openbz2 | ( | dk_app_t * | a, | |
char * | n, | |||
char * | m | |||
) |
Open a file for use with dk_stream_t API (bzip2 compressed file, requires bzip2 support), apply security checks before opening the file.
a | Application support structure. | |
n | File name. | |
m | File open mode (i.e. "r", "w"...). |
dk_stream_t* dkapp_stream_openfile | ( | dk_app_t * | a, | |
char * | n, | |||
char * | m | |||
) |
Open a file for use with dk_stream_t API (plain file), apply security checks before opening the file.
a | Application support structure. | |
n | File name. | |
m | File open mode (i.e. "r", "w"...). |
dk_stream_t* dkapp_stream_opengz | ( | dk_app_t * | a, | |
char * | n, | |||
char * | m | |||
) |
Open a file for use with dk_stream_t API (gzip compressed file, requires gzip support), apply security checks before opening the file.
a | Application support structure. | |
n | File name. | |
m | File open mode (i.e. "r", "w"...). |
int dkapp_tmpnam | ( | dk_app_t * | a, | |
char * | b, | |||
size_t | s | |||
) |
Create name for temporary file.
A file name for a temporary file in the applications temporary directory is created.
a | Application support structure. | |
b | Buffer to receive result. | |
s | Length of buffer b in bytes. |
int dkapp_transform_string | ( | dk_app_t * | a, | |
char * | d, | |||
size_t | l, | |||
char * | s | |||
) |
Transform string (substitute placeholders).
a | Application support structure. | |
d | Destination (pointer to buffer to receive result). | |
l | Size of d in bytes. | |
s | Source string. |
int dkapp_transform_string_ext1 | ( | dk_app_t * | a, | |
char * | d, | |||
size_t | l, | |||
char * | s, | |||
int | f | |||
) |
Transform string, correct slashes/backslashes in file names if necessary.
a | Application support structure. | |
d | Destination (pointer to buffer to receive result). | |
l | Size of d in bytes. | |
s | Source string. | |
f | Flag, the text to transform is a file name. |
void dkapp_unconfigure | ( | dk_app_t * | a | ) |
Set unconfigure flag for the application.
At the end of the application dkapp_close() does not update the configuration file. Instead the configuration file is removed, on Windows systems the registry key is removed.
a | Application support structure. |
dk_stream_t* dkapp_write_file | ( | dk_app_t * | a, | |
char * | n | |||
) |
Open file for writing.
This function opens file to write plain or compressed (gzip or bzip2 for suffixes ``.gz'' or ``.bz2'' if compiled with gzip/bzip2 support).
a | Application support structure. | |
n | File name. |