dkapp.h File Reference

Application functions. More...

#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_tdkapp_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_tdkapp_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_tdkapp_read_file_ext1 (dk_app_t *a, char *n, int *t)
 Open a file for reading, return stream.
dk_stream_tdkapp_read_file (dk_app_t *a, char *n)
 Open a file for reading, return stream.
dk_stream_tdkapp_read_cfg (dk_app_t *a, char *n)
 Search for file and open file for reading.
dk_stream_tdkapp_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_tdkapp_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_tdkapp_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_tdkapp_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.


Detailed Description

Application functions.

Overview

This module provides functions for command line applications such as:

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.

Examples

Example: Opening and closing a normal application. The application group name is "tests". The system configuratin directory is "/etc". There is no need to run silently, the program is free to use stdout and stderr for logging as configured in the program preferences.
  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 Documentation

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


Function Documentation

void dkapp_close ( dk_app_t a  ) 

Destroy application support structure and release memory.

Parameters:
a Pointer to the structure.

void dkapp_err_cwd ( dk_app_t a  ) 

Error message: Failed to find current working directory.

Parameters:
a Application support structure.

void dkapp_err_fopenr ( dk_app_t a,
char *  n 
)

Error message: Failed to open file for reading.

Parameters:
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.

Parameters:
a Application support structure.
n File name.

void dkapp_err_fread ( dk_app_t a,
char *  n 
)

Error message: Error while reading from file.

Parameters:
a Application support structure.
n File name.

void dkapp_err_fwrite ( dk_app_t a,
char *  n 
)

Error message: Error while writing to file.

Parameters:
a Application support structure.
n File name.

void dkapp_err_invalid_owner ( dk_app_t a,
char *  n 
)

Error message: Invalid file owner.

Parameters:
a Application support structure.
n File name.

void dkapp_err_invalid_permissions ( dk_app_t a,
char *  n 
)

Error message: Invalid permissions to file.

Parameters:
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.

Parameters:
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.

Parameters:
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.

Parameters:
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.

Parameters:
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.

Parameters:
a Application support structure.
n File name.

void dkapp_err_no_such_file ( dk_app_t a,
char *  n 
)

Error message: No such file.

Parameters:
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.

Parameters:
a Application support structure.
n File name.

void dkapp_err_not_a_device ( dk_app_t a,
char *  n 
)

Error message: Not a device.

Parameters:
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.

Parameters:
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.

Parameters:
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.

Parameters:
a Application support structure.
n File name.

void dkapp_err_tcpip ( dk_app_t a  ) 

Error message: TCP/IP protocol not available.

Parameters:
a Application support structure.

void dkapp_err_traverse_dir ( dk_app_t a,
char *  n 
)

Error message: Failed to traverse directory.

Parameters:
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.

Parameters:
a Application support structure.
n File name to search for.
b Buffer to receive the result.
s Size of b in bytes.
Returns:
Flag to indicate success. See Search order for dkapp_find_file() and dkapp_find_cfg() for details about the search order.

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.

Parameters:
a Application support structure.
n File name to search for.
Returns:
Pointer to copy of file name found on success, NULL on error. See Search order for dkapp_find_file() and dkapp_find_cfg() for details about the search order.

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.

Parameters:
a Application support structure.
n File name to search for.
b Buffer to receive the result.
s Size of b in bytes.
Returns:
Flag to indicate success. See Search order for dkapp_find_file() and dkapp_find_cfg() for details about the search order.

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.

Parameters:
a Application support structure.
n File name to search for.
Returns:
Pointer to copy of file name found on success, NULL on error. See Search order for dkapp_find_file() and dkapp_find_cfg() for details about the search order.

char** dkapp_find_key_value ( dk_app_t a,
dk_key_value_t k,
size_t  s,
char *  n 
)

Find multiple strings.

Parameters:
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.
Returns:
A char ** pointer (array to pointers of strings). The memory for the pointer array is allocated dynamically, use dk_delete() to release the memory.

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.

Parameters:
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.

Parameters:
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).
Returns:
String found in string table or d. May be NULL.

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.

The function returns a copy of the file name placed in dynamically allocated memory on success. Use dk_delete() to release the memory.

Parameters:
a Application support structure.
f File name expander.
p Pattern to match.
Returns:
Pointer to file name on success, NULL on error. On success use dk_delete() for the pointer to release the memory after usage.

FILE* dkapp_fopen ( dk_app_t a,
char *  n,
char *  m 
)

Open a file, apply security checks before opening the file.

Parameters:
a Application support structure.
n File name.
m File open mode (i.e. "r", "w"...).
Returns:
FILE pointer on success, NULL on error. On success call fclose() on the pointer after usage.

void dkapp_fputs ( dk_app_t a,
char *  s,
FILE *  f 
)

Print string to file, do codepage translations if necessary.

Parameters:
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).

Parameters:
a Application support structure.
Returns:
The application name.

int dkapp_get_argc ( dk_app_t a  ) 

Retrieve number of ``real'' command line arguments (command line options to overwrite preferences removed).

Parameters:
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).

Parameters:
a Application support structure.

int dkapp_get_bool_pref ( dk_app_t a,
char *  k 
)

Retrieve boolean value from preferences.

Parameters:
a Application support structure.
k Preference name.
Returns:
  • -1 if preference not found,
  • 0 if value is false or
  • 1 if value is true.

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.

Parameters:
a Application support structure.
Returns:
The minimum log priority required by any log destination.

int dkapp_get_pref ( dk_app_t a,
char *  k,
char *  b,
size_t  l,
int  x 
)

Get preference.

Parameters:
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).
Returns:
Flag to indicate success.

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:

  • command line options to overwrite preferences
  • environment variable
  • user and system dependant configuration entries.
    Parameters:
    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.
    Returns:
    Flag to indicate success.

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.

Parameters:
a Application support structure.
Returns:
Or-combined DK_SF_SEC_xxx constants for checks to ignore, see dksf.h.

char* dkapp_get_source_filename ( dk_app_t a  ) 

Retrieve source file name for error positions.

Parameters:
a Application support structure.
Returns:
The file name currently configured to show error positions or NULL.

unsigned long dkapp_get_source_lineno ( dk_app_t a  ) 

Retrieve source line number for error positions.

Parameters:
a Application support structure.
Returns:
The line number used in error positions.

unsigned char* dkapp_get_stdout_codepage ( dk_app_t a  ) 

Get pointer to codepage.

Parameters:
a Application support structure.
Returns:
Pointer to 256 byte codepage on success, NULL on error.

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.

Parameters:
a Application support structure.
k Preference name
Returns:
Pointer to string value on success, NULL on error (not found or not enough memory).

unsigned long dkapp_get_ul_pref ( dk_app_t a,
char *  k 
)

Retrieve unsigned long value from preferences.

Parameters:
a Application support structure.
k Preference name.
Returns:
The value. If the preference was not found or is not an unsigned long the function returns 0.

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.

Parameters:
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.

Parameters:
s Name of program to imitate: "gcc", "msvc", "workshop" or "tasm".
Returns:
Numeric key for the type.

void dkapp_info_file_does_not_exist ( dk_app_t a,
char *  n 
)

Informational message: File does not exist.

Parameters:
a Application support structure.
n File name.

void dkapp_info_no_openssl_support ( dk_app_t a  ) 

Information message: No OpenSSL support available.

Parameters:
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.

Parameters:
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.

Parameters:
a Application support structure.
Returns:
The maximum priority of all log messages issued by the application since it was started.

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.

Parameters:
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.

Parameters:
a Application support structure.
p Log priority.
Returns:
Flag, test result.

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.

Parameters:
a Application support structure.
p Log priority.
m Pointer to array of pointers to messages parts.
n Number of array elements in m.
Returns:
Flag to indicate success.

dk_app_t* dkapp_open ( int  c,
char *  v[] 
)

Create application support structure (obsoleted).

Parameters:
c The argc argument of the main() function.
v The argv argument of the main() function.
Returns:
Pointer to new application structure on success, NULL on error.

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.

Parameters:
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.
Returns:
Pointer to new application structure on success, NULL on error.

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.

Parameters:
a Application support structure.
s String.

int dkapp_rand_begin ( dk_app_t a,
int  r 
)

Initialize random number generation seed PRNG.

Parameters:
a Application support structure.
r Key to indicate which PRNG types are allowed (or-combination of DK_RAND_TYPE_xxx).
Returns:
Key to indicate which PRNG type is used (if any) or 0 (if no PRNG can be used and seeded).

size_t dkapp_rand_bytes ( dk_app_t a,
void *  b,
size_t  s 
)

Obtain random bytes.

Parameters:
a Application support structure.
b Buffer to receive the bytes.
s Length of b in bytes.
Returns:
The number of bytes received.

size_t dkapp_rand_bytes_non_crypto ( dk_app_t a,
void *  b,
size_t  s 
)

Obtain random bytes for non-cryptographic purposes.

Parameters:
a Application support structure.
b Buffer to receive the bytes.
s Length of b in bytes.
Returns:
The number of bytes received.

int dkapp_rand_end ( dk_app_t a  ) 

End random number generation, save seed and close PRNG.

Parameters:
a Application support structure.
Returns:
Flag to indicate success.

int dkapp_rand_types_from_string ( dk_app_t a,
char *  s 
)

Convert string containing list of allowed PRNG types to key.

Parameters:
a Application support structure.
s Comma-separated list of allowed PRNG types, may include ``openssl'', ``random'', ``rand48'' and ``rand'' or simply ``all''.
Returns:
Numeric key indicating the allowed PRNG types.

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.

Parameters:
a Application support structure.
n File name.
Returns:
dk_stream_t pointer to read the file on success, NULL on error. On success use dkstream_close() to close the dk_stream_t after usage. See Search order for dkapp_find_file() and dkapp_find_cfg() for details about the search order.

dk_stream_t* dkapp_read_file ( dk_app_t a,
char *  n 
)

Open a file for reading, return stream.

Parameters:
a Application support structure.
n File name.
Returns:
Pointer to stream, use dkstream_close() to close the stream and release memory.

dk_stream_t* dkapp_read_file_ext1 ( dk_app_t a,
char *  n,
int *  t 
)

Open a file for reading, return stream.

Parameters:
a Application support structure.
n File name.
t Pointer to variable to store sub directory type.
Returns:
Pointer to stream, use dkstream_close() to close the stream and release memory.

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.

Parameters:
a Application support structure.
n Application group name.
Returns:
Flag to indicate success.

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).

Parameters:
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.

Parameters:
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.

Parameters:
a Application support structure.
k Preference name (without scope).
v Preference value.
Returns:
Flag to indicate success.

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.

Parameters:
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.

Parameters:
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().

Parameters:
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().

Parameters:
argc The argc parameter from the main() function.
argv The argv parameter from the main() function.
Returns:
Flag to indicate whether --/log/off was found.

void dkapp_stderr ( dk_app_t a,
char *  s 
)

Print string to standard error output, do codepage translations if necessary.

Parameters:
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.

Parameters:
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.

Parameters:
a Application support structure.
n File name.
m File open mode (i.e. "r", "w"...).
Returns:
dk_stream_t pointer on success, NULL on error. On success call dkstream_close() on the dk_stream_t pointer after usage.

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.

Parameters:
a Application support structure.
n File name.
m File open mode (i.e. "r", "w"...).
Returns:
dk_stream_t pointer on success, NULL on error. On success call dkstream_close() on the dk_stream_t pointer after usage.

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.

Parameters:
a Application support structure.
n File name.
m File open mode (i.e. "r", "w"...).
Returns:
dk_stream_t pointer on success, NULL on error. On success call dkstream_close() on the dk_stream_t pointer after usage.

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.

Parameters:
a Application support structure.
b Buffer to receive result.
s Length of buffer b in bytes.
Returns:
Flag to indicate success.

int dkapp_transform_string ( dk_app_t a,
char *  d,
size_t  l,
char *  s 
)

Transform string (substitute placeholders).

Parameters:
a Application support structure.
d Destination (pointer to buffer to receive result).
l Size of d in bytes.
s Source string.
Returns:
Flag to indicate success. See String transformations in the dkapp module for details about string transformations.

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.

Parameters:
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.
Returns:
Flag to indicate success. See String transformations in the dkapp module for details about string transformations.

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.

Parameters:
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).

Parameters:
a Application support structure.
n File name.
Returns:
dk_stream_t pointer to write to on success, NULL on error. On success use dkstream_close() to close the dk_stream_t after usage.


Generated on Thu Feb 25 13:48:24 2010 for dklibs by  doxygen 1.5.8