/**	@file	dk3sf.h	System functions interface.

@section	sfoverview	System functions overview
One of the main goals in the rewrite of dktools from version 2 to version 3
was internationalization and localization.
A programmer has to deal with both "char" and "wchar_t" strings today.
The wchar_t type uses 16 bits on some systems, 32 bits on others.
UTF-16 encoding is used for 16-bit wchar_t data, direct UNICODE encoding
is used for 32-bit wchar_t. When using the char type we can have
different encodings, the most popular are ISO-LATIN-1, UTF-8 and ASCII.

To use localized strings just having string handling routines isn't enough.
We also need system functions, i.e. to open files...

At the time of writing (July 2012) most *x operating systems provide
system functions working with the char data type in ISO-LATIN-1,
UTF-8 and ASCII encoding. On Windows systems the use of wchar_t is
recommended, UTF-16 is used.

For portable programming the dktools libraries use the "dkChar" data
type which is mapped to char on all non-Windows systems and to
wchar_t on Windows systems.

When defining string literals or string constans you can use
dkT('x') or dkT("Some text") to define dkChar strings.

The dk3str.c module provides functions for string handling, the
dk3enc.c module provides functions for conversions between the different
character sizes and encodings. The dk3sf.c module provides system
functions working with the dkChar type.

The module headers contain macros (i.e. dk3sf_fopen_app()) which are
mapped to different functions (i.e. dk3sf_c8_fopen_app() or
dk3sf_c16_fopen_app()) depending on the size of the dkChar character.

@section	sfmacros	Macros

For the functions expecting a dk3_app_t argument as last parameter there
are convenience macros allowing you to omit this parameter.

@section	sfcategory	System functions by category

@subsection	sfcattextfile	Text file I/O.
- dk3sf_inspect_bom_app()\n
  Inspect file, search for byte order marker at the beginning
  of the file and return the encoding used by the file.
- dk3sf_apply_bom_to_file_app()\n
  Set mode for file according to result of dk3sf_inspect_bom_app()
  (Windows only).
- dk3sf_initialize_stdout()\n
  Set up stdout for dkChar text.
- dk3sf_initialize_stderr()\n
  Set up stderr for dkChar text.
- dk3sf_initialize_file()\n
  Set up a file for dkChar text.
- dk3sf_fgets()\n
  Read a dkChar text line from file.
- dk3sf_fputc()\n
  Write a dkChar to file.
- dk3sf_fputs()\n
  Write a dkChar text string to file.
- dk3sf_c8_fputc()\n
  Print 8-bit character to file, convert to 16 bit if necessary.
- dk3sf_c8_fputs()\n
  Print 8-bit string to file, convert to 16 bit if necessary.

@subsection	sfcatbinfile	Binary file I/O
- dk3sf_read_app()\n
  Read bytes into buffer.
- dk3sf_fread_app()\n
  Read elements into buffer.
- dk3sf_write_app()\n
  Write bytes from buffer to file.
- dk3sf_fwrite_app()\n
  Write elements from buffer to file.

@subsection	sfcatdir	Directories
- dk3sf_c8_getcwd_app()\n
  Get current directory name.
- dk3sf_c8_get_home_app()\n
  Find current users home directory.
- dk3sf_c8_mkdir_app()\n
  Create directory if it does not yet exist.
- dk3sf_c8_remove_dir_app()\n
  Remove directory (directory must be empty).
- dk3sf_c16_getcwd_app()\n
  Get current directory name.
- dk3sf_c16_get_home_app()\n
  Find current users home directory.
- dk3sf_c16_mkdir_app()\n
  Create directory if it does not yet exist.
- dk3sf_c16_remove_dir_app()\n
  Remove directory (directory must be empty).

@subsection	sfcatfile	Files
- dk3sf_c8_stat_app()\n
  Obtain information about a file.
- dk3sf_c8_fopen_app()\n
  Open a file.
- dk3sf_c8_find_exec_app()\n
  Find name of executable file.
- dk3sf_c8_remove_file_app()\n
  Remove a file.
- dk3sf_c16_stat_app()\n
  Obtain information about a file.
- dk3sf_c16_fopen_app()\n
  Open a file.
- dk3sf_c16_find_exec_app()\n
  Find name of executable file.
- dk3sf_c16_remove_file_app()\n
  Remove a file.
- dk3sf_must_expand()\n
  Check whether a file name must be expanded. On some systems the shell
  does not expand file names like "*.h" itself, this command line argument
  is passed to the program as is instead. So the program must check
  whether or not it must expand a file name using the
  dk3dir_fne_open_app() function.

@subsection	sfcatnames	Names
- dk3sf_c8_get_hostname_app()\n
  Get current hostname (short hostname without DNS domain).
- dk3sf_c8_get_logname_app()\n
  Get current users login name.
- dk3sf_c8_getenv()\n
  Retrieve value from environment variable.
- dk3sf_c16_get_hostname_app()\n
  Get current hostname (short hostname without DNS domain).
- dk3sf_c16_get_logname_app()\n
  Get current users login name.
- dk3sf_c16_getenv()\n
  Retrieve value from environment variable.

@subsection	sfcattime	Time functions
- dk3sf_time()\n
  Get current time.
- dk3sf_c8_time_convert_app()\n
  Convert timestamp to text.
- dk3sf_c16_time_convert_app()\n
  Convert timestamp to text.

@subsection	sfcatinfo	Other information
- dk3sf_getpid()\n
  Get process ID of current process.

*/