Merge branch 'release/debian/4.10-1'debian/4.10-1

1 files changed, 0 insertions, 24663 deletions

diff --git a/doc/libHX_Documentation.lyx b/doc/libHX_Documentation.lyx
deleted file mode 100644
index 9e2e9f5..0000000
--- a/doc/libHX_Documentation.lyx
+++ /dev/null
@@ -1,24663 +0,0 @@
-#LyX 2.3 created this file. For more info see http://www.lyx.org/
-\lyxformat 544
-\begin_document
-\begin_header
-\save_transient_properties true
-\origin unavailable
-\textclass article
-\use_default_options true
-\maintain_unincluded_children false
-\language english
-\language_package default
-\inputencoding utf8
-\fontencoding global
-\font_roman "lmodern" "default"
-\font_sans "lmss" "default"
-\font_typewriter "lmtt" "default"
-\font_math "auto" "auto"
-\font_default_family default
-\use_non_tex_fonts false
-\font_sc false
-\font_osf false
-\font_sf_scale 100 100
-\font_tt_scale 100 100
-\use_microtype false
-\use_dash_ligatures true
-\graphics default
-\default_output_format default
-\output_sync 0
-\bibtex_command default
-\index_command default
-\paperfontsize 12
-\spacing single
-\use_hyperref true
-\pdf_bookmarks false
-\pdf_bookmarksnumbered false
-\pdf_bookmarksopen false
-\pdf_bookmarksopenlevel 1
-\pdf_breaklinks false
-\pdf_pdfborder true
-\pdf_colorlinks false
-\pdf_backref page
-\pdf_pdfusetitle true
-\papersize a4paper
-\use_geometry true
-\use_package amsmath 1
-\use_package amssymb 1
-\use_package cancel 1
-\use_package esint 1
-\use_package mathdots 1
-\use_package mathtools 1
-\use_package mhchem 1
-\use_package stackrel 1
-\use_package stmaryrd 1
-\use_package undertilde 1
-\cite_engine natbib
-\cite_engine_type numerical
-\biblio_style plainnat
-\use_bibtopic false
-\use_indices false
-\paperorientation portrait
-\suppress_date false
-\justification true
-\use_refstyle 0
-\use_minted 0
-\index Index
-\shortcut idx
-\color #008000
-\end_index
-\leftmargin 2cm
-\topmargin 2cm
-\rightmargin 2cm
-\bottommargin 2cm
-\secnumdepth 3
-\tocdepth 1
-\paragraph_separation indent
-\paragraph_indentation default
-\is_math_indent 0
-\math_numbering_side default
-\quotes_style english
-\dynamic_quotes 0
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\tracking_changes false
-\output_changes false
-\html_math_output 0
-\html_css_as_file 0
-\html_be_strict false
-\end_header
-
-\begin_body
-
-\begin_layout Title
-libHX 3.25
-\begin_inset Newline newline
-\end_inset
-
-Documentation
-\end_layout
-
-\begin_layout Standard
-\begin_inset VSpace defskip
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset CommandInset toc
-LatexCommand tableofcontents
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Introduction
-\end_layout
-
-\begin_layout Standard
-libHX collects many useful day-to-day functions, intended to reduce the
- amount of otherwise repeatedly open-coded instructions.
-\end_layout
-
-\begin_layout Section
-Overview
-\end_layout
-
-\begin_layout Itemize
-Maps (key-value pairs) (section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:maps"
-
-\end_inset
-
-)
-\begin_inset Newline newline
-\end_inset
-
-Originally created to provide a data structure like Perl's associative arrays.
- Different map types and characteristics are available, such as hash-based
- or the traditional rbtree.
-\end_layout
-
-\begin_layout Itemize
-Deques (section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:deque"
-
-\end_inset
-
-)
-\begin_inset Newline newline
-\end_inset
-
-Double-ended queues, implemented as a doubly-linked list with sentinels,
- are suitable for both providing stack and queue functionality.
-\end_layout
-
-\begin_layout Itemize
-Inline doubly-linked list, uncounted and counted (sections
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:list"
-
-\end_inset
-
- and
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:clist"
-
-\end_inset
-
-)
-\begin_inset Newline newline
-\end_inset
-
-Light-weight linked lists as used in the Linux kernel.
-\end_layout
-
-\begin_layout Itemize
-Common string operations (section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:strings"
-
-\end_inset
-
-)
-\begin_inset Newline newline
-\end_inset
-
-basename, chomp, dirname, getl(ine), split, strlcat/strlcpy, strlower/-upper,
- str*trim, strsep, etc.
-\end_layout
-
-\begin_layout Itemize
-Memory containers, auto-sizing string operations (section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:mc"
-
-\end_inset
-
-)
-\begin_inset Newline newline
-\end_inset
-
-Scripting-like invocation for string handling
-\begin_inset space ~
-\end_inset
-
-— automatically doing (re)allocations as needed.
-\end_layout
-
-\begin_layout Itemize
-String formatter (section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:format"
-
-\end_inset
-
-)
-\begin_inset Newline newline
-\end_inset
-
-HXfmt is a small template system for by-name variable expansion.
- It can be used to substitute placeholders in format strings supplied by
- the user by appropriate expanded values defined by the program.
-\end_layout
-
-\begin_layout Itemize
-Directory creation, traversal, removal, and file copying (sections
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:dir-ops1"
-
-\end_inset
-
-, 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:dir-ops2"
-
-\end_inset
-
- and
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:file-ops"
-
-\end_inset
-
-)
-\end_layout
-
-\begin_layout Itemize
-Option parsing (section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:option"
-
-\end_inset
-
-)
-\begin_inset Newline newline
-\end_inset
-
-Table-/callback-based option parser that works similar to Perl's 
-\family typewriter
-Getopt::Long
-\family default
-
-\begin_inset space ~
-\end_inset
-
-— no open-coding but a single 
-\begin_inset Quotes eld
-\end_inset
-
-atomic
-\begin_inset Quotes erd
-\end_inset
-
- invocation.
-\end_layout
-
-\begin_layout Itemize
-Shell-style config parser (section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:shconf"
-
-\end_inset
-
-)
-\begin_inset Newline newline
-\end_inset
-
-Configuration file reader for Shell-style 
-\begin_inset Quotes eld
-\end_inset
-
-configuration
-\begin_inset Quotes erd
-\end_inset
-
- files with key-value pairs, as usually foudn in 
-\family typewriter
-/etc\SpecialChar breakableslash
-sysconfig
-\family default
-.
-\end_layout
-
-\begin_layout Itemize
-Random number gathering (section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:random"
-
-\end_inset
-
-)
-\begin_inset Newline newline
-\end_inset
-
-Convenient wrapper that uses kernel-provided RNG devices when available.
-\end_layout
-
-\begin_layout Itemize
-External process invocation (section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:proc"
-
-\end_inset
-
-)
-\begin_inset Newline newline
-\end_inset
-
-Setting up pipes for the standard file descriptors for sending/capturing
- data to/from a program.
-\end_layout
-
-\begin_layout Itemize
-
-\shape italic
-a bit more beyond that ...
- Miscellaneous
-\end_layout
-
-\begin_layout Section
-Resources
-\end_layout
-
-\begin_layout Standard
-As of this writing, the repository is located at
-\end_layout
-
-\begin_layout Itemize
-\begin_inset Flex URL
-status open
-
-\begin_layout Plain Layout
-
-git://libhx.git.sf.net/gitroot/libhx/libhx
-\end_layout
-
-\end_inset
-
-
-\begin_inset space ~
-\end_inset
-
-— clone URL
-\end_layout
-
-\begin_layout Itemize
-\begin_inset Flex URL
-status open
-
-\begin_layout Plain Layout
-
-http://libhx.git.sf.net/
-\end_layout
-
-\end_inset
-
-
-\begin_inset space ~
-\end_inset
-
-— gitweb interface
-\end_layout
-
-\begin_layout Itemize
-\begin_inset Flex URL
-status open
-
-\begin_layout Plain Layout
-
-http://libhx.sf.net/
-\end_layout
-
-\end_inset
-
-
-\begin_inset space ~
-\end_inset
-
-— home page (and link to tarballs)
-\end_layout
-
-\begin_layout Itemize
-\begin_inset Flex URL
-status open
-
-\begin_layout Plain Layout
-
-http://freecode.com/projects/libhx/
-\end_layout
-
-\end_inset
-
-
-\begin_inset space ~
-\end_inset
-
-— Freecode page (useful for automatic notification of new releases)
-\end_layout
-
-\begin_layout Section
-Installation
-\end_layout
-
-\begin_layout Standard
-libHX uses GNU autotools as a build environment, which means that all you
- have to run as a end-user is the 
-\family typewriter
-configure
-\family default
- with any options that you need, plus the usual 
-\family typewriter
-make
-\family default
- and 
-\family typewriter
-make install
-\family default
- as desired.
-\end_layout
-
-\begin_layout Standard
-Pay attention to multi-lib Linux distributions where you most likely need
- to specify a different libdir instead of using the default 
-\begin_inset Quotes eld
-\end_inset
-
-lib
-\begin_inset Quotes erd
-\end_inset
-
-.
- In case of the Debian-style multi-arch/multi-lib proposal (
-\begin_inset Flex URL
-status collapsed
-
-\begin_layout Plain Layout
-
-http://wiki.debian.org/Multiarch
-\end_layout
-
-\end_inset
-
-):
-\end_layout
-
-\begin_layout LyX-Code
-$ 
-\series bold
-./configure --libdir='${prefix}/lib/x86_64-linux-gnu'
-\end_layout
-
-\begin_layout Standard
-and the classic-style 32-64 2-lib distributions:
-\end_layout
-
-\begin_layout LyX-Code
-$ 
-\series bold
-./configure --libdir='${prefix}/lib64'
-\end_layout
-
-\begin_layout Subsection
-Requirements
-\end_layout
-
-\begin_layout Itemize
-GNU C Compiler 3.3.5 or newer.
- Other compilers (non-GCC) have not been tested in months
-\begin_inset space ~
-\end_inset
-
-— use at your own risk.
-\end_layout
-
-\begin_layout Itemize
-approximately 80–160
-\begin_inset space ~
-\end_inset
-
-KB of disk space on Linux for the shared library (depends on platform) and
- header files.
-\end_layout
-
-\begin_layout Standard
-A C++ compiler is only needed if you want to build the C++ test programs
- that come with libHX.
- By default, if there is no C++ compiler present, these will not be built.
-\end_layout
-
-\begin_layout Itemize
-No external libraries are needed for compilation of libHX.
- Helper files, like 
-\family typewriter
-libxml_\SpecialChar softhyphen
-helper.h
-\family default
-, may reference their include files, but they are not used during compilation.
-\end_layout
-
-\begin_layout Section
-Portability notice
-\end_layout
-
-\begin_layout Standard
-libHX runs on contemporary versions of Linux, Solaris and the three BSD
- distributions.
- It might even work on Microsoft Windows, but this is not tested very often,
- if at all.
- Overly old systems, especially Unices, are not within focus.
- While AIX
-\begin_inset space ~
-\end_inset
-
-5.3 might still classify as contemporary, strangelets like 
-\begin_inset Quotes eld
-\end_inset
-
-Ultrix
-\begin_inset Quotes erd
-\end_inset
-
- or 
-\begin_inset Quotes eld
-\end_inset
-
-Dynix
-\begin_inset Quotes erd
-\end_inset
-
- you can find in the autotools-related file 
-\family typewriter
-config.guess
-\family default
- are some that are definitely not.
-\end_layout
-
-\begin_layout Standard
-Furthermore, a compiler that understands the C99 or GNU89 standard is required.
- The integer type 
-\begin_inset Quotes eld
-\end_inset
-
-int
-\begin_inset Quotes erd
-\end_inset
-
- should at best have 32 bits at least.
- There is no ultra-portable version as of this writing, but feel free to
- start one akin to the 
-\begin_inset Quotes eld
-\end_inset
-
-p
-\begin_inset Quotes erd
-\end_inset
-
- variants of OpenBSD software such as OpenSSH.
-\end_layout
-
-\begin_layout Section
-History
-\end_layout
-
-\begin_layout Standard
-The origins of libHX trace back, even crossing a language boundary, to when
- the author started on using Perl in 1999.
- Some tasks were just too damn useful to be open-coded every time.
- Two such examples are what is these days known as 
-\family typewriter
-HX_basename
-\family default
- and 
-\family typewriter
-HX_mkdir
-\family default
-.
- The name does not relate to anyone's initials; it is a result of a truncation
- of the author's nick used years ago.
-\end_layout
-
-\begin_layout Standard
-Around the beginning of 2003, the author also started on the C programming
- language and soon the small library was converted from Perl to C.
- The libHX library as of today is the result of working with C ever since,
- and naturally grew from there to support whatever the author was in need
- of.
-\end_layout
-
-\begin_layout Standard
-The 
-\begin_inset Quotes eld
-\end_inset
-
-correct
-\begin_inset Quotes erd
-\end_inset
-
- name for libHX is with an uppercase 
-\begin_inset Quotes eld
-\end_inset
-
-H
-\begin_inset Quotes erd
-\end_inset
-
- and uppercase 
-\begin_inset Quotes eld
-\end_inset
-
-X
-\begin_inset Quotes erd
-\end_inset
-
-, and the same is used for filenames, such as 
-\begin_inset Quotes eld
-\end_inset
-
-libHX.so
-\begin_inset Quotes erd
-\end_inset
-
-
-\begin_inset Foot
-status open
-
-\begin_layout Plain Layout
-Software projects may choose to entirely lowercase the project name for
- use in filenames, such as the Linux kernel which is released as 
-\family typewriter
-linux-${
-\family default
-\shape italic
-version
-\family typewriter
-\shape default
-}.tar.bz2
-\family default
-, or the project may choose to keep the name for filenames, like Mesa and
- SDL do.
- libHX is of the latter.
-\end_layout
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Part
-General
-\end_layout
-
-\begin_layout Standard
-Many functions are prefixed with 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-HX_
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- or 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-HXsubsys_
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-, as are structures (sometimes without underscores, be sure to check the
- syntax and names), to avoid name clashes with possibly existing files.
- Functions that are not tied to a specific data structure such as most of
- the string functions (see chapter
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:strings"
-
-\end_inset
-
-) use the subsystem-less prefix, 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-HX_
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-.
- Functions from a clearly-defined subsystem, such as map or deque, augment
- the base prefix by a suffix, forming e.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
-\begin_inset space \space{}
-\end_inset
-
-
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-HXmap_
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Section
-Initialization
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/init.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_init(
-\series bold
-void
-\series default
-);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX_init
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HX_exit(
-\series bold
-void
-\series default
-);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX_exit
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Before using the library's functions, 
-\family typewriter
-HX_init
-\family default
- must be called.
- This function will initialize any needed state libHX needs for itself,
- if any.
- It is designed to be invoked multiple times, such as for example, from
- different libraries linking to libHX itself, and will refcount.
- On success, >0 is returned.
- If there was an error, it will return a negative error code or zero.
- 
-\family typewriter
-HX_exit
-\family default
- is the logical counterpart of notifying that the library is no longer used.
-\end_layout
-
-\begin_layout Section
-Type-checking casts
-\end_layout
-
-\begin_layout Standard
-The C++ language provides so-called 
-\begin_inset Quotes eld
-\end_inset
-
-new-style casts
-\begin_inset Quotes erd
-\end_inset
-
-, referring to the four template-looking invocations 
-\family typewriter
-static_cast<>
-\family default
-, 
-\family typewriter
-const_cast<>
-\family default
-, 
-\family typewriter
-reinterpret_cast<>
-\family default
- and 
-\family typewriter
-dynamic_cast<>
-\family default
-.
- No such blessing was given to the C language, but still, even using macros
- that expand to the olde cast make it much easier to find casts in source
- code and annotate why something was casted, which is already an improvement.
-\begin_inset space ~
-\end_inset
-
-— Actually, it 
-\shape italic
-is
-\shape default
- possible to do a some type checking, using some GCC extensions, which augments
- these macros from their documentary nature to an actual safety measure.
-\end_layout
-
-\begin_layout Subsection
-
-\family typewriter
-reinterpret_cast
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-reinterpret_cast
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-reinterpret_cast()
-\family default
- maps directly to the old-style typecast, 
-\family typewriter
-(type)(expr)
-\family default
-, and causes the bit pattern for the expr rvalue to be 
-\begin_inset Quotes eld
-\end_inset
-
-reinterpreted
-\begin_inset Quotes erd
-\end_inset
-
- as a new type.
- You will notice that 
-\begin_inset Quotes eld
-\end_inset
-
-reinterpret
-\begin_inset Quotes erd
-\end_inset
-
- is the longest of all the 
-\family typewriter
-*_cast
-\family default
- names, and can easily cause your line to grow to 80 columns (the good maximum
- in many style guides).
- As a side effect, it is a good indicator that something potentially dangerous
- might be going on, for example converting intergers from/to pointer.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/defs.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/defs.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-
-\begin_inset Newline newline
-\end_inset
-
-int
-\series default
- i;
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-Tree with numeric keys
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-tree = HXhashmap_init(0);
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-for
-\series default
- (i = 0; i < 6; ++i)
-\begin_inset Newline newline
-\end_inset
-
-        HXmap_add(tree, 
-\series bold
-reinterpret_cast
-\series default
-(
-\series bold
-void *
-\series default
-,
-\begin_inset Newline newline
-\end_inset
-
-                  
-\series bold
-static_cast
-\series default
-(
-\series bold
-long
-\series default
-, i)), my_data);
-\end_layout
-
-\begin_layout Subsection
-
-\family typewriter
-signed_cast
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-signed_cast
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-This tag is for annotating that the cast was solely done to change the signednes
-s of pointers to char
-\begin_inset space ~
-\end_inset
-
-— and only those.
- No integers etc.
- The intention is to facilitate working with libraries that use 
-\family typewriter
-unsigned char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
- pointers, such as libcrypto and libssl (from the OpenSSL project) or libxml2,
- for example.
- See table
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "tab:defs-signed_cast"
-
-\end_inset
-
- for the allowed conversions.
- C++ does 
-\shape italic
-not
-\shape default
- actually have a 
-\family typewriter
-signed_cast<>
-\family default
-, and one would have to use 
-\family typewriter
-reinterpret_cast<>
-\family default
- to do the conversion, because 
-\family typewriter
-static_cast<>
-\family default
- does not allow conversion from 
-\family typewriter
-const char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
- to 
-\family typewriter
-const unsigned char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-, for example.
- (libHX's 
-\family typewriter
-static_cast()
-\family default
- would also throw at least a compiler warning about the different signedness.)
- libHX does provide a 
-\family typewriter
-signed_cast<>
-\family default
- for C++ though.
- This is where 
-\family typewriter
-signed_cast
-\family default
- comes in.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float table
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Tabular
-<lyxtabular version="3" rows="7" columns="7">
-<features tabularvalignment="middle">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="top">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-From 
-\backslash
- To
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-c*
-\series default
-section
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-sc*
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-uc*
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Cc*
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Csc*
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Cuc*
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series bold
-char *
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series bold
-signed char *
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series bold
-unsigned char *
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series bold
-const char *
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-–
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-–
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-–
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series bold
-const signed char *
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-–
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-–
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-–
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series bold
-const unsigned char *
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-–
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-–
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-–
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\checkmark$
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption Standard
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "tab:defs-signed_cast"
-
-\end_inset
-
-Accepted conversions for 
-\family typewriter
-signed_cast()
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-
-\family typewriter
-static_cast
-\begin_inset CommandInset label
-LatexCommand label
-name "subsec:defs-static_cast"
-
-\end_inset
-
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-static_cast
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Just like C++'s 
-\family typewriter
-static_cast<>
-\family default
-, libHX's 
-\family typewriter
-static_cast()
-\family default
- verifies that 
-\family typewriter
-expr
-\family default
- can be implicitly converted to the new type (by a simple 
-\family typewriter
-b
-\begin_inset space ~
-\end_inset
-
-=
-\begin_inset space ~
-\end_inset
-
-a
-\family default
-).
- Such is mainly useful for forcing a specific type, as is needed in varargs
- functions such as 
-\family typewriter
-printf
-\family default
-, and where the conversion actually incurs other side effects, such as truncatio
-n or promotion:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-Convert to a type printf knows about
-\family default
-\series bold
-\shape default
- */
-\begin_inset Newline newline
-\end_inset
-
-uint64_t
-\series default
- x = something;
-\begin_inset Newline newline
-\end_inset
-
-printf("%llu
-\backslash
-n", 
-\series bold
-static_cast
-\series default
-(
-\series bold
-unsigned long long
-\series default
-, x));
-\end_layout
-
-\begin_layout Standard
-Because there is no format specifier for 
-\family typewriter
-uint64_t
-\family default
- for 
-\family typewriter
-printf
-\family default
-, a conversion to an accepted type is necessary to not cause undefined behavior.
- The author has seen code that did, for example, 
-\family typewriter
-printf("%u")
-\family default
- on a 
-\begin_inset Quotes eld
-\end_inset
-
-long
-\begin_inset Quotes erd
-\end_inset
-
-, which only works on architectures where 
-\family typewriter
-sizeof(unsigned int)
-\family default
- happens to equal 
-\family typewriter
-sizeof(unsigned long)
-\family default
-, such as x86_32.
- On x86_64, an 
-\family typewriter
-unsigned long
-\family default
- is usually twice as big as an 
-\family typewriter
-unsigned int
-\family default
-, so that 8 bytes are pushed onto the stack, but 
-\family typewriter
-printf
-\family default
- only unshifts 4 bytes because the developer used 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-%u
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-, leading to misreading the next variable on the stack.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-Force promotion
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-double
-\series default
- a_quarter = 
-\series bold
-static_cast
-\series default
-(
-\series bold
-double
-\series default
-, 1) / 4;
-\end_layout
-
-\begin_layout Standard
-Were 
-\begin_inset Quotes eld
-\end_inset
-
-1
-\begin_inset Quotes erd
-\end_inset
-
- not promoted to double, the result in 
-\family typewriter
-q
-\family default
- would be zero because 1/4 is just an integer division, yielding zero.
- By making one of the operands a floating-point quantity, the compiler will
- instruct the FPU to compute the result.
- Of course, one could have also written 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-1.0
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- instead of 
-\family typewriter
-static_cast(double, 1)
-\family default
-, but this is left for the programmer to decide which style s/he prefers.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-Force truncation before invoking second sqrt
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-double
-\series default
- f = sqrt(
-\series bold
-static_cast
-\series default
-(
-\series bold
-int
-\series default
-, 10 * sqrt(3.0 / 4)));
-\end_layout
-
-\begin_layout Standard
-And here, the conversion from 
-\family typewriter
-double
-\family default
- to 
-\family typewriter
-int
-\family default
- incurs a (wanted) truncation of the decimal fraction, that is, rounding
- down for positive numbers, and rounding up for negative numbers.
-\end_layout
-
-\begin_layout Subsubsection
-Allowed conversions
-\end_layout
-
-\begin_layout Itemize
-
-\series bold
-Numbers
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-Conversion between numeric types, such as 
-\family typewriter
-char
-\family default
-, 
-\family typewriter
-short
-\family default
-, 
-\family typewriter
-int
-\family default
-, 
-\family typewriter
-long
-\family default
-, 
-\family typewriter
-long long
-\family default
-, 
-\family typewriter
-int
-\shape italic
-N
-\shape default
-_t
-\family default
-, both their signed and unsigned variants, 
-\family typewriter
-float
-\family default
- and 
-\family typewriter
-double
-\family default
-.
-\end_layout
-
-\begin_layout Itemize
-
-\series bold
-Generic Pointer
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-Conversion from 
-\family typewriter
-type
-\begin_inset space ~
-\end_inset
-
-*
-\family default
- to and from 
-\family typewriter
-void
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-.
- (Where 
-\family typewriter
-type
-\family default
- may very well be a type with further indirection.)
-\end_layout
-
-\begin_layout Itemize
-
-\series bold
-Generic Pointer (const)
-\begin_inset Newline newline
-\end_inset
-
-
-\series default
-Conversion from 
-\family typewriter
-const type
-\begin_inset space ~
-\end_inset
-
-*
-\family default
- to and from 
-\family typewriter
-const void
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-
-\family typewriter
-const_cast
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-const_cast
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-const_cast
-\family default
- allows to add or remove 
-\begin_inset Quotes eld
-\end_inset
-
-const
-\begin_inset Quotes erd
-\end_inset
-
- qualifiers from the type a pointer is pointing to.
- Due to technical limitations, it could not be implemented to support arbitrary
- indirection.
- Instead, 
-\family typewriter
-const_cast
-\family default
- comes in three variants, to be used for indirection levels of 1 to 3:
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-\series bold
-const_cast
-\series default
-1(
-\series bold
-type
-\begin_inset space ~
-\end_inset
-
-*
-\series default
-, expr)
-\family default
- with 
-\family typewriter
-\series bold
-typeof
-\series default
-(expr)
-\begin_inset space ~
-\end_inset
-
-= 
-\series bold
-type
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-\series default
-.
- (Similarly for any combinations of const.)
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-\series bold
-const_cast
-\series default
-2(
-\series bold
-type
-\begin_inset space ~
-\end_inset
-
-**
-\series default
-, expr) with 
-\series bold
-typeof
-\series default
-(expr)
-\begin_inset space ~
-\end_inset
-
-= 
-\series bold
-type
-\begin_inset space ~
-\end_inset
-
-**
-\family default
-\series default
- (and all combinations of const in all possible locations).
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-\series bold
-const_cast
-\series default
-3(
-\series bold
-type
-\begin_inset space ~
-\end_inset
-
-***
-\series default
-, expr) with 
-\series bold
-typeof
-\series default
-(expr)
-\begin_inset space ~
-\end_inset
-
-= 
-\series bold
-type
-\begin_inset space ~
-\end_inset
-
-***
-\family default
-\series default
- (and all combinations...).
-\end_layout
-
-\begin_layout Standard
-As indirection levels above 3 are really unlikely
-\begin_inset Foot
-status open
-
-\begin_layout Plain Layout
-See 
-\begin_inset Quotes eld
-\end_inset
-
-Three Star Programmer
-\begin_inset Quotes erd
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-, having only these three type-checking cast macros was deemed sufficient.
- The only place where libHX even uses a level\SpecialChar nobreakdash
-3 indirection is in the option
- parser.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Tabular
-<lyxtabular version="3" rows="2" columns="2">
-<features tabularvalignment="middle">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="top">
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-int **
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-int *const *
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-const int **
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-const int *const *
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption Standard
-
-\begin_layout Plain Layout
-Accepted expr/target types for 
-\family typewriter
-const_cast2
-\family default
-; example for the 
-\begin_inset Quotes eld
-\end_inset
-
-int
-\begin_inset Quotes erd
-\end_inset
-
- type
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\align center
-Conversion is permitted when expression and target type are from the table.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-It is currently not possible to use 
-\family typewriter
-const_cast
-\family default
-1/2/3 on pointers to structures whose member structure is unknown.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Macros
-\end_layout
-
-\begin_layout Standard
-All macros in this section are available through 
-\family typewriter
-#include <libHX/defs.h>
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/defs.h
-\end_layout
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsection
-Preprocessor
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#define
-\series default
- HX_STRINGIFY(s)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_STRINGIFY
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Transforms the expansion of the argument 
-\family typewriter
-s
-\family default
- into a C string.
-\end_layout
-
-\begin_layout Subsection
-Sizes
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#define
-\series default
- HXSIZEOF_Z16
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXSIZEOF_Z16
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#define
-\series default
- HXSIZEOF_Z32
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXSIZEOF_Z32
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#define
-\series default
- HXSIZEOF_Z64
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXSIZEOF_Z64
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Expands to the size needed for a buffer (including '
-\family typewriter
-
-\backslash
-0
-\family default
-') to hold the base-10 string representation of a 16\SpecialChar nobreakdash
-, 32\SpecialChar nobreakdash
- or 64\SpecialChar nobreakdash
-bit integer.
-\end_layout
-
-\begin_layout Subsection
-Locators
-\end_layout
-
-\begin_layout LyX-Code
-output_type 
-\series bold
-*
-\series default
-containerof(
-\series bold
-input_type *
-\series default
-ptr, output_type, member);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-containerof
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-size_t
-\series default
- HXsizeof_member(struct_type, member);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXsizeof_member
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-output_type HXtypeof_member(struct_type, member);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXtypeof_member
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-containerof
-\family default
- will return a pointer to the struct in which 
-\family typewriter
-ptr
-\family default
- is contained as the given member.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- foo {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-int
-\series default
- bar;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-int
-\series default
- baz;
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static void
-\series default
- test(
-\series bold
-int *
-\series default
-ptr)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- foo 
-\series bold
-*
-\series default
-self = containerof(baz, 
-\series bold
-struct
-\series default
- foo, baz);
-\begin_inset Newline newline
-\end_inset
-
-}
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HXsizeof_member
-\family default
- and 
-\family typewriter
-HXtypeof_member
-\family default
- are shortcuts (mainly for the C language) to get the size or type of a
- named member in a given struct:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-char
-\series default
- padding[FIELD_SIZEOF(
-\series bold
-struct
-\series default
- foo, baz)];
-\end_layout
-
-\begin_layout Standard
-In C++, one can simply use 
-\family typewriter
-sizeof(foo::baz)
-\family default
- and 
-\family typewriter
-decltype(foo::baz)
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-Array size
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-size_t
-\series default
- ARRAY_SIZE(
-\series bold
-type
-\series default
- array
-\series bold
-[]
-\series default
-); 
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-implemented as a macro
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-ARRAY_SIZE
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Returns the number of elements in 
-\family typewriter
-array
-\family default
-.
- This only works with true arrays (
-\family typewriter
-type[]
-\family default
-), and will not output a meaningful value when used with a pointer-to-element
- (
-\family typewriter
-type
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-), which is often used for array access too.
-\end_layout
-
-\begin_layout Subsection
-Compile-time build checks
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-int
-\series default
- BUILD_BUG_ON_EXPR(
-\series bold
-bool
-\series default
- condition); 
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-implemented as a macro
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-BUILD_BUG_ON_EXPR
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- BUILD_BUG_ON(
-\series bold
-bool
-\series default
- condition); 
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-implemented as a macro
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-BUILD_BUG_ON
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Causes the compiler to fail when 
-\family typewriter
-condition
-\family default
- evaluates to true.
- If not implemented for a compiler, it will be a no-op.
- 
-\family typewriter
-BUILD_BUG_ON
-\family default
- is meant to be used as a standalone statement, while 
-\family typewriter
-BUILD_\SpecialChar softhyphen
-BUG_\SpecialChar softhyphen
-ON_\SpecialChar softhyphen
-EXPR
-\family default
- is for when a check is to occur within an expression, that latter of which
- is useful for within macros when one cannot, or does not want to use multiple
- statements.
-\end_layout
-
-\begin_layout LyX-Code
-type DEMOTE_TO_PTR(type expr); 
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-macro
-\family default
-\series bold
-\shape default
- */
-\end_layout
-
-\begin_layout Standard
-Changes the type of expr to pointer type: If 
-\family typewriter
-expr
-\family default
- of array type class, changes it to a pointer to the first element.
- If 
-\family typewriter
-expr
-\family default
- of function type class, changes it to a pointer to the function.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-int
-\series default
- main(
-\series bold
-void
-\series default
-);
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int (*
-\series default
-fp
-\series bold
-)
-\series default
-(
-\series bold
-void
-\series default
-);
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char
-\series default
- a
-\series bold
-[
-\series default
-123
-\series bold
-]
-\series default
-;
-\begin_inset Newline newline
-\end_inset
-
-DEMOTE_TO_PTR(main); 
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-yields 
-\series bold
-int (*)
-\series default
-(
-\series bold
-void
-\series default
-);
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-DEMOTE_TO_PTR(fp);   
-\series bold
-/* 
-\series default
-also yields 
-\family roman
-\series bold
-\shape italic
-int (*)
-\series default
-(
-\series bold
-void
-\series default
-);
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-DEMOTE_TO_PTR(a);    
-\series bold
-/* 
-\series default
-yields 
-\family roman
-\series bold
-\shape italic
-char *
-\family default
-\shape default
- */
-\end_layout
-
-\begin_layout Subsection
-UNIX file modes
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#define
-\series default
- S_IRUGO   (S_IRUSR | S_IRGRP | S_IROTH)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-S_IRUGO
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#define
-\series default
- S_IWUGO   (S_IWUSR | S_IWGRP | S_IWOTH)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-S_IWUGO
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#define
-\series default
- S_IXUGO   (S_IXUSR | S_IXGRP | S_IXOTH)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-S_IXUGO
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#define
-\series default
- S_IRWXUGO (S_IRUGO | S_IWUGO | S_IXUGO)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-S_IRWXUGO
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The defines make it vastly easier to specify permissions for large group
- of users.
- For example, if one wanted to create a file with the permissions 
-\family typewriter
-rw-r--r--
-\family default
- (ignoring the umask in this description), 
-\family typewriter
-S_IRUSR
-\begin_inset space ~
-\end_inset
-
-| S_IWUSR
-\family default
- can now be used instead of the longer 
-\family typewriter
-S_IRUSR
-\begin_inset space ~
-\end_inset
-
-| S_IWUSR
-\begin_inset space ~
-\end_inset
-
-| S_IRGRP
-\begin_inset space ~
-\end_inset
-
-| S_IROTH
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-VC runtime format specifiers
-\end_layout
-
-\begin_layout Standard
-The Microsoft Visual C runtime (a weak libc) uses non-standard format specifiers
- for certain types.
- Whereas C99 specifies 
-\begin_inset Quotes eld
-\end_inset
-
-z
-\begin_inset Quotes erd
-\end_inset
-
- for 
-\family typewriter
-size_t
-\family default
- and 
-\begin_inset Quotes eld
-\end_inset
-
-ll
-\begin_inset Quotes erd
-\end_inset
-
- for long long, MSVCRT users must use 
-\begin_inset Quotes eld
-\end_inset
-
-I
-\begin_inset Quotes erd
-\end_inset
-
- and 
-\begin_inset Quotes eld
-\end_inset
-
-I64
-\begin_inset Quotes erd
-\end_inset
-
- (forming 
-\family typewriter
-%Id
-\family default
- instead of 
-\family typewriter
-%zd
-\family default
- for 
-\family typewriter
-ssize_t
-\family default
-, for example).
- libHX provides two convenience macros for this:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#define
-\series default
- HX_SIZET_FMT    "z"
-\family roman
-\shape italic
- or 
-\family default
-\shape default
-"I"
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_SIZET_FMT
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#define
-\series default
- HX_LONGLONG_FMT "ll"
-\family roman
-\shape italic
- or 
-\family default
-\shape default
-"I64"
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_LONGLONG_FMT
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-These may be used together with printf or scanf:
-\end_layout
-
-\begin_layout LyX-Code
-printf("struct timespec is of size %" HX_SIZET_FMT "u
-\backslash
-n",
-\begin_inset Newline newline
-\end_inset
-
-       
-\series bold
-sizeof
-\series default
-(struct timespec));
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Miscellaneous functions
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/misc.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/misc.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_ffs(
-\series bold
-unsigned long
-\series default
- z);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_ffs
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_fls(
-\series bold
-unsigned long
-\series default
- z);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_fls
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HX_hexdump(
-\series bold
-FILE *
-\series default
-fp, 
-\series bold
-const void *
-\series default
-ptr, 
-\series bold
-unsigned int
-\series default
- len);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_hexdump
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HX_zvecfree(
-\series bold
-char **
-\series default
-);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_zvecfree
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-unsigned int
-\series default
- HX_zveclen(
-\series bold
-const char *const *
-\series default
-);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_zveclen
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_ffs
-\family default
- Finds the first (lowest-significant) bit in a value and returns its position,
- or -1 to indicate failure.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_fls
-\family default
- Finds the last (most-significant) bit in a value and returns its position,
- or -1 to indicate failure.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_hexdump
-\family default
- Outputs a nice pretty-printed hex and ASCII dump to the filedescriptor
- 
-\family typewriter
-fp
-\family default
-.
- 
-\family typewriter
-ptr
-\family default
- is the memory area, of which 
-\family typewriter
-len
-\family default
- bytes will be dumped.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_zvecfree
-\family default
- Frees the supplied Z-vector array.
- (Frees all array elements from the first element to (excluding) the first
- 
-\family typewriter
-NULL
-\family default
- element.)
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_zveclen
-\family default
- Counts the number of array elements until the first 
-\family typewriter
-NULL
-\family default
- array element is seen, and returns this number.
-\end_layout
-
-\begin_layout Section
-Time functions
-\end_layout
-
-\begin_layout Standard
-Time in POSIX systems is represented in 
-\family typewriter
-struct timespec
-\family default
-.
- This structure is composed of two members: one integer for the number of
- full seconds in the time value, and one integer for the number of nanoseconds
- that remain when subtracting the full seconds from the time value.
- POSIX leaves it unspecified how negative time is to be represented with
- this structure, so I have devised an algebra for use with the same struct
- that gives negative time support.
-\end_layout
-
-\begin_layout Standard
-Since integers often cannot store negative zero (due to e.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
-\begin_inset space \space{}
-\end_inset
-
-use of 2s complements in the language implementation), we will store the
- minus sign in the nanosecond member if the integral second part is zero.
- This gives us the property that we can test for negative time by looking
- for whether at least one member of the structure is negative.
- Also, we want to avoid storing the minus in both members to somewhat aid
- the pretty-printing construct often seen,
-\end_layout
-
-\begin_layout LyX-Code
-printf("%ld.%09ld
-\backslash
-n", (long)ts.tv_sec, ts.tv_nsec);
-\end_layout
-
-\begin_layout Standard
-The number of combinations of a (non-zero) negative number, zero and a (non-zero
-) positive number is small, so we can actually just exhaustively list them
- all.
-\begin_inset Separator latexpar
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\noindent
-\align center
-\begin_inset Tabular
-<lyxtabular version="3" rows="4" columns="6">
-<features tabularvalignment="middle">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="top">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Representation
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-Time value
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-R
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-T
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-R
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-T
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\left\{ -1,-1\right\} $
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-illegal
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\left\{ 0,-1\right\} $
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
--0.1
-\begin_inset space \thinspace{}
-\end_inset
-
-s
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\left\{ 1,-1\right\} $
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-illegal
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\left\{ -1,0\right\} $
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
--1.0
-\begin_inset space \thinspace{}
-\end_inset
-
-s
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\left\{ 0,0\right\} $
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-0.0
-\begin_inset space \thinspace{}
-\end_inset
-
-s
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\left\{ 1,0\right\} $
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-1.0
-\begin_inset space \thinspace{}
-\end_inset
-
-s
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\left\{ -1,1\right\} $
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
--1.1
-\begin_inset space \thinspace{}
-\end_inset
-
-s
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\left\{ 0,1\right\} $
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-0.1
-\begin_inset space \thinspace{}
-\end_inset
-
-s
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-\begin_inset Formula $\left\{ 1,1\right\} $
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-1.1
-\begin_inset space \thinspace{}
-\end_inset
-
-s
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The set of so-extended valid timespecs is therefore:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Formula 
-\[
-K=\left\{ \left(i,f\right):i,f\in\mathbb{Z}\wedge i\neq0\wedge0\leq f<10^{9}\right\} \cup\left\{ \left(i,f\right):i=0\wedge f\in\mathbb{Z}\wedge-10^{9}<f<10^{9}\right\} 
-\]
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Function list
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/misc.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-bool
-\series default
- HX_timespec_isneg(
-\series bold
-const struct
-\series default
- timespec 
-\series bold
-*
-\series default
-p);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_timespec_isneg
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- timespec 
-\series bold
-*
-\series default
-HX_timespec_neg(
-\series bold
-struct
-\series default
- timespec 
-\series bold
-*
-\series default
-result,
-\begin_inset Newline newline
-\end_inset
-
-    
-\series bold
-const struct
-\series default
- timespec 
-\series bold
-*
-\series default
-p);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_timespec_neg
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- timespec 
-\series bold
-*
-\series default
-HX_timespec_add(
-\series bold
-struct
-\series default
- timespec 
-\series bold
-*
-\series default
-result,
-\begin_inset Newline newline
-\end_inset
-
-    
-\series bold
-const struct
-\series default
- timespec 
-\series bold
-*
-\series default
-p, 
-\series bold
-const struct
-\series default
- timespec 
-\series bold
-*
-\series default
-q);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_timespec_add
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- timespec 
-\series bold
-*
-\series default
-HX_timespec_sub(
-\series bold
-struct
-\series default
- timespec 
-\series bold
-*
-\series default
-delta,
-\begin_inset Newline newline
-\end_inset
-
-    
-\series bold
-const struct
-\series default
- timespec 
-\series bold
-*
-\series default
-p, 
-\series bold
-const struct
-\series default
- timespec 
-\series bold
-*
-\series default
-q);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_timespec_sub
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- timespec 
-\series bold
-*
-\series default
-HX_timespec_mul(
-\series bold
-struct
-\series default
- timespec 
-\series bold
-*
-\series default
-delta,
-\begin_inset Newline newline
-\end_inset
-
-    
-\series bold
-const struct
-\series default
- timespec 
-\series bold
-*
-\series default
-p, 
-\series bold
-int
-\series default
- f);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_timespec_mul
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- timespec 
-\series bold
-*
-\series default
-HX_timespec_mulf(
-\series bold
-struct
-\series default
- timespec 
-\series bold
-*
-\series default
-delta,
-\begin_inset Newline newline
-\end_inset
-
-    
-\series bold
-const struct
-\series default
- timespec 
-\series bold
-*
-\series default
-p, 
-\series bold
-double
-\series default
- f);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_timespec_mulf
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- timeval 
-\series bold
-*
-\series default
-HX_timeval_sub(
-\series bold
-struct
-\series default
- timeval 
-\series bold
-*
-\series default
-delta,
-\begin_inset Newline newline
-\end_inset
-
-    
-\series bold
-const struct
-\series default
- timeval 
-\series bold
-*
-\series default
-p, 
-\series bold
-const struct
-\series default
- timeval 
-\series bold
-*
-\series default
-q);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_timeval_sub
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_time_compare(
-\series bold
-const struct
-\series default
- stat 
-\series bold
-*
-\series default
-a, 
-\series bold
-const struct
-\series default
- stat 
-\series bold
-*
-\series default
-b, 
-\series bold
-int
-\series default
- mode);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_time_compare
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_timespec_isneg
-\family default
- Determines whether a timespec structure represents (non-zero) negative
- time.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_timespec_neg
-\family default
- Computes the negation of the time specified by 
-\family typewriter
-p
-\family default
-.
- 
-\family typewriter
-result
-\family default
- and 
-\family typewriter
-p
-\family default
- may point to the same structure.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_timespec_add
-\family default
- Calculates the sum of the two times specified by 
-\family typewriter
-p
-\family default
- and 
-\family typewriter
-q
-\family default
-, which are of type 
-\family typewriter
-struct timespec
-\family default
-.
- Any of 
-\family typewriter
-result
-\family default
-, 
-\family typewriter
-p
-\family default
- and 
-\family typewriter
-q
-\family default
- may point to the same structure.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_timespec_sub
-\family default
- Calculates the difference between the two timepoints p and q, which are
- of type 
-\family typewriter
-struct timespec
-\family default
- (nanosecond granularity).
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_timespec_mul
-\family default
- Multiplies the time quantum in 
-\family typewriter
-p
-\family default
- by 
-\family typewriter
-f
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_timespec_mulf
-\family default
- Multiplies the time quantum in 
-\family typewriter
-p
-\family default
- by 
-\family typewriter
-f
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_timeval_sub
-\family default
- Calculates the difference between the two timepoints p and q, which are
- of type 
-\family typewriter
-struct timeval
-\family default
- (microsecnod granularity).
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_time_compare
-\family default
- Compares the timestamps from two 
-\family typewriter
-struct stat
-\family default
-s.
- 
-\family typewriter
-mode
-\family default
- indicates which field is compared, which can either be 
-\family typewriter
-'a'
-\family default
- for the access time, 
-\family typewriter
-'c'
-\family default
- for the inode change time, 
-\family typewriter
-'m'
-\family default
- for the modification time, or 
-\family typewriter
-'o'
-\family default
- for the creation time (where available).
- Returns a negative number if the time in 
-\family typewriter
-a
-\family default
- is less than 
-\family typewriter
-b
-\family default
-, zero when they are equal, or a positive number greater than zero if 
-\family typewriter
-a
-\family default
- is greater than 
-\family typewriter
-b
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-The macros 
-\family typewriter
-HX_TIMESPEC_FMT
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_TIMESPEC_FMT
-\end_layout
-
-\end_inset
-
- and 
-\family typewriter
-HX_TIMESPEC_EXP
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_TIMESPEC_EXP
-\end_layout
-
-\end_inset
-
- can be used for passing and printing a 
-\family typewriter
-struct timespec
-\family default
- using the *
-\family typewriter
-printf
-\family default
- function family:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- timespec p;
-\begin_inset Newline newline
-\end_inset
-
-clock_gettime(CLOCK_MONOTONIC, &p);
-\begin_inset Newline newline
-\end_inset
-
-printf("Now: " HX_TIMESPEC_FMT, HX_TIMESPEC_EXP(&p));
-\end_layout
-
-\begin_layout Standard
-Similarly, 
-\family typewriter
-HX_TIMEVAL_FMT
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_TIMEVAL_FMT
-\end_layout
-
-\end_inset
-
- and 
-\family typewriter
-HX_TIMEVAL_EXP
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_TIMEVAL_EXP
-\end_layout
-
-\end_inset
-
- exist for the older 
-\family typewriter
-struct timeval
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Bitmaps
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/misc.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-size_t
-\series default
- HXbitmap_size(
-\series bold
-type
-\series default
- array, 
-\series bold
-unsigned int
-\series default
- bits);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXbitmap_size
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXbitmap_set(
-\series bold
-type *
-\series default
-bmap, 
-\series bold
-unsigned int
-\series default
- bit);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXbitmap_set
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXbitmap_clear(
-\series bold
-type *
-\series default
-bmap, 
-\series bold
-unsigned int
-\series default
- bit);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXbitmap_clear
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-bool
-\series default
- HXbitmap_test(
-\series bold
-type *
-\series default
-bmap, 
-\series bold
-unsigned int
-\series default
- bit);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXbitmap_test
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-All of these four are implemented as macros, so they can be used with any
- integer type that is desired to be used.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXbitmap_size
-\family default
- Returns the amount of 
-\begin_inset Quotes eld
-\end_inset
-
-type
-\begin_inset Quotes erd
-\end_inset
-
--based integers that would be needed to hold an array of the requested amount
- of bits.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXbitmap_set
-\family default
- Set the specific bit in the bitmap.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXbitmap_clear
-\family default
- Clear the specific bit in this bitmap.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXbitmap_test
-\family default
- Test for the specific bit and returns 
-\family typewriter
-true
-\family default
- if it is set, otherwise 
-\family typewriter
-false
-\family default
-.
-\end_layout
-
-\begin_layout Subsubsection
-Example
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <stdlib.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <string.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <libHX/misc.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- main(
-\series bold
-void
-\series default
-)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-unsigned long
-\series default
- bitmap
-\series bold
-[
-\series default
-HXbitmap_size(
-\series bold
-unsigned long
-\series default
-, 128)
-\series bold
-]
-\series default
-;
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        memset(bitmap, 0, sizeof(bitmap));
-\begin_inset Newline newline
-\end_inset
-
-        HXbitmap_set(bitmap, 49);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-return
-\series default
- HXbitmap_get(bitmap, HX_irand(0, 128)) ?
-\begin_inset Newline newline
-\end_inset
-
-               EXIT_SUCCESS : EXIT_FAILURE;
-\begin_inset Newline newline
-\end_inset
-
-}
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Part
-Data structures
-\end_layout
-
-\begin_layout Section
-Maps
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:maps"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-A map is a collection of key-value pairs.
- (Some languages, such as Perl, also call them 
-\begin_inset Quotes eld
-\end_inset
-
-associative array
-\begin_inset Quotes erd
-\end_inset
-
- or just 
-\begin_inset Quotes eld
-\end_inset
-
-hash
-\begin_inset Quotes erd
-\end_inset
-
-, however, the underlying storage mechanism may not be an array or a hash,
- however.) Each key is unique and has an associated value.
- Keys can be any data desired; HXmap allows to specify your own key and
- data handling functions so they can be strings, raw pointers, or complex
- structures.
-\end_layout
-
-\begin_layout Standard
-To access any map-related functions, 
-\family typewriter
-#include <libHX\SpecialChar breakableslash
-map.h>
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-Structural definition
-\begin_inset CommandInset label
-LatexCommand label
-name "subsec:maps-def"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-HXmap
-\family default
- structure is a near-opaque type.
- Unlike the predecessor map implementation 
-\family typewriter
-struct HXbtree
-\family default
- from libHX 2.x, the 3.x API exposes much less fields.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- HXmap {
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-struct HXmap
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-unsigned int
-\series default
- items, flags;
-\begin_inset Newline newline
-\end_inset
-
-};
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-items
-\family default
- The number of items in the tree.
- This field tracks the number of items in the map and is used to report
- the number of elements to the user, and is updated whenever an element
- is inserted or removed from the map.
- The field must not be changed by user.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-flags
-\family default
- The current behavior flags for the map.
- While implementation-private bits are exposed, only 
-\family typewriter
-HXMAP_NOREPLACE
-\family default
- is currently allowed to be (un)set by the developer while a map exists.
-\end_layout
-
-\begin_layout Standard
-For retrieving elements from a tree, some functions work with 
-\family typewriter
-struct HXmap_node
-\family default
-, which is defined as follows:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- HXmap_node {
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-struct HXmap_node
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-union
-\series default
- {
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-void *
-\series default
-key;
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-const char *const
-\series default
- skey;
-\begin_inset Newline newline
-\end_inset
-
-        };
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-union
-\series default
- {
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-void *
-\series default
-data;
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-char *
-\series default
-sdata;
-\begin_inset Newline newline
-\end_inset
-
-        };
-\begin_inset Newline newline
-\end_inset
-
-};
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-key
-\family default
- The so-called primary key, which uniquely identifies an element (a key-value
- pair) in the map.
- The memory portions that make up the key must not be modified.
- (If the key changes, so does its hash value and/or position index, and
- without taking that into account, writing to the key directly is going
- to end up with an inconsistent state.
- To change the key, you will need to delete the element and reinsert it
- with its new key.)
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-skey
-\family default
- A convenience type field for when the map's keys are C strings.
- It is useful for use with e.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
-\begin_inset space \space{}
-\end_inset
-
-
-\family typewriter
-printf
-\family default
- or other varargs function, which would otherwise require casting of the
- 
-\family typewriter
-void
-\begin_inset space ~
-\end_inset
-
-*key
-\family default
- member to 
-\family typewriter
-const char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
- first.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-data
-\family default
- The data associated with the key.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-sdata
-\family default
- Convenience type field.
-\end_layout
-
-\begin_layout Subsection
-Map initialization
-\end_layout
-
-\begin_layout Standard
-During initialization, you specify the underlying storage type by selecting
- a given constructor function.
- All further operations are done through the unified HXmap API which uses
- a form of virtual calls internally.
-\end_layout
-
-\begin_layout Standard
-Currently, there are two distinct map types in libHX.
- There are a handful of selectable symbols, though.
- Abstract types are:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAPT_DEFAULT
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAPT_DEFAULT
-\end_layout
-
-\end_inset
-
- No further preferences or guarantees; selects any map type that the libHX
- maintainer deemed fast.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAPT_ORDERED
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAPT_ORDERED
-\end_layout
-
-\end_inset
-
- The map shall use a data structure that provides ordered traversal.
-\end_layout
-
-\begin_layout Standard
-Specific types include:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAPT_HASH
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_MAPT_HASH
-\end_layout
-
-\end_inset
-
- Hash-based map
-\begin_inset space ~
-\end_inset
-
-– Amortized 
-\begin_inset Formula $\mathcal{O}\left(1\right)$
-\end_inset
-
- insertion, lookup and deletion; unordered.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAPT_RBTREE
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_MAPT_RBTREE
-\end_layout
-
-\end_inset
-
- Red-black binary tree
-\begin_inset space ~
-\end_inset
-
-– 
-\begin_inset Formula $\mathcal{O}\left(\log\left(n\right)\right)$
-\end_inset
-
- insertion, lookup and deletion; ordered.
-\end_layout
-
-\begin_layout Standard
-These can then be used with the initialization functions:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- HXmap 
-\series bold
-*
-\series default
-HXmap_init(
-\series bold
-unsigned int
-\series default
- type, 
-\series bold
-unsigned int
-\series default
- flags);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmap_init
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXmap 
-\series bold
-*
-\series default
-HXmap_init5(
-\series bold
-unsigned int
-\series default
- type, 
-\series bold
-unsigned int
-\series default
- flags,
-\begin_inset Newline newline
-\end_inset
-
-    
-\series bold
-const struct
-\series default
- HXmap_ops 
-\series bold
-*
-\series default
-ops, 
-\series bold
-size_t
-\series default
- key_size, 
-\series bold
-size_t
-\series default
- data_size);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmap_init5
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Both the 
-\family typewriter
-*_init
-\family default
- and 
-\family typewriter
-*_init5
-\family default
- variant creates a new map; the latter function allows to specify the operations
- in detail as well as key and data size, which may become necessary when
- using data sets which have their own way of being managed.
- The 
-\family typewriter
-flags
-\family default
- parameter can contain any of the following:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAP_NONE
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAP_NONE
-\end_layout
-
-\end_inset
-
- This is just a mnemonic for the value 0, indicating no flags.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAP_NOREPLACE
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAP_NOREPLACE
-\end_layout
-
-\end_inset
-
- If a key already exists and another add operation is attempted, the key's
- associated value will be replaced by the new value.
- If this flag is absent, 
-\family typewriter
--EEXIST
-\family default
- is returned.
- This flag is allowed to be subsequently changed by the developer if so
- desired, using bit logic such as 
-\family typewriter
-map->flags &= ~HXMAP_NOREPLACE;
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAP_SKEY
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAP_SKEY
-\end_layout
-
-\end_inset
-
- Notifies the constructor that keys will be C-style strings.
- The flag presets the 
-\family typewriter
-k_compare
-\family default
- operation to use 
-\family typewriter
-strcmp
-\family default
-.
- In the flag's absence, direct value comparison will be used if the key
- size is specified as zero (e.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
-\begin_inset space \space{}
-\end_inset
-
-with the 
-\family typewriter
-HXhashmap_\SpecialChar softhyphen
-init4
-\family default
- function call), or 
-\family typewriter
-memcmp
-\family default
- if the key size is non-zero.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAP_CKEY
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAP_CKEY
-\end_layout
-
-\end_inset
-
- Instructs the map to make copies of keys when they are added to the map.
- This is required when the buffer holding the key changes or goes out of
- scope.
- The flag presets the 
-\family typewriter
-k_clone
-\family default
- and 
-\family typewriter
-k_free
-\family default
- operations to 
-\family typewriter
-HX_memdup
-\family default
- and 
-\family typewriter
-free
-\family default
-, and as such, the 
-\family typewriter
-key_size
-\family default
- parameter must not be zero.
- If however, 
-\family typewriter
-HXMAP_SKEY
-\family default
- is also specified, 
-\family typewriter
-HX_strdup
-\family default
- and 
-\family typewriter
-free
-\family default
- will be used and 
-\family typewriter
-key_size
-\family default
- must be zero.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAP_SDATA
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAP_SDATA
-\end_layout
-
-\end_inset
-
- Notifies the constructor that data will be C-style strings.
- This sets up the 
-\family typewriter
-d_clone
-\family default
- and 
-\family typewriter
-d_free
-\family default
- operations.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAP_CDATA
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAP_CDATA
-\end_layout
-
-\end_inset
-
- Instructs the map to make copies of the data when new entries are added
- to the map.
- This is required when the buffer holding the data either goes out of scope,
- or you want to keep the original contents instead of just a pointer.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAP_SCKEY
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAP_SCKEY
-\end_layout
-
-\end_inset
-
- Mnemonic for the combination of 
-\family typewriter
-HXMAP_\SpecialChar softhyphen
-SKEY
-\family default
- OR'ed with 
-\family typewriter
-HXMAP_\SpecialChar softhyphen
-CKEY
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAP_SCDATA
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAP_SCDATA
-\end_layout
-
-\end_inset
-
- Mnemonic for the combination of 
-\family typewriter
-HXMAP_\SpecialChar softhyphen
-SDATA
-\family default
- OR'ed with 
-\family typewriter
-HXMAP_\SpecialChar softhyphen
-SDATA
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAP_SINGULAR
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAP_SINGULAR
-\end_layout
-
-\end_inset
-
- Specifies that the 
-\begin_inset Quotes eld
-\end_inset
-
-map
-\begin_inset Quotes erd
-\end_inset
-
- is only used as a set, i.
-\begin_inset space \thinspace{}
-\end_inset
-
-e.
-\begin_inset space \space{}
-\end_inset
-
-it does not store any values, only keys.
- Henceforth, the 
-\family typewriter
-value
-\family default
- argument to 
-\family typewriter
-HXmap_add
-\family default
- must always be 
-\family typewriter
-NULL
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-Flag combinations
-\end_layout
-
-\begin_layout Standard
-This subsection highlights the way 
-\family typewriter
-HXMAP_SKEY
-\family default
- interacts with 
-\family typewriter
-HXMAP_CKEY
-\family default
- and the key size.
- The copy semantics are the same for 
-\family typewriter
-HXMAP_SDATA
-\family default
- and 
-\family typewriter
-HXMAP_CDATA
-\family default
-.
-\end_layout
-
-\begin_layout Subsubsection*
-
-\family typewriter
-HXMAP_SKEY
-\family default
- is unset, 
-\family typewriter
-HXMAP_CKEY
-\family default
- is unset
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-key_size
-\family default
- parameter at the time of map construction is ignored.
- The pointer value of the 
-\family typewriter
-key
-\family default
- parameter for the 
-\family typewriter
-HXmap_add
-\family default
- call is directly stored in the tree, and this is the key that uniquely
- identifies the map entry and which is used for comparisons.
- This may be used if you intend to directly map pointer values.
-\end_layout
-
-\begin_layout LyX-Code
-static struct something *x = ..., *y = ...;
-\begin_inset Newline newline
-\end_inset
-
-HXmap_add(map, &x[0], "foo");
-\begin_inset Newline newline
-\end_inset
-
-HXmap_add(map, &x[1], "bar");
-\end_layout
-
-\begin_layout Subsubsection*
-
-\family typewriter
-HXMAP_SKEY
-\family default
- is set, 
-\family typewriter
-HXMAP_CKEY
-\family default
- is unset
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-key_size
-\family default
- parameter at the time of map construction is ignored.
- The pointer value of the 
-\family typewriter
-key
-\family default
- parameter for the 
-\family typewriter
-HXmap_add
-\family default
- call is directly stored in the tree, but it is the C string 
-\shape italic
-pointed to
-\shape default
- by the 
-\family typewriter
-key
-\family default
- parameter that serves as the key.
-\end_layout
-
-\begin_layout Subsubsection*
-
-\family typewriter
-HXMAP_SKEY
-\family default
- is set, 
-\family typewriter
-HXMAP_CKEY
-\family default
- is set
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-key_size
-\family default
- parameter at the time of map construction is ignored.
- The string pointed to by the key parameter will be duplicated, and the
- resulting pointer will be stored in the tree.
- Again, it is the pointed-to string that is the key.
-\end_layout
-
-\begin_layout Subsubsection*
-
-\family typewriter
-HXMAP_SKEY
-\family default
- is unset, 
-\family typewriter
-HXMAP_CKEY
-\family default
- is set
-\end_layout
-
-\begin_layout Standard
-The memory block pointed to by the key parameter will be duplicated.
- The 
-\family typewriter
-key_size
-\family default
- parameter must be non-zero for this to successfully work.
-\end_layout
-
-\begin_layout Subsubsection*
-With separate ops
-\end_layout
-
-\begin_layout Standard
-However, when a custom 
-\family typewriter
-struct HXmap_ops
-\family default
- is provided in the call to 
-\family typewriter
-HXmap_init5
-\family default
-, any of these semantics can be overridden.
- Particularly, since your own ops can practically ignore 
-\family typewriter
-key_size
-\family default
-, it could be set to any value.
-\end_layout
-
-\begin_layout Subsection
-Key-data operations
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-HXMAP_SKEY
-\family default
-\SpecialChar breakableslash
-
-\family typewriter
-CKEY
-\family default
-\SpecialChar breakableslash
-
-\family typewriter
-SDATA
-\family default
-\SpecialChar breakableslash
-
-\family typewriter
-CDATA
-\family default
- flags are generally sufficient to set up common maps where keys and/or
- data are C strings or simple binary data where 
-\family typewriter
-memdup
-\family default
-/
-\family typewriter
-memcmp
-\family default
- is enough.
- Where the provided mechanisms are not cutting it, an extra 
-\family typewriter
-HXmap_ops
-\family default
- structure with functions specialized in handling the keys and/or data has
- to be used as an argument to the initialization function call.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- HXmap_ops {
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-struct HXmap_ops
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-int (*
-\series default
-k_compare
-\series bold
-)
-\series default
-(
-\series bold
-const void *
-\series default
-, 
-\series bold
-const void *
-\series default
-, 
-\series bold
-size_t
-\series default
-);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-void *(*
-\series default
-k_clone
-\series bold
-)
-\series default
-(
-\series bold
-const void *
-\series default
-, 
-\series bold
-size_t
-\series default
-);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-void (*
-\series default
-k_free
-\series bold
-)
-\series default
-(
-\series bold
-void *
-\series default
-);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-void *(*
-\series default
-d_clone
-\series bold
-)
-\series default
-(
-\series bold
-const void *
-\series default
-, 
-\series bold
-size_t
-\series default
-);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-void (*
-\series default
-d_free
-\series bold
-)
-\series default
-(
-\series bold
-void *
-\series default
-);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-unsigned long (*
-\series default
-k_hash
-\series bold
-)
-\series default
-(
-\series bold
-const void *
-\series default
-, 
-\series bold
-size_t
-\series default
-);
-\begin_inset Newline newline
-\end_inset
-
-};
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-k_compare
-\family default
- Function to compare two keys.
- The return value is the same as that of 
-\family typewriter
-memcmp
-\family default
- or 
-\family typewriter
-strcmp
-\family default
-: negative values indicate that the first key is 
-\begin_inset Quotes eld
-\end_inset
-
-less than
-\begin_inset Quotes erd
-\end_inset
-
- the second, zero indicates that both keys are equal, and positive values
- indicate that the first key is 
-\begin_inset Quotes eld
-\end_inset
-
-greater than
-\begin_inset Quotes erd
-\end_inset
-
- the second.
- The size argument in third position is provided so that 
-\family typewriter
-memcmp
-\family default
-, which wants a size parameter, can directly be used without having to write
- an own function.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-k_clone
-\family default
- Function that will clone (duplicate) a key.
- This is used for keys that will be added to the tree, and potentially also
- for state-keeping during traversal of the map.
- It is valid that this clone function simply returns the value of the pointer
- it was actually passed; this is used by default for maps without 
-\family typewriter
-HXMAP_CKEY
-\family default
- for example.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-k_free
-\family default
- Function to free a key.
- In most cases it defaults to 
-\family typewriter
-free
-\family default
-(3), but in case you are using complex structs, more cleanup may be needed.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-d_clone
-\family default
- Same as 
-\family typewriter
-k_clone
-\family default
-, but for data.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-d_free
-\family default
- Same as 
-\family typewriter
-k_free
-\family default
-, but for data.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-k_hash
-\family default
- Specifies an alternate hash function.
- Only to be used with hash-based maps.
- Hashmaps default to using the DJB2 string hash function when 
-\family typewriter
-HXMAP_SKEY
-\family default
- is given, or otherwise the Jenkins' lookup3 hash function.
-\end_layout
-
-\begin_layout Standard
-libHX exports two hash functions that you can select for 
-\family typewriter
-struct HXmap_ops
-\family default
-'s 
-\family typewriter
-k_hash
-\family default
- if the default for a given flag combination is not to your liking.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXhash_jlookup3
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXhash_jlookup3
-\end_layout
-
-\end_inset
-
- Bob Jenkins's lookup3 hash.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXhash_djb2
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXhash_djb2
-\end_layout
-
-\end_inset
-
- DJB2 string hash.
-\end_layout
-
-\begin_layout Subsection
-Map operations
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-int
-\series default
- HXmap_add(
-\series bold
-struct
-\series default
- HXmap 
-\series bold
-*
-\series default
-, 
-\series bold
-const void *
-\series default
-key, 
-\series bold
-const void *
-\series default
-value);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmap_add
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-const struct
-\series default
- HXmap_node 
-\series bold
-*
-\series default
-HXmap_find(
-\series bold
-const struct
-\series default
- HXmap 
-\series bold
-*
-\series default
-, 
-\series bold
-const void *
-\series default
-key);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmap_find
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void *
-\series default
-HXmap_get(
-\series bold
-const struct
-\series default
- HXmap 
-\series bold
-*
-\series default
-, 
-\series bold
-const void *
-\series default
-key);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmap_get
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void *
-\series default
-HXmap_del(
-\series bold
-struct
-\series default
- HXmap 
-\series bold
-*
-\series default
-, 
-\series bold
-const void *
-\series default
-key);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmap_del
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXmap_free(
-\series bold
-struct
-\series default
- HXmap 
-\series bold
-*
-\series default
-);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmap_free
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXmap_node 
-\series bold
-*
-\series default
-HXmap_keysvalues(
-\series bold
-const struct
-\series default
- HXmap 
-\series bold
-*
-\series default
-);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmap_keysvalues
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmap_add
-\family default
- 
-\family typewriter
-A
-\family default
-dds a new node to the tree using the given key and data.
- When an element is in the map, the key may not be modified, as doing so
- could possibly invalidate the internal location of the element, or its
- ordering with respect to other elements.
- If you need to change the key, you will have to delete the element from
- the tree and re-insert it.
- On error, 
-\family typewriter
--errno
-\family default
- will be returned.
-\begin_inset Newline newline
-\end_inset
-
-When 
-\family typewriter
-HXMAP_SINGULAR
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAP_SINGULAR
-\end_layout
-
-\end_inset
-
- is in effect, 
-\family typewriter
-value
-\family default
- must be 
-\family typewriter
-NULL
-\family default
-, or 
-\family typewriter
--EINVAL
-\family default
- is returned.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmap_find
-\family default
- Finds the node for the given key.
- The key can be read from the node using 
-\family typewriter
-node->key
-\family default
- or 
-\family typewriter
-node->skey
-\family default
- (convenience alias for 
-\family typewriter
-key
-\family default
-, but with a type of 
-\family typewriter
-const char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-), and the data by using 
-\family typewriter
-node->data
-\family default
- or 
-\family typewriter
-node->sdata
-\family default
-.
- (see section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "subsec:maps-def"
-
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmap_get
-\family default
- Get is a find operation directly returning 
-\family typewriter
-node->data
-\family default
- instead of the node itself.
- Since 
-\family typewriter
-HXmap_get
-\family default
- may legitimately return 
-\family typewriter
-NULL
-\family default
- if 
-\family typewriter
-NULL
-\family default
- was stored in the tree as the data for a given key, only 
-\family typewriter
-errno
-\family default
- will really tell whether the node was found or not; in the latter case,
- 
-\family typewriter
-errno
-\family default
- is set to 
-\family typewriter
-ENOENT
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmap_del
-\family default
- Removes an element from the map and returns the data value that was associated
- with it.
- When an error occurred, or the element was not found, 
-\family typewriter
-NULL
-\family default
- is returned.
- Because 
-\family typewriter
-NULL
-\family default
- can be a valid data value, 
-\family typewriter
-errno
-\family default
- can be checked for non-zero.
- 
-\family typewriter
-errno
-\family default
- will be 
-\family typewriter
--ENOENT
-\family default
- if the element was not found, or zero when everything was ok.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmap_free
-\family default
- The function will delete all elements in the map and free memory it holds.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmap_keysvalues
-\family default
- Returns all key-value-pairs in an array of the size as many items were
- in the map (
-\family typewriter
-map->items
-\family default
-) at the time it was called.
- The memory must be freed using 
-\family typewriter
-free
-\family default
-(3) when it is no longer needed.
- The order elements in the array follows the traverser notes (see below),
- unless otherwise specified.
-\end_layout
-
-\begin_layout Subsection
-Map traversal
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- HXmap_trav 
-\series bold
-*
-\series default
-HXmap_travinit(
-\series bold
-const struct
-\series default
- HXmap 
-\series bold
-*
-\series default
-);
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-const struct
-\series default
- HXmap_node 
-\series bold
-*
-\series default
-HXmap_traverse(
-\series bold
-struct
-\series default
- HXmap_trav 
-\series bold
-*
-\series default
-iterator);
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXmap_travfree(
-\series bold
-struct
-\series default
- HXmap_trav 
-\series bold
-*
-\series default
-iterator);
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXmap_qfe(
-\series bold
-const struct
-\series default
- HXmap 
-\series bold
-*
-\series default
-, 
-\series bold
-bool (*
-\series default
-fn
-\series bold
-)
-\series default
-(
-\series bold
-const struct
-\series default
- HXmap_node 
-\series bold
-*
-\series default
-,
-\begin_inset Newline newline
-\end_inset
-
-     
-\series bold
-void *
-\series default
-arg), 
-\series bold
-void *
-\series default
-arg);
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmap_travinit
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmap_travinit
-\end_layout
-
-\end_inset
-
- Initializes a traverser (a.
-\begin_inset space \thinspace{}
-\end_inset
-
-k.
-\begin_inset space \thinspace{}
-\end_inset
-
-a.
-\begin_inset space \space{}
-\end_inset
-
-iterator) for the map, and returns a pointer to it.
- 
-\family typewriter
-NULL
-\family default
- will be returned in case of an error, such as memory allocation failure.
- Traversers are returned even if the map has zero elements.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmap_traverse
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmap_traverse
-\end_layout
-
-\end_inset
-
- Returns a pointer to a 
-\family typewriter
-struct HXmap_node
-\family default
- for the next element
-\begin_inset space ~
-\end_inset
-
-\SpecialChar breakableslash
- key-value pair from the map, or 
-\family typewriter
-NULL
-\family default
- if there are no more entries.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmap_travfree
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmap_travfree
-\end_layout
-
-\end_inset
-
- Release the memory associated with a traverser.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmap_qfe
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmap_qfe
-\end_layout
-
-\end_inset
-
- The 
-\begin_inset Quotes eld
-\end_inset
-
-quick foreach
-\begin_inset Quotes erd
-\end_inset
-
-.
- Iterates over all map elements in the fastest possible manner, but has
- the restriction that no modifications to the map are allowed.
- Furthermore, a separate function to handle each visited node, is required.
- (Hence this is also called 
-\begin_inset Quotes eld
-\end_inset
-
-closed traversal
-\begin_inset Quotes erd
-\end_inset
-
-, because one cannot access the stack frame of the original function which
- called 
-\family typewriter
-HXmap_qfe
-\family default
-.) The user-defined function returns a bool which indicates whether traversal
- shall continue or not.
-\end_layout
-
-\begin_layout Standard
-Flags for 
-\family typewriter
-HXmap_travinit
-\family default
-:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAP_NOFLAGS
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAP_NOFLAGS
-\end_layout
-
-\end_inset
-
- A mnemonic for no flags, and is defined to be 
-\family typewriter
-0
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXMAP_DTRAV
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXMAP_DTRAV
-\end_layout
-
-\end_inset
-
- Enable support for deletion during traversal.
- As it can make traversal slower, it needs to be explicitly specified for
- cases where it is needed, to not penalize cases where it is not.
-\end_layout
-
-\begin_layout Standard
-WARNING: Modifying the map while a traverser is active is implementation-specifi
-c behavior! libHX generally ensures that there will be no undefined behavior
- (e.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
-\begin_inset space \space{}
-\end_inset
-
-crashes), but there is no guarantee that elements will be returned exactly
- once.
- There are fundamental cases that one should be aware of:
-\end_layout
-
-\begin_layout Itemize
-An element is inserted before where the traverser is currently positioned
- at.
- The element may not be returned in subsequent calls to 
-\family typewriter
-HXmap_traverse
-\family default
- on an already-active traverser.
-\end_layout
-
-\begin_layout Itemize
-Insertion or deletion may cause internal data structure to re-layout.
-\begin_inset Separator latexpar
-\end_inset
-
-
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-Traversers of ordered data structures may choose to rebuild their state.
-\end_layout
-
-\begin_layout Itemize
-Traversers of unordered data structures would run risk to return more than
- once, or not at all.
-\end_layout
-
-\end_deeper
-\begin_layout Standard
-Descriptions for different map types follow.
-\end_layout
-
-\begin_layout Description
-Hashmaps On 
-\family typewriter
-HXmap_add
-\family default
-, an element may be inserted in a position that is before where the traverser
- is currently positioned.
- Such elements will not be returned in the remaining calls to 
-\family typewriter
-HXmap_traverse
-\family default
-.
- The insertion or deletion of an element may cause the internal data structure
- to re-layout itself.
- When this happens, the traverser will stop, so as to not return entries
- twice.
-\end_layout
-
-\begin_layout Description
-Binary
-\begin_inset space ~
-\end_inset
-
-trees Elements may be added before the traverser's position.
- These elements will not be returned in subsequent traversion calls.
- If the data structure changes as a result of an addition or deletion, the
- traverser will rebuild its state and continue traversal transparently.
- Because elements in a binary tree are ordered, that is, element positions
- may not change with respect to another when the tree is rebalanced, there
- is no risk of returning entries more than once.
- Nor will elements that are sorted after the current traverser's position
- not be returned (=
-\begin_inset space ~
-\end_inset
-
-they will be returned, because they cannot get reordered to before the traverser
- like in a hash map).
- The HX rbtree implementation also has proper handling for when the node
- which is currently visiting is deleted.
-\end_layout
-
-\begin_layout Subsection
-RB-tree Limitations
-\end_layout
-
-\begin_layout Standard
-The implementation has a theoretical minimum on the maximum number of nodes,
- 
-\begin_inset Formula $2^{24}=16{,}777{,}216$
-\end_inset
-
-.
- A worst-case tree with this many elements already has a height of 48 (
-\family typewriter
-RBT_MAXDEP
-\family default
-), which is the maximum height currently supported.
- The larger the height is that HXrbtree is supposed to handle, the more
- memory (linear increase) it needs.
- All functions that build or keep a path reserve memory for 
-\family typewriter
-RBT_MAXDEP
-\family default
- nodes; on x86_64 this is 9 bytes per 
-\begin_inset Formula $\langle$
-\end_inset
-
-node, direction
-\begin_inset Formula $\rangle$
-\end_inset
-
- pair, amounting to 432 bytes for path tracking alone.
- It may not sound like a lot to many, but given that kernel people can limit
- their stack usage to 4096 bytes is impressive alone
-\end_layout
-
-\begin_layout Standard
-\begin_inset Foot
-status open
-
-\begin_layout Plain Layout
-Not always of course.
- Linux kernels are often configured to use an 8K stack because some components
- still use a lot of stack space, but even 8K is still damn good.
-\end_layout
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsection
-Examples
-\end_layout
-
-\begin_layout Subsubsection
-Case-insensitive ordering
-\end_layout
-
-\begin_layout Standard
-The correct way:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-static int
-\series default
- my_strcasecmp(
-\series bold
-const void *
-\series default
-a, 
-\series bold
-const void *
-\series default
-b, 
-\series bold
-size_t
-\series default
- z)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-return
-\series default
- strcasecmp(a, b);
-\begin_inset Newline newline
-\end_inset
-
-}
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static const struct
-\series default
- HXmap_ops icase = {
-\begin_inset Newline newline
-\end_inset
-
-        .k_compare = my_strcasecmp,
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-HXmap_init5(HXMAPT_RBTREE, HXMAP_SKEY, &icase, 0, 
-\shape italic
-dsize
-\shape default
-);
-\end_layout
-
-\begin_layout Standard
-A hackish way (which wholly depends on the C implementation and use of extra
- safeguards is a must):
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-static const struct
-\series default
- HXmap_ops icase = {
-\begin_inset Newline newline
-\end_inset
-
-         .k_compare = (
-\series bold
-void *
-\series default
-)strcasecmp,
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-BUILD_BUG_ON(
-\series bold
-sizeof
-\series default
-(DEMOTE_TO_PTR(strcasecmp)) > 
-\series bold
-sizeof
-\series default
-(void *));
-\begin_inset Newline newline
-\end_inset
-
-BUILD_BUG_ON(
-\series bold
-sizeof
-\series default
-(DEMOTE_TO_PTR(strcasecmp)) > 
-\series bold
-sizeof
-\series default
-(icase.k_compare));
-\begin_inset Newline newline
-\end_inset
-
-HXmap_init5(HXMAPT_RBTREE, HXMAP_SKEY, &icase, 0, 
-\shape italic
-dsize
-\shape default
-);
-\end_layout
-
-\begin_layout Subsubsection
-Reverse sorting order
-\end_layout
-
-\begin_layout Standard
-Any function that behaves like 
-\family typewriter
-strcmp
-\family default
- can be used.
- It merely has to return negative when 
-\begin_inset Formula $a<b$
-\end_inset
-
-, zero on 
-\begin_inset Formula $a=b$
-\end_inset
-
-, and positive non-zero when 
-\begin_inset Formula $a>b$
-\end_inset
-
-.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-static int
-\series default
- strcmp_rev(
-\series bold
-const void *
-\series default
-a, 
-\series bold
-const void *
-\series default
-b, 
-\series bold
-size_t
-\series default
- z)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-z is provided for cases when things are raw memory blocks.
-
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-return
-\series default
- strcmp(b, a);
-\begin_inset Newline newline
-\end_inset
-
-}
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static const struct
-\series default
- HXmap_ops rev = {
-\begin_inset Newline newline
-\end_inset
-
-        .k_compare = strcmp_rev,
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-HXmap_init5(HXMAPT_RBTREE, HXMAP_SKEY, &rev, 0, 
-\shape italic
-dsize
-\shape default
-);
-\end_layout
-
-\begin_layout Subsubsection
-Keys with non-unique data
-\begin_inset CommandInset label
-LatexCommand label
-name "subsec:maps-examples-bigkey"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Keys can actually store non-unique data, as long as this extra fields does
- not actually contribute to the logical key
-\begin_inset space ~
-\end_inset
-
-— the parts that do uniquely identify it.
- In the following example, the 
-\family typewriter
-notes
-\family default
- member may be part of struct package, which is the key as far as HXmap
- is concerned, but still, only the name and versions are used to identify
- it.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- package {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-char *
-\series default
-name;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-unsigned int
-\series default
- major_version;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-unsigned int
-\series default
- minor_version;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-char
-\series default
- notes
-\series bold
-[
-\series default
-64
-\series bold
-]
-\series default
-;
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static int
-\series default
- package_cmp(
-\series bold
-const void *
-\series default
-a, 
-\series bold
-const void *
-\series default
-b)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-const struct
-\series default
- package 
-\series bold
-*
-\series default
-p = a, 
-\series bold
-*
-\series default
-q = b;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-int
-\series default
- ret;
-\begin_inset Newline newline
-\end_inset
-
-        ret = strcmp(p->name, q->name);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-if
-\series default
- (ret != 0)
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-return
-\series default
- ret;
-\begin_inset Newline newline
-\end_inset
-
-        ret = p->major_version - q->major_version;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-if
-\series default
- (ret != 0)
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-return
-\series default
- ret;
-\begin_inset Newline newline
-\end_inset
-
-        ret = p->minor_version - q->minor_version;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-if
-\series default
- (ret != 0)
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-return
-\series default
- ret;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-return
-\series default
- 0;
-\begin_inset Newline newline
-\end_inset
-
-}
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static const struct
-\series default
- HXmap_ops package_ops = {
-\begin_inset Newline newline
-\end_inset
-
-        .k_compare = package_cmp,
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXmap_init5(HXMAPT_RBTREE, 
-\shape italic
-flags
-\shape default
-, &package_ops,
-\begin_inset Newline newline
-\end_inset
-
-            
-\series bold
-sizeof
-\series default
-(
-\series bold
-struct
-\series default
- package), 
-\shape italic
-dsize
-\shape default
-);
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Doubly-linked list
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:deque"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-HXdeque is a data structure for a doubly-linked non-circular 
-\family typewriter
-NULL
-\family default
--sentineled list.
- Despite being named a deque, which is short for double-ended queue, and
- which may be implemented using an array, HXdeque is in fact using a linked
- list to provide its deque functionality.
- Furthermore, a dedicated root structure and decidated node structures with
- indirect data referencing are used.
-\end_layout
-
-\begin_layout Subsection
-Structural definition
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/deque.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/deque.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXdeque {
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-struct HXdeque
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- HXdeque_node 
-\series bold
-*
-\series default
-first, 
-\series bold
-*
-\series default
-last;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-unsigned int
-\series default
- items;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-void *
-\series default
-ptr;
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXdeque_node {
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-struct HXdeque_node
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- HXdeque_node 
-\series bold
-*
-\series default
-next, 
-\series bold
-*
-\series default
-prev;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-parent;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-void *
-\series default
-ptr;
-\begin_inset Newline newline
-\end_inset
-
-};
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-ptr
-\family default
- member in 
-\family typewriter
-struct HXdeque
-\family default
- provides room for an arbitrary custom user-supplied pointer.
- 
-\family typewriter
-items
-\family default
- will reflect the number of elements in the list, and must not be modified.
- 
-\family typewriter
-first
-\family default
- and 
-\family typewriter
-last
-\family default
- provide entrypoints to the list's ends.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-ptr
-\family default
- within 
-\family typewriter
-struct HXdeque_node
-\family default
- is the pointer to the user's data.
- It may be modified and used at will by the user.
- See example section
-\begin_inset space ~
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Subsection
-Constructor, destructors
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-HXdeque_init(
-\series bold
-void
-\series default
-);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXdeque_init
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXdeque_free(
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-dq);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXdeque_free
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXdeque_genocide(
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-dq);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXdeque_genocide
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXdeque_genocide2(
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-dq, 
-\series bold
-void (*
-\series default
-xfree
-\series bold
-)
-\series default
-(
-\series bold
-void *
-\series default
-));
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXdeque_genocide2
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void **
-\series default
-HXdeque_to_vec(
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-dq, 
-\series bold
-unsigned int *
-\series default
-num);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXdeque_to_vec
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-To allocate a new empty list, use 
-\family typewriter
-HXdeque_init
-\family default
-.
- 
-\family typewriter
-HXdeque_free
-\family default
- will free the list (including all nodes owned by the list), but not the
- data pointers.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HXdeque_genocide
-\family default
- is a variant that will not only destroy the list, but also calls a freeing
- function 
-\family typewriter
-free()
-\family default
- on all stored data pointers.
- This puts a number of restrictions on the characteristics of the list:
- all data pointers must have been obtained with 
-\family typewriter
-malloc
-\family default
-, 
-\family typewriter
-calloc
-\family default
- or 
-\family typewriter
-realloc
-\family default
- before, and no data pointer must exist twice in the list.
- The function is more efficient than an open-coded loop over all nodes calling
- 
-\family typewriter
-HXdeque_del
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-A generic variant is available with 
-\family typewriter
-HXdeque_genocide2
-\family default
-, which takes a pointer to an appropriate freeing function.
- 
-\family typewriter
-HXdeque_genocide
-\family default
- is thus equivalent to 
-\family typewriter
-HXdeque_genocide2(dq, free)
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-To convert a linked list to a 
-\family typewriter
-NULL
-\family default
--terminated array, 
-\family typewriter
-HXdeque_to_vec
-\family default
- can be used.
- If 
-\family typewriter
-num
-\family default
- is not 
-\family typewriter
-NULL
-\family default
-, the number of elements excluding the 
-\family typewriter
-NULL
-\family default
- sentinel, is stored in 
-\family typewriter
-*num
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-Addition and removal
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- HXdeque_node 
-\series bold
-*
-\series default
-HXdeque_push(
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-dq, 
-\series bold
-void *
-\series default
-ptr);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXdeque_push
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXdeque_node 
-\series bold
-*
-\series default
-HXdeque_unshift(
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-dq, 
-\series bold
-void *
-\series default
-ptr);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXdeque_unshift
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void *
-\series default
-HXdeque_pop(
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-dq);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXdeque_pop
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void *
-\series default
-HXdeque_shift(
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-dq);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXdeque_shift
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-HXdeque_move(
-\series bold
-struct
-\series default
- HXdeque_node 
-\series bold
-*
-\series default
-target,
-\begin_inset Newline newline
-\end_inset
-
-                             
-\series bold
-struct
-\series default
- HXdeque_node 
-\series bold
-*
-\series default
-node);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXdeque_move
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void *
-\series default
-HXdeque_del(
-\series bold
-struct
-\series default
- HXdeque_node 
-\series bold
-*
-\series default
-node);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXdeque_del
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HXdeque_\SpecialChar softhyphen
-push
-\family default
- and 
-\family typewriter
-HXdeque_\SpecialChar softhyphen
-unshift
-\family default
- add the data item in a new node at the end (
-\begin_inset Quotes eld
-\end_inset
-
-push
-\begin_inset Quotes erd
-\end_inset
-
-) or as the new first element (
-\begin_inset Quotes eld
-\end_inset
-
-unshift
-\begin_inset Quotes erd
-\end_inset
-
- as Perl calls it), respectively.
- The functions will return the new node on success, or 
-\family typewriter
-NULL
-\family default
- on failure and 
-\family typewriter
-errno
-\family default
- will be set.
- The node is owned by the list.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HXdeque_\SpecialChar softhyphen
-pop
-\family default
- and 
-\family typewriter
-HXdeque_\SpecialChar softhyphen
-shift
-\family default
- remove the last (
-\begin_inset Quotes eld
-\end_inset
-
-pop
-\begin_inset Quotes erd
-\end_inset
-
-) or first (
-\begin_inset Quotes eld
-\end_inset
-
-shift
-\begin_inset Quotes erd
-\end_inset
-
-) node, respectively, and return the data pointer that was stored in the
- data.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HXdeque_\SpecialChar softhyphen
-move
-\family default
- will unlink a node from its list, and reinsert it after the given target
- node, which may be in a different list.
-\end_layout
-
-\begin_layout Standard
-Deleting a node is accomplished by calling 
-\family typewriter
-HXdeque_del
-\family default
- on it.
- The data pointer stored in the node is not freed, but returned.
-\end_layout
-
-\begin_layout Subsection
-Iteration
-\end_layout
-
-\begin_layout Standard
-Iterating over a HXdeque linked list is done manually and without additional
- overhead of function calls:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-const struct
-\series default
- HXdeque_node 
-\series bold
-*
-\series default
-node;
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-for
-\series default
- (node = dq->first; node != NULL; node = node->next)
-\begin_inset Newline newline
-\end_inset
-
-        do_something(node->ptr);
-\end_layout
-
-\begin_layout Subsection
-Searching
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- HXdeque_node 
-\series bold
-*
-\series default
-HXdeque_find(
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-dq, 
-\series bold
-const void *
-\series default
-ptr);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXdeque_find
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void *
-\series default
-HXdeque_get(
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-dq, 
-\series bold
-void *
-\series default
-ptr);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXdeque_get
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HXdeque_find
-\family default
- searches for the node which contains 
-\family typewriter
-ptr
-\family default
-, and does so by beginning at the start of the list.
- If no node is found, 
-\family typewriter
-NULL
-\family default
- is returned.
- If a pointer is more than once in the list, any node may be returned.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HXdeque_get
-\family default
- will further return the data pointer stored in the node
-\begin_inset space ~
-\end_inset
-
-— however, since that is just what the 
-\family typewriter
-ptr
-\family default
- argument is, the function practically only checks for existence of 
-\family typewriter
-ptr
-\family default
- in the list.
-\end_layout
-
-\begin_layout Subsection
-Examples
-\end_layout
-
-\begin_layout Standard
-
-\series bold
-\begin_inset Float figure
-placement h
-wide false
-sideways false
-status open
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <stdio.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <stdlib.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <string.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <libHX/defs.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <libHX/deque.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <libHX/string.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <pwd.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-
-\begin_inset Newline newline
-\end_inset
-
-int
-\series default
- main(
-\series bold
-void
-\series default
-)
-\begin_inset Newline newline
-\end_inset
-
-{
-\series bold
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series default
-        
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-dq = HXdeque_init();
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- passwd *pw;
-\begin_inset Newline newline
-\end_inset
-
-        
-\family typewriter
-\series bold
-unsigned int
-\series default
- elem;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-char **
-\series default
-users;
-\family default
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        setpwent();
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-while
-\series default
- ((pw = getpwent()) != NULL)
-\begin_inset Newline newline
-\end_inset
-
-                HXdeque_push(dq, HX_strdup(pw->pw_name));
-\begin_inset Newline newline
-\end_inset
-
-        endpwent();
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        users = 
-\series bold
-reinterpret_cast
-\series default
-(
-\series bold
-char **
-\series default
-, HXdeque_to_vec(dq, &elem));
-\begin_inset Newline newline
-\end_inset
-
-        HXdeque_free(dq);
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        qsort(users, elem, 
-\series bold
-sizeof
-\series default
-(*users), 
-\series bold
-static_cast
-\series default
-(
-\series bold
-void *
-\series default
-, strcmp));
-\begin_inset Newline newline
-\end_inset
-
-        return 0;
-\begin_inset Newline newline
-\end_inset
-
-}
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption Standard
-
-\begin_layout Plain Layout
-Example use of HXdeque to store and sort a list
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-In this example, all usernames are obtained from NSS, and put into a list.
- 
-\family typewriter
-HX_strdup
-\family default
- is used, because 
-\family typewriter
-getpwent
-\family default
- will overwrite the buffer it uses to store its results.
- The list is then converted to an array, and the list is freed (because
- it is not need it anymore).
- 
-\family typewriter
-HXdeque_genocide
-\family default
- must not be used here, because it would free all the data pointers (strings
- here) that were just inserted into the list.
- Finally, the list is sorted using the well-known 
-\family typewriter
-qsort
-\family default
- function.
- Because 
-\family typewriter
-strcmp
-\family default
- takes two 
-\family typewriter
-const char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
- arguments, but 
-\family typewriter
-qsort
-\family default
- mandates a function taking two 
-\family typewriter
-const void
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-, a cast can be used to silence the compiler.
- This only works because we know that the array consists of a bunch of 
-\family typewriter
-char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
- pointers, so 
-\family typewriter
-strcmp
-\family default
- will work.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Inline doubly-linked list
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:list"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Classical linked-list implementations, such as HXdeque, either store the
- actual data within a node, or indirectly through a pointer, but the 
-\begin_inset Quotes eld
-\end_inset
-
-inline doubly-linked list
-\begin_inset Quotes erd
-\end_inset
-
- instead does it reverse and has the list head within the data structure.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement h
-wide false
-sideways false
-status open
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- package_desc {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-char *
-\series default
-package_name;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-int
-\series default
- version;
-\end_layout
-
-\begin_layout LyX-Code
-};
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- classic_direct_node {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- classic_direct_node 
-\series bold
-*
-\series default
-next, 
-\series bold
-*
-\series default
-prev;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- package_desc direct_data;
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- classic_indirect_node {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- classic_indirect_node 
-\series bold
-*
-\series default
-next, 
-\series bold
-*
-\series default
-prev;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-void *
-\series default
-indirect_data;
-\begin_inset Newline newline
-\end_inset
-
-};
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption Standard
-
-\begin_layout Plain Layout
-Classic linked-list implementations with direct/indirect data blocks.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- package_desc {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- HXlist_head list;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-char *
-\series default
-package_name;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-int
-\series default
- version;
-\begin_inset Newline newline
-\end_inset
-
-};
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption Standard
-
-\begin_layout Plain Layout
-List head (next,prev pointers) inlined into the data block
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-At first glance, an inline list does not look much different from 
-\family typewriter
-struct classic_\SpecialChar softhyphen
-direct_\SpecialChar softhyphen
-data
-\family default
-, it is mostly a viewpoint decision which struct is in the foreground.
-\end_layout
-
-\begin_layout Subsection
-Synopsis
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/list.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/list.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXlist_head {
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-struct HXlist_head
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-All fields considered private
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXLIST_HEAD_INIT(name);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXLIST_HEAD_INIT
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXLIST_HEAD(name);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXLIST_HEAD
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXlist_init(
-\series bold
-struct
-\series default
- HXlist_head 
-\series bold
-*
-\series default
-list);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXlist_init
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXlist_add(
-\series bold
-struct
-\series default
- HXlist_head 
-\series bold
-*
-\series default
-list, 
-\series bold
-struct
-\series default
- HXlist_head 
-\series bold
-*
-\series default
-elem);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXlist_add
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXlist_add_tail(
-\series bold
-struct
-\series default
- HXlist_head 
-\series bold
-*
-\series default
-list, 
-\series bold
-struct
-\series default
- HXlist_head 
-\series bold
-*
-\series default
-elem);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXlist_add_tail
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXlist_del(
-\series bold
-struct
-\series default
- HXlist_head 
-\series bold
-*
-\series default
-element);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXlist_del
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-bool
-\series default
- HXlist_empty(
-\series bold
-const struct
-\series default
- HXlist_head 
-\series bold
-*
-\series default
-list);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXlist_empty
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXLIST_HEAD_INIT
-\family default
- This macro expands to the static initializer for a list head.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXLIST_HEAD
-\family default
- This macro expands to the definition of a list head (i.
-\begin_inset space \thinspace{}
-\end_inset
-
-e.
-\begin_inset space \space{}
-\end_inset
-
-
-\family typewriter
-struct HXlist_head name = HXLIST_HEAD_INIT;
-\family default
-)
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXlist_init
-\family default
- Initializes the list head.
- This function is generally used when the list head is on the heap where
- the static initializer cannot be used.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXlist_add
-\family default
- Adds 
-\family typewriter
-elem
-\family default
- to the front of the list.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXlist_add_tail
-\family default
- Adds 
-\family typewriter
-elem
-\family default
- to the end of the list.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXlist_del
-\family default
- Deletes the given element from the list.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXlist_empty
-\family default
- Tests whether the list is empty.
- Note: For clists, you could also use 
-\family typewriter
-clist->items == 0
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-Traversal
-\end_layout
-
-\begin_layout Standard
-Traversal is implemented using macros that expand to for() statements which
- can syntactically be used like them, i.
-\begin_inset space \thinspace{}
-\end_inset
-
-e.
-\begin_inset space \space{}
-\end_inset
-
-curly braces may be omitted if only a single statement is in the body of
- the loop.
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-head
-\family default
- parameter specifies the list head (
-\family typewriter
-struct HXlist_head
-\family default
-), 
-\family typewriter
-pos
-\family default
- specifies an iterator, also of type 
-\family typewriter
-struct HXlist_head
-\family default
-.
- Lists can either be traversed in forward direction, or, using the 
-\family typewriter
-_rev
-\family default
- variants, in reverse direction.
- The 
-\family typewriter
-_safe
-\family default
- variants use a temporary 
-\family typewriter
-n
-\family default
- to hold the next object in the list, which is needed when pos itself is
- going to be inaccessible at the end of the block, through, for example,
- freeing its encompassing object.
-\end_layout
-
-\begin_layout LyX-Code
-HXlist_for_each(pos, head)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXlist_for_each
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXlist_for_each_rev(pos, head)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXlist_for_each_rev
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXlist_for_each_safe(pos, n, head)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXlist_for_each_safe
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXlist_for_each_rev_safe(pos, n, head)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXlist_for_each_rev_safe
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXlist_for_each
-\family default
- Forward iteration over the list heads.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXlist_for_each_rev
-\family default
- Reverse iteration over the list heads.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXlist_for_each_safe
-\family default
- Forward iteration over the list heads that is safe against freeing 
-\family typewriter
-pos
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXlist_for_each_rev_safe
-\family default
- Reverse iteration over the list heads that is safe against freeing 
-\family typewriter
-pos
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-_entry
-\family default
- variants use an iterator 
-\family typewriter
-pos
-\family default
- of the type of the encompassing object (e.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
-\begin_inset space \space{}
-\end_inset
-
-
-\family typewriter
-struct item
-\family default
- in below's example), so that the manual 
-\family typewriter
-HXlist_entry
-\family default
- invocation is not needed.
- 
-\family typewriter
-member
-\family default
- is the name of the list structure embedded into the item.
-\end_layout
-
-\begin_layout LyX-Code
-HXlist_for_each_entry(pos, head, member)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXlist_for_each_entry
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXlist_for_each_entry_rev(pos, head, member)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXlist_for_each_entry_rev
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXlist_for_each_entry_safe(pos, n, head, member)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXlist_for_each_entry_safe
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXlist_for_each_entry
-\family default
- Forward iteration over the list elements.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXlist_for_each_entry_rev
-\family default
- Reverse iteration over the list elements.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXlist_for_each_entry_safe
-\family default
- Forward iteration over the list elements that is safe against freeing 
-\family typewriter
-pos
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-Examples
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- item {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- HXlist_head anchor;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-char
-\series default
- name
-\series bold
-[
-\series default
-32
-\series bold
-]
-\series default
-;
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXlist_head 
-\series bold
-*
-\series default
-e;
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- item 
-\series bold
-*
-\series default
-i, 
-\series bold
-*
-\series default
-j;
-\begin_inset Newline newline
-\end_inset
-
-HXLIST_HEAD(list);
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-i = malloc(
-\series bold
-sizeof
-\series default
-(
-\series bold
-*
-\series default
-i));
-\begin_inset Newline newline
-\end_inset
-
-HXlist_init(&e->anchor);
-\begin_inset Newline newline
-\end_inset
-
-strcpy(i->name, "foo");
-\begin_inset Newline newline
-\end_inset
-
-HXlist_add_tail(&list, &i->anchor);
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-i = malloc(
-\series bold
-sizeof
-\series default
-(
-\series bold
-*
-\series default
-i));
-\begin_inset Newline newline
-\end_inset
-
-HXlist_init(&e->anchor);
-\begin_inset Newline newline
-\end_inset
-
-strcpy(i->name, "bar");
-\begin_inset Newline newline
-\end_inset
-
-HXlist_add_tail(&list, &i->anchor);
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXlist_for_each(e, &list) {
-\begin_inset Newline newline
-\end_inset
-
-        i = HXlist_entry(e, 
-\series bold
-typeof
-\series default
-(
-\series bold
-*
-\series default
-i), anchor);
-\begin_inset Newline newline
-\end_inset
-
-        printf("e=%p i=%p name=%s
-\backslash
-n", e, i, i->name);
-\begin_inset Newline newline
-\end_inset
-
-}
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXlist_for_each_entry(i, &list, anchor)
-\begin_inset Newline newline
-\end_inset
-
-        printf("i=%p name=%s
-\backslash
-n", i, i->name);
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXlist_for_each_entry_rev(i, &list, anchor)
-\begin_inset Newline newline
-\end_inset
-
-        printf("i=%p name=%s
-\backslash
-n", i, i->name);
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXlist_for_each_entry_safe(i, j, &list, anchor) {
-\begin_inset Newline newline
-\end_inset
-
-        printf("i=%p name=%s
-\backslash
-n", i, i->name);
-\begin_inset Newline newline
-\end_inset
-
-        free(i);
-\begin_inset Newline newline
-\end_inset
-
-}
-\end_layout
-
-\begin_layout Subsection
-When to use HXdeque/HXlist
-\end_layout
-
-\begin_layout Standard
-The choice whether to use HXdeque or HXlist/HXclist depends on whether one
- wants the list head handling on the developer or on the library.
- Especially for 
-\begin_inset Quotes eld
-\end_inset
-
-atomic
-\begin_inset Quotes erd
-\end_inset
-
- and 
-\begin_inset Quotes eld
-\end_inset
-
-small
-\begin_inset Quotes erd
-\end_inset
-
- data, it might be easier to just let HXdeque do the management.
- Compare the following two code examples to store strings:
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout LyX-Code
-
-\series bold
-int
-\series default
- main(
-\family typewriter
-\series bold
-int
-\series default
- argc, 
-\series bold
-const char **
-\series default
-argv)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-dq = HXdeque_init();
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-while
-\series default
- (--argc)
-\begin_inset Newline newline
-\end_inset
-
-                 HXdeque_push(dq, ++argv);
-\begin_inset Newline newline
-\end_inset
-
-        
-\family default
-\series bold
-return
-\family typewriter
-\series default
- 0;
-\begin_inset Newline newline
-\end_inset
-
-}
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption Standard
-
-\begin_layout Plain Layout
-Storing strings in a HXdeque
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- element {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- HXlist_head list;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-char *
-\family typewriter
-\series default
-data;
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- main(
-\series bold
-int
-\series default
- main, 
-\series bold
-const char **
-\series default
-argv)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        HXLIST_HEAD(lh);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-while
-\series default
- (--argc) {
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-struct
-\series default
- element 
-\series bold
-*
-\series default
-e = malloc(
-\family default
-\series bold
-sizeof
-\family typewriter
-\series default
-(*e));
-\begin_inset Newline newline
-\end_inset
-
-                e->data = *++argv;
-\begin_inset Newline newline
-\end_inset
-
-                HXlist_init(&e->list);
-\begin_inset Newline newline
-\end_inset
-
-                HXlist_add_tail(&e->list);
-\begin_inset Newline newline
-\end_inset
-
-        }
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-return
-\series default
- 0;
-\begin_inset Newline newline
-\end_inset
-
-}
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption Standard
-
-\begin_layout Plain Layout
-Storing strings in a HXlist
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-These examples assume that 
-\family typewriter
-argv
-\family default
- is persistent, which, for the sample, is true.
-\end_layout
-
-\begin_layout Standard
-With HXlist, one needs to have a struct with a HXlist_head in it, and if
- one does not already have such a struct
-\begin_inset space ~
-\end_inset
-
-—e.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
-\begin_inset space \space{}
-\end_inset
-
-by means of wanting to store more than just one value
-\begin_inset space ~
-\end_inset
-
-— one will need to create it first, as shown, and this may lead to an expansion
- of code.
-\end_layout
-
-\begin_layout Standard
-This however does not mean that HXlist is the better solution over HXdeque
- for data already available in a struct.
- As each struct has a list_head that is unique to the node, it is not possible
- to share this data.
- Trying to add a HXlist_head to another list is not going to end well, while
- HXdeque has no problem with this as list heads are detached from the actual
- data in HXdeque.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- point p = {15, 30};
-\begin_inset Newline newline
-\end_inset
-
-HXdeque_push(dq, &p);
-\begin_inset Newline newline
-\end_inset
-
-HXdeque_push(dq, &p);
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption Standard
-
-\begin_layout Plain Layout
-Data can be added multiple times in a HXdeque without ill effects
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-To support this, an extra allocation is needed on the other hand.
- In a HXlist, to store 
-\begin_inset Formula $n$
-\end_inset
-
- elements of compound data (e.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
-\begin_inset space \space{}
-\end_inset
-
-
-\family typewriter
-struct point
-\family default
-), 
-\begin_inset Formula $n$
-\end_inset
-
- allocations are needed, assuming the list head is a stack object, and the
- points are not.
- HXdeque will need at least 
-\begin_inset Formula $2n+1$
-\end_inset
-
- allocations, 
-\begin_inset Formula $n$
-\end_inset
-
- for the nodes, 
-\begin_inset Formula $n$
-\end_inset
-
- for the points and another for the head.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Counted inline doubly-linked list
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:clist"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-clist is the inline doubly-linked list from chapter
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "sec:list"
-
-\end_inset
-
-, extended by a counter to retrieve the number of elements in the list in
- 
-\begin_inset Formula $\mathcal{O}\left(1\right)$
-\end_inset
-
- time.
- This is also why all operations always require the list head.
- For traversal of clists, use the corresponding HXlist macros.
-\end_layout
-
-\begin_layout Subsection
-Synopsis
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/list.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/list.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXclist_head {
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-struct HXclist_head
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-public readonly:
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-unsigned int
-\series default
- items;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-Undocumented fields are considered 
-\begin_inset Quotes eld
-\end_inset
-
-private
-\begin_inset Quotes erd
-\end_inset
-
-
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXCLIST_HEAD_INIT(name);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXCLIST_HEAD_INIT
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-HXCLIST_HEAD(name);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXCLIST_HEAD
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXclist_init(
-\series bold
-struct
-\series default
- HXclist_head 
-\series bold
-*
-\series default
-head);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXclist_init
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXclist_unshift(
-\series bold
-struct
-\series default
- HXclist_head 
-\series bold
-*
-\series default
-head, 
-\series bold
-struct
-\series default
- HXlist_head 
-\series bold
-*
-\series default
-new_node);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXclist_unshift
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXclist_push(
-\series bold
-struct
-\series default
- HXclist_head 
-\series bold
-*
-\series default
-head, 
-\series bold
-struct
-\series default
- HXlist_head 
-\series bold
-*
-\series default
-new_node);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXclist_push
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-type
-\series default
- HXclist_pop(
-\series bold
-struct
-\series default
- HXclist_head 
-\series bold
-*
-\series default
-head, 
-\series bold
-type
-\series default
-, member);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXclist_pop
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-type
-\series default
- HXclist_shift(
-\series bold
-struct
-\series default
- HXclist_head 
-\series bold
-*
-\series default
-head, 
-\series bold
-type
-\series default
-, member);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXclist_shift
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXclist_del(
-\series bold
-struct
-\series default
- HXclist_head 
-\series bold
-*
-\series default
-head, 
-\series bold
-struct 
-\series default
-HXlist_chead 
-\series bold
-*
-\series default
-node);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXclist_del
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXCLIST_HEAD_INIT
-\family default
- Macro that expands to the static initializer for a clist.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXCLIST_HEAD
-\family default
- Macro that expands to the definition of a clist head, with initialization.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXclist_init
-\family default
- Initializes a clist.
- This function is generally used when the head has been allocated from the
- heap.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXclist_unshift
-\family default
- Adds the node to the front of the list.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXclist_push
-\family default
- Adds the node to the end of the list.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXclist_pop
-\family default
- Removes the last node in the list and returns it.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXclist_shift
-\family default
- Removes the first node in the list and returns it.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXclist_del
-\family default
- Deletes the node from the list.
-\end_layout
-
-\begin_layout Standard
-The list count in the clist head is updated whenever a modification is done
- on the clist through these functions.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Part
-Strings and memory
-\end_layout
-
-\begin_layout Section
-String operations
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:strings"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Some string functions are merely present in libHX because they are otherwise
- unportable; some are only in the C libraries of the BSDs, some only in
- GNU libc.
-\end_layout
-
-\begin_layout Subsection
-Locating chars
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/string.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/string.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void *
-\series default
-HX_memmem(
-\series bold
-const void *
-\series default
-haystack, 
-\series bold
-size_t
-\series default
- hsize,
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-const void *
-\series default
-needle, 
-\series bold
-size_t
-\series default
- nsize);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_memmem
-\end_layout
-
-\end_inset
-
-
-\series bold
-
-\begin_inset Newline newline
-\end_inset
-
-char *
-\series default
-HX_strbchr(
-\series bold
-const char *
-\series default
-start, 
-\series bold
-const char *
-\series default
-now, 
-\series bold
-char
-\series default
- delimiter);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_strbchr
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_strchr2(
-\series bold
-const char *
-\series default
-s, 
-\series bold
-const char *
-\series default
-accept);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_strchr2
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-size_t
-\series default
- HX_strrcspn(
-\series bold
-const char *
-\series default
-s, 
-\series bold
-const char *
-\series default
-reject);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_strccspn
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_memmem
-\family default
- Analogous to 
-\family typewriter
-strstr
-\family default
-(3), 
-\family typewriter
-memmem
-\family default
- tries to locate the memory block pointed to by 
-\family typewriter
-needle
-\family default
- (which is of length 
-\family typewriter
-nsize
-\family default
-) in the block pointed to by 
-\family typewriter
-haystack
-\family default
- (which is of size 
-\family typewriter
-hsize
-\family default
-).
- It returns a pointer to the first occurrence in 
-\family typewriter
-haystack
-\family default
-, or 
-\family typewriter
-NULL
-\family default
- when it was not found.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strbchr
-\family default
- Searches the character specified by 
-\family typewriter
-delimiter
-\family default
- in the range from 
-\family typewriter
-now
-\family default
- to 
-\family typewriter
-start
-\family default
-.
- It works like 
-\family typewriter
-strrchr
-\family default
-(3)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-strrchr
-\end_layout
-
-\end_inset
-
-, but begins at 
-\family typewriter
-now
-\family default
- rather than the end of the string.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strchr2
-\family default
- This function searches the string 
-\family typewriter
-s
-\family default
- for any set of bytes that are not specified in the second argument, 
-\family typewriter
-n
-\family default
-.
- In this regard, the function is the opposite to 
-\family typewriter
-strpbrk
-\family default
-(3)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-strpbrk
-\end_layout
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strrcspn
-\family default
- Works like 
-\family typewriter
-strcspn
-\family default
-(3)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-strcspn
-\end_layout
-
-\end_inset
-
-, but processes the string from end to start.
-\end_layout
-
-\begin_layout Subsection
-Extraction
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/string.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/string.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_basename(
-\series bold
-const char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_basename
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_basename_exact(
-\series bold
-const char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_basename_exact
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_dirname(
-\series bold
-const char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_dirname
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_strmid(
-\series bold
-const char *
-\series default
-s, 
-\series bold
-long
-\series default
- offset, 
-\series bold
-long
-\series default
- length);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_strmid
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_basename
-\family default
- Returns a pointer to the basename portion of the supplied path 
-\family typewriter
-s
-\family default
-.
- The result of this function is never 
-\family typewriter
-NULL
-\family default
-, and must never be freed either.
- Trailing slashes are not stripped, to avoid having to do an allocation.
- In other words, 
-\family typewriter
-basename("/mnt/")
-\family default
- will return 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-mnt/
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-.
- If you need to have the slashes stripped, use 
-\family typewriter
-HX_basename_exact
-\family default
-.
- A possible use for this function is, for example, to derive a logging prefix
- from 
-\family typewriter
-argv[0]
-\family default
-.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-int
-\series default
- main(
-\series bold
-int
-\series default
- argc, 
-\series bold
-const char **
-\series default
-argv)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-if
-\series default
- (foo())
-\end_layout
-
-\begin_layout LyX-Code
-                fprintf(stderr, "%s: Special condition occurred.
-\backslash
-n",
-\begin_inset Newline newline
-\end_inset
-
-                        HX_basename(argv[0]));
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-return
-\series default
- 0;
-\begin_inset Newline newline
-\end_inset
-
-}
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_basename_exact
-\family default
- The accurate and safe version of 
-\family typewriter
-HX_basename
-\family default
- that deals with trailing slashes correctly and produces the same result
- as 
-\family typewriter
-dirname
-\family default
-(3).
- It returns a pointer to a newly-allocated string that must be freed when
- done using.
- 
-\family typewriter
-NULL
-\family default
- may be returned in case of an allocation error.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_dirname
-\family default
- Returns a pointer to a new string that contains the directory name portion
- (everything except basename).
- When done using the string, it must be freed to avoid memory leaks.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strmid
-\family default
- Extract a substring of 
-\family typewriter
-length
-\family default
- characters from 
-\family typewriter
-s
-\family default
-, beginning at 
-\family typewriter
-offset
-\family default
-.
- If 
-\family typewriter
-offset
-\family default
- is negative, counting beings from the end of the string; 
-\begin_inset Formula $-1$
-\end_inset
-
- is the last character (not the 
-\family typewriter
-'
-\backslash
-0'
-\family default
- byte).
- If 
-\family typewriter
-length
-\family default
- is negative, it will leave out that many characters off the end.
- The function returns a pointer to a new string, and the user has to free
- it.
-\end_layout
-
-\begin_layout Subsection
-In-place transformations
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/string.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/string.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_chomp(
-\series bold
-char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_chomp
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-size_t
-\series default
- HX_strltrim(
-\series bold
-char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_strltrim
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_stpltrim(
-\series bold
-const char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_stpltrim
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_strlower(
-\series bold
-char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_strlower
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_strrev(
-\series bold
-char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_strrev
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-size_t
-\series default
- HX_strrtrim(
-\series bold
-char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_strrtrim
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_strupper(
-\series bold
-char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_strupper
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_chomp
-\family default
- Removes the characters 
-\family typewriter
-'
-\backslash
-r'
-\family default
- and 
-\family typewriter
-'
-\backslash
-n'
-\family default
- from the right edge of the string.
- Returns the original argument.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strltrim
-\family default
- Trim all whitespace (characters on which 
-\family typewriter
-isspace
-\family default
-(3) return true) on the left edge of the string.
- Returns the number of characters that were stripped.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_stpltrim
-\family default
- Returns a pointer to the first non-whitespace character in 
-\family typewriter
-s
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strlower
-\family default
- Transforms all characters in the string 
-\family typewriter
-s
-\family default
- into lowercase using 
-\family typewriter
-tolower
-\family default
-(3).
- Returns the original argument.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strrev
-\family default
- Reverse the string in-place.
- Returns the original argument.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strrtrim
-\family default
- Trim all whitespace on the right edge of the string.
- Returns the number of characters that were stripped.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strupper
-\family default
- Transforms all characters in the string 
-\family typewriter
-s
-\family default
- into uppercase using 
-\family typewriter
-toupper
-\family default
-(3).
- Returns the original argument.
-\end_layout
-
-\begin_layout Subsection
-Out-of-place quoting transforms
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/string.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/string.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_strquote(
-\series bold
-const char *
-\series default
-s, 
-\series bold
-unsigned int
-\series default
- type, 
-\series bold
-char **
-\series default
-free_me);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_strquote
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HX_strquote
-\family default
- will escape metacharacters in a string according to 
-\family typewriter
-type
-\family default
-, and returns the escaped result.
-\end_layout
-
-\begin_layout Standard
-Possible values for 
-\family typewriter
-type
-\family default
-:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXQUOTE_SQUOTE
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXQUOTE_SQUOTE
-\end_layout
-
-\end_inset
-
- Escape all single quotes and backslashes in a string with a backslash.
- (
-\begin_inset Quotes eld
-\end_inset
-
-Ol' 
-\backslash
-Backslash
-\begin_inset Quotes erd
-\end_inset
-
- 
-\begin_inset Formula $\rightarrow$
-\end_inset
-
- 
-\begin_inset Quotes eld
-\end_inset
-
-Ol
-\backslash
-' 
-\backslash
-
-\backslash
-Backslash
-\begin_inset Quotes erd
-\end_inset
-
-)
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXQUOTE_DQUOTE
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXQUOTE_DQUOTE
-\end_layout
-
-\end_inset
-
- Escape all double quotes and backslahes in a string with the backslash
- method.
- (
-\begin_inset Quotes eld
-\end_inset
-
-Ol
-\begin_inset Quotes erd
-\end_inset
-
- 
-\backslash
-Backslash
-\begin_inset Quotes erd
-\end_inset
-
- 
-\begin_inset Formula $\rightarrow$
-\end_inset
-
- 
-\begin_inset Quotes eld
-\end_inset
-
-Ol
-\backslash
-
-\begin_inset Quotes erd
-\end_inset
-
- 
-\backslash
-
-\backslash
-Backslash
-\begin_inset Quotes erd
-\end_inset
-
-)
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXQUOTE_HTML
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXQUOTE_HTML
-\end_layout
-
-\end_inset
-
- Escape '
-\family typewriter
-<
-\family default
-', '
-\family typewriter
->
-\family default
-', '
-\family typewriter
-&
-\family default
-' and '
-\family typewriter
-"
-\family default
-' by their respective HTML entities 
-\family typewriter
-&lt;
-\family default
-, 
-\family typewriter
-&gt;
-\family default
-, 
-\family typewriter
-&amp;
-\family default
- and 
-\family typewriter
-&quot;
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXQUOTE_LDAPFLT
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXQUOTE_LDAPFLT
-\end_layout
-
-\end_inset
-
- Escape the string using backslash-plus-hexcode notation as described in
- RFC 4515
-\begin_inset Foot
-status open
-
-\begin_layout Plain Layout
-\begin_inset Flex URL
-status collapsed
-
-\begin_layout Plain Layout
-
-http://tools.ietf.org/html/rfc4515
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-, to make it suitable for use in an LDAP search filter.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXQUOTE_LDAPRDN
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXQUOTE_LDAPRDN
-\end_layout
-
-\end_inset
-
- Escape the string using backslash-plus-hexcode notation as described in
- RFC 4514
-\begin_inset Foot
-status open
-
-\begin_layout Plain Layout
-\begin_inset Flex URL
-status collapsed
-
-\begin_layout Plain Layout
-
-http://tools.ietf.org/html/rfc4514
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-, to make it suitable for use in an LDAP Relative Distinguished Name.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXQUOTE_BASE64
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXQUOTE_BASE64
-\end_layout
-
-\end_inset
-
- Transform the string to BASE64, as described in RFC 4648
-\begin_inset Foot
-status open
-
-\begin_layout Plain Layout
-\begin_inset Flex URL
-status collapsed
-
-\begin_layout Plain Layout
-
-http://tools.ietf.org/html/rfc4648
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXQUOTE_URIENC
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXQUOTE_URIENC
-\end_layout
-
-\end_inset
-
- Escape the string so that it becomes a valid part for an URI.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXQUOTE_SQLSQUOTE
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXQUOTE_SQLSQUOTE
-\end_layout
-
-\end_inset
-
- Escape all single quotes in the string by double single-quotes, as required
- for using it in a single-quoted SQL string.
- No surrounding quotes will be generated to facilitate concatenating of
- 
-\family typewriter
-HX_strquote
-\family default
- results.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXQUOTE_SQLBQUOTE
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXQUOTE_SQLBQUOTE
-\end_layout
-
-\end_inset
-
- Escape all backticks in the string by double backticks, as required for
- using it in a backtick-quoted SQL string (used for table names and columns).
- No surrounding ticks will be generated to facilitate concatenation.
-\end_layout
-
-\begin_layout Standard
-Specifying an unrecognized type will result in 
-\family typewriter
-NULL
-\family default
- being returned and 
-\family typewriter
-errno
-\family default
- be set to 
-\family typewriter
-EINVAL
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-If 
-\family typewriter
-free_me
-\family default
- is 
-\family typewriter
-NULL
-\family default
-, the function will always allocate memory, even if the string needs no
- quoting.
- The program then has to free the result:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-char *
-\series default
-s = HX_strquote("<head>", HXQUOTE_HTML, NULL);
-\begin_inset Newline newline
-\end_inset
-
-printf("%s
-\backslash
-n", s);
-\begin_inset Newline newline
-\end_inset
-
-free(s);
-\end_layout
-
-\begin_layout Standard
-If 
-\family typewriter
-free_me
-\family default
- is not 
-\family typewriter
-NULL
-\family default
- however, the function will put the pointer to the memory area into 
-\family typewriter
-*free_me
-\family default
-, if the string needed quoting.
- The program then has to free that after it is done with the quoted result:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-char *
-\series default
-tmp = NULL;
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-s = HX_strquote("head", HXQUOTE_HTML, &tmp);
-\begin_inset Newline newline
-\end_inset
-
-printf("%s
-\backslash
-n", s);
-\begin_inset Newline newline
-\end_inset
-
-free(tmp);
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-tmp
-\family default
- could be 
-\family typewriter
-NULL
-\family default
-, and since 
-\family typewriter
-free(NULL)
-\family default
- is not an error, this is perfectly valid.
- Furthermore, if 
-\family typewriter
-*free_me
-\family default
- is not 
-\family typewriter
-NULL
-\family default
- by the time 
-\family typewriter
-HX_strquote
-\family default
- is called, the function will free it.
- This makes it possible to call 
-\family typewriter
-HX_strquote
-\family default
- in succession without 
-\family typewriter
-free
-\family default
-s in between:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-char *
-\series default
-tmp = NULL;
-\begin_inset Newline newline
-\end_inset
-
-printf("%s
-\backslash
-n", HX_strquote("<html>", HXQUOTE_HTML, &tmp));
-\begin_inset Newline newline
-\end_inset
-
-printf("%s
-\backslash
-n", HX_strquote("<head>", HXQUOTE_HTML, &tmp));
-\begin_inset Newline newline
-\end_inset
-
-free(tmp);
-\end_layout
-
-\begin_layout Subsection
-Tokenizing
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/string.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/string.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char **
-\series default
-HX_split(
-\series bold
-const char *
-\series default
-s, 
-\series bold
-const char *
-\series default
-delimiters,
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-size_t *
-\series default
-fields, 
-\series bold
-int
-\series default
- max);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_split
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char **
-\series default
-HX_split_inplace(
-\series bold
-char *
-\series default
-s, 
-\series bold
-const char *
-\series default
-delimiters, 
-\series bold
-int *
-\series default
-fields, 
-\series bold
-int
-\series default
- max);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_split_inplace
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_split_fixed(
-\series bold
-char *
-\series default
-s, 
-\series bold
-const char *
-\series default
-delimiters, 
-\series bold
-int
-\series default
- max, 
-\series bold
-char **
-\series default
-arr);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_split_fixed
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_strsep(
-\series bold
-char **
-\series default
-sp, 
-\series bold
-const char *
-\series default
-delimiters);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_strsep
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_strsep2(
-\series bold
-char **
-\series default
-sp, 
-\series bold
-const char *
-\series default
-dstr);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_strsep2
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_split
-\family default
- Split the string 
-\family typewriter
-s
-\family default
- on any characters from the 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-delimiters
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- string.
- Both the substrings and the array holding the pointers to these substrings
- will be allocated as required; the original string is not modified.
- If 
-\family typewriter
-max
-\family default
- is larger than zero, produces no more than 
-\family typewriter
-max
-\family default
- fields.
- If 
-\family typewriter
-fields
-\family default
- is not 
-\family typewriter
-NULL
-\family default
-, the number of elements produced will be stored in 
-\family typewriter
-*fields
-\family default
-.
- The result is a 
-\family typewriter
-NULL
-\family default
--terminated array of 
-\family typewriter
-char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-, and the user needs to free it when done with it, using 
-\family typewriter
-HX_zvecfree
-\family default
- or equivalent.
- An empty string (zero-length string) for 
-\family typewriter
-s
-\family default
- yields a single field.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_split_inplace
-\family default
- Split the string 
-\family typewriter
-s
-\family default
- in-place on any characters from the 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-delimiters
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- string.
- The array that will be holding the pointers to the substrings will be allocated
- and needs to be freed by the user, using 
-\family typewriter
-free
-\family default
-(3).
- The 
-\family typewriter
-fields
-\family default
- and 
-\family typewriter
-max
-\family default
- arguments work as with 
-\family typewriter
-HX_split
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_split_fixed
-\family default
- Split the string 
-\family typewriter
-s
-\family default
- in-place on any characters from the 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-delimiters
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- string.
- The array for the substring pointers must be provided by the user through
- the 
-\family typewriter
-arr
-\family default
- argument.
- 
-\family typewriter
-max
-\family default
- must be the number of elements in the array or less.
- The array will not be 
-\family typewriter
-NULL
-\family default
--terminated
-\begin_inset Foot
-status open
-
-\begin_layout Plain Layout
-An implementation may however decide to put NULL in the unassigned fields,
- but this is implementation and situation-specific.
- Do not rely on it.
-\end_layout
-
-\end_inset
-
-.
- The number of fields produced is returned.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strsep
-\family default
- Extract tokens from a string.
-\begin_inset Newline newline
-\end_inset
-
-This implementation of 
-\family typewriter
-strsep
-\family default
- has been added since the function is non-standard (according to the manpage,
- conforms to BSD4.4 only) and may not be available on every operating system.
-\begin_inset Newline newline
-\end_inset
-
-This function extracts tokens, separated by one of the characters in 
-\family typewriter
-delimiters
-\family default
-.
- The string is modified in-place and thus must be writable.
- The delimiters in the string are then overwritten with 
-\family typewriter
-'
-\backslash
-0'
-\family default
-, 
-\family typewriter
-*sp
-\family default
- is advanced to the character after the delimiter, and the original pointer
- is returned.
- After the final token, 
-\family typewriter
-strsep
-\family default
- will return 
-\family typewriter
-NULL
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strsep2
-\family default
- Like 
-\family typewriter
-HX_strsep
-\family default
-, but 
-\family typewriter
-dstr
-\family default
- is not an array of delimiting characters, but an entire substring that
- acts as a delimiter.
-\end_layout
-
-\begin_layout Subsection
-Size-bounded string ops
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/string.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-libHX/string.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_strlcat(
-\series bold
-char *
-\series default
-dest, 
-\series bold
-const char *
-\series default
-src, 
-\series bold
-size_t
-\series default
- length);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_strlcat
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_strlcpy(
-\series bold
-char *
-\series default
-dest, 
-\series bold
-const char *
-\series default
-src, 
-\series bold
-size_t
-\series default
- length);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_strlcpy
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_strlncat(
-\series bold
-char *
-\series default
-dest, 
-\series bold
-const char *
-\series default
-src, 
-\series bold
-size_t
-\series default
- dlen, 
-\series bold
-size_t
-\series default
- slen);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_strlncat
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-size_t
-\series default
- HX_strnlen(
-\series bold
-const char *
-\series default
-src, 
-\series bold
-size_t
-\series default
- max);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_strnlen
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HX_strlcat
-\family default
- and 
-\family typewriter
-HX_strlcpy
-\family default
- provide implementations of the BSD-originating 
-\family typewriter
-strlcat
-\family default
-(3)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-strlcat
-\end_layout
-
-\end_inset
-
- and 
-\family typewriter
-strlcpy
-\family default
-(3)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-strlcpy
-\end_layout
-
-\end_inset
-
-.
- 
-\family typewriter
-strlcat
-\family default
- and 
-\family typewriter
-strlcpy
-\family default
- are less error-prone variants for 
-\family typewriter
-strncat
-\family default
- and 
-\family typewriter
-strncpy
-\family default
- as they always take the length of the entire buffer specified by 
-\family typewriter
-dest
-\family default
-, instead of just the length that is to be written.
- The functions guarantee that the buffer is 
-\family typewriter
-'
-\backslash
-0'
-\family default
--terminated.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HX_strnlen
-\family default
- will return the length of the input string or the upper bound given by
- 
-\family typewriter
-max
-\family default
-, whichever is less.
- It will not attempt to access more than this many bytes in the input buffer.
-\end_layout
-
-\begin_layout Subsection
-Allocation-related
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/string.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/string.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void *
-\series default
-HX_memdup(
-\series bold
-const void *
-\series default
-ptr, 
-\series bold
-size_t
-\series default
- length);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_memdup
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_strdup(
-\series bold
-const char *
-\series default
-str);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_strdup
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-HX_strndup(
-\series bold
-const char *
-\series default
-str, 
-\series bold
-size_t
-\series default
- max);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_strndup
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-
-\begin_inset Note Greyedout
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series bold
-char *
-\series default
-HX_strclone(
-\series bold
-char **
-\series default
-pa, 
-\series bold
-const char *
-\series default
-pb);
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_strclone
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-
-\begin_inset Newline newline
-\end_inset
-
-#ifdef
-\series default
- __cplusplus
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-template<typename type> type
-\series default
- HX_memdup(
-\series bold
-const void *
-\series default
-ptr, 
-\series bold
-size_t
-\series default
- length);
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#endif
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_memdup
-\family default
- Duplicates 
-\family typewriter
-length
-\family default
- bytes from the memory area pointed to by 
-\family typewriter
-ptr
-\family default
- and returns a pointer to the new memory block.
- 
-\family typewriter
-ptr
-\family default
- may not be 
-\family typewriter
-NULL
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strdup
-\family default
- Duplicates the string.
- The function is equivalent to 
-\family typewriter
-strdup
-\family default
-, but the latter may not be available on all platforms.
- 
-\family typewriter
-str
-\family default
- may be 
-\family typewriter
-NULL
-\family default
-, in which case 
-\family typewriter
-NULL
-\family default
- is also returned.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strndup
-\family default
- Duplicates the input string, but copies at most 
-\family typewriter
-max
-\family default
- characters.
- (The resulting string will be NUL-terminated of course.) 
-\family typewriter
-str
-\family default
- may not be 
-\family typewriter
-NULL
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_strclone
-\family default
- Copies the string pointed to by 
-\family typewriter
-pb
-\family default
- into 
-\family typewriter
-*pa
-\family default
-.
- If 
-\family typewriter
-*pa
-\family default
- was not 
-\family typewriter
-NULL
-\family default
- by the time 
-\family typewriter
-HX_strclone
-\family default
- was called, the string is freed before a new one is allocated.
- The function returns 
-\family typewriter
-NULL
-\family default
- and sets 
-\family typewriter
-errno
-\family default
- to 
-\family typewriter
-EINVAL
-\family default
- if 
-\family typewriter
-pb
-\family default
- is 
-\family typewriter
-NULL
-\family default
- (this way it can be freed), or, if 
-\family typewriter
-malloc
-\family default
- fails, returns 
-\family typewriter
-NULL
-\family default
- and leaves 
-\family typewriter
-errno
-\family default
- at what 
-\family typewriter
-malloc
-\family default
- set it to.
-\begin_inset Newline newline
-\end_inset
-
-The use of this function is deprecated, albeit no replacement is proposed.
-\end_layout
-
-\begin_layout Subsection
-Examples
-\end_layout
-
-\begin_layout Subsubsection
-Using HX_split_fixed
-\begin_inset CommandInset label
-LatexCommand label
-name "subsec:string-ex-HX_split_fixed"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HX_split_fixed
-\family default
- is often used just with scoped automatic-storage variables and where the
- field count of interest is fixed, as the example for parsing 
-\family typewriter
-/etc/passwd
-\family default
- shows:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <stdio.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <libHX/string.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-field[8];
-\begin_inset Newline newline
-\end_inset
-
-hxmc_t 
-\series bold
-*
-\series default
-line = NULL;
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-while
-\series default
- (HX_getl(&line, fp) != NULL) {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-if
-\series default
- (HX_split_fixed(line, ":", ARRAY_SIZE(field), field) < 7) {
-\begin_inset Newline newline
-\end_inset
-
-                fprintf(stderr, "That does not look like a valid line.
-\backslash
-n");
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-continue
-\series default
-;
-\begin_inset Newline newline
-\end_inset
-
-        }
-\begin_inset Newline newline
-\end_inset
-
-        printf("Username: %s
-\backslash
-n", field[0]);
-\begin_inset Newline newline
-\end_inset
-
-}
-\end_layout
-
-\begin_layout Subsubsection
-Using HX_split_inplace
-\end_layout
-
-\begin_layout Standard
-Where the number of fields is not previously known and/or estimatable, but
- the string can be modified in place, one uses 
-\family typewriter
-HX_split_inplace
-\family default
- as follows:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <errno.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <stdio.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <libHX/string.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-while
-\series default
- (HX_getl(&line, fp) != NULL) {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-char **
-\series default
-field = HX_split_inplace(line, ":", NULL, 0);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-if
-\series default
- (field == NULL) {
-\begin_inset Newline newline
-\end_inset
-
-                fprintf(stderr, "Badness! %s
-\backslash
-n", strerror(errno));
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-break
-\series default
-;
-\begin_inset Newline newline
-\end_inset
-
-        }
-\begin_inset Newline newline
-\end_inset
-
-        printf("Username: %s
-\backslash
-n", field[0]);
-\begin_inset Newline newline
-\end_inset
-
-        free(field);
-\begin_inset Newline newline
-\end_inset
-
-}
-\end_layout
-
-\begin_layout Subsubsection
-Using HX_split
-\end_layout
-
-\begin_layout Standard
-Where the string is not modifiable in-place, one has to resort to using
- the full-fledged 
-\family typewriter
-HX_split
-\family default
- that allocates space for each substring.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <errno.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <stdio.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <libHX/string.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-while
-\series default
- (HX_getl(&line, fp) != NULL) {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-char **
-\series default
-field = HX_split(line, ":", NULL, 0);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-if
-\series default
- (field == NULL) {
-\begin_inset Newline newline
-\end_inset
-
-                fprintf(stderr, "Badness.
- %s
-\backslash
-n", strerror(errno));
-\begin_inset Newline newline
-\end_inset
-
-                break;
-\begin_inset Newline newline
-\end_inset
-
-        }
-\begin_inset Newline newline
-\end_inset
-
-        printf("Username: %s
-\backslash
-n", field[0]);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-Suppose 
-\begin_inset Quotes eld
-\end_inset
-
-callme
-\begin_inset Quotes erd
-\end_inset
-
- needs the original string
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-        callme(line);
-\begin_inset Newline newline
-\end_inset
-
-        HX_zvecfree(field);
-\begin_inset Newline newline
-\end_inset
-
-}
-\end_layout
-
-\begin_layout Subsubsection
-Using HX_strsep
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HX_strsep
-\family default
- provides for thread- and reentrant-safe tokenizing a string where strtok
- from the C standard would otherwise fail.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <stdio.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <libHX/string.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char
-\series default
- line
-\series bold
-[]
-\series default
- = "root:x:0:0:root:/root:/bin/bash";
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-wp, 
-\series bold
-*
-\series default
-p;
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-wp = line;
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-while
-\series default
- ((p = HX_strsep(&wp, ":")) != NULL)
-\begin_inset Newline newline
-\end_inset
-
-        printf("%s
-\backslash
-n", p)
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Memory containers
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:mc"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The HXmc series of functions provide scripting-like semantics for strings,
- especially automatically resizing the buffer on demand.
- They can also be used to store a binary block of data together with its
- length.
- (Hence the name: mc = memory container.)
-\end_layout
-
-\begin_layout Standard
-The benefit of using the HXmc functions is that one does not have to meticulousl
-y watch buffer and string sizes anymore.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Paragraph
-/* Step
-\begin_inset space ~
-\end_inset
-
-1 */
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-char
-\series default
- buf
-\series bold
-[
-\family roman
-\series default
-\shape italic
-whatever was believed to be long enough
-\family default
-\series bold
-\shape default
-]
-\series default
- = "helloworld";
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-if
-\series default
- (strlen(buf) + strlen(".txt") < 
-\series bold
-sizeof
-\series default
-(buf))
-\begin_inset Newline newline
-\end_inset
-
-        strcat(s, ".txt");
-\end_layout
-
-\begin_layout Paragraph
-/* Step
-\begin_inset space ~
-\end_inset
-
-2 */
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-char
-\series default
- buf
-\series bold
-[
-\family roman
-\series default
-\shape italic
-long_enough
-\family default
-\series bold
-\shape default
-]
-\series default
- = "helloworld";
-\end_layout
-
-\begin_layout LyX-Code
-strlcat(s, ".txt", 
-\series bold
-sizeof
-\series default
-(buf));
-\end_layout
-
-\begin_layout Paragraph
-/* Step
-\begin_inset space ~
-\end_inset
-
-3 */
-\end_layout
-
-\begin_layout LyX-Code
-hxmc_t 
-\series bold
-*
-\series default
-buf = HXmc_strinit("helloworld");
-\begin_inset Newline newline
-\end_inset
-
-HXmc_strcat(&s, ".txt");
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption Standard
-
-\begin_layout Plain Layout
-Improvement of string safety over time
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-This makes it quite similar to the string operations (and append seems to
- be the most commonly used one to me) supported in scripting languages that
- also do without a size argument.
- The essential part of such memory containers is that their internal (hidden)
- metadata structure contains the length of the memory block in the container.
- For binary data this may be the norm, but for C-style strings, the stored
- and auto-updated length field serves as an accelerator cache.
- For more details, see 
-\family typewriter
-HXmc_length
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-Of course, the automatic management of memory comes with a bit of overhead
- as the string expands beyond its preallocated region.
- Such may be mitigated by doing explicit (re)sizing.
-\end_layout
-
-\begin_layout Subsection
-Structural overview
-\end_layout
-
-\begin_layout Standard
-HXmc functions do not actually return a pointer to the memory container
- (e.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
-\begin_inset space \space{}
-\end_inset
-
-
-\family typewriter
-struct
-\family default
-) itself, but a pointer to the data block.
- Conversely, input parameters to HXmc functions will be the data block pointer.
- It is of type 
-\family typewriter
-hxmc_t
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-, which is typedef'ed to 
-\family typewriter
-char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
- and inherits all properties and privileges of 
-\family typewriter
-char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-.
- Pointer arithmetic is thus supported.
- It also means you can just pass it to functions that take a 
-\family typewriter
-char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
- without having to do a member access like 
-\family typewriter
-s.c_str
-\family default
-.
- The drawback is that many functions operating on the memory container need
- a 
-\family typewriter
-hxmc_t
-\begin_inset space ~
-\end_inset
-
-**
-\family default
- (a level-two indirection), because not only does the memory block move,
- but also the memory container itself.
- This is due to the implementation of the container metadata which immediately
- and always precedes the writable memory block.
-\end_layout
-
-\begin_layout Standard
-HXmc ensures that the data block is terminated by a NUL (
-\family typewriter
-'
-\backslash
-0'
-\family default
-) byte (unless you trash it), so you do not have to, and of course, to be
- on the safe side.
- But, the automatic NUL byte is not part of the region allocated by the
- user.
- That is, when one uses the classic approach with 
-\family typewriter
-malloc(4096)
-\family default
-, the user will have control of 4096 bytes and has to stuff the NUL byte
- in there somehow on his own; for strings this means the maximum string
- length is 4095.
- Requesting space for a 4096-byte sized HXmc container gives you the possibility
- to use all 4096 bytes for the string, because HXmc provides a NUL byte.
-\end_layout
-
-\begin_layout Standard
-By the way, 
-\family typewriter
-hxmc_t
-\family default
- is the 
-\shape italic
-only
-\shape default
- typedef in this entire library, to distinguish it from regular 
-\family typewriter
-char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
- that does not have a backing memory cointainer.
-\end_layout
-
-\begin_layout Subsection
-Constructors, destructors
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/string.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/string.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-hxmc_t 
-\series bold
-*
-\series default
-HXmc_strinit(
-\series bold
-const char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmc_strinit
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-hxmc_t 
-\series bold
-*
-\series default
-HXmc_meminit(
-\series bold
-const void *
-\series default
-ptr, 
-\series bold
-size_t
-\series default
- size);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmc_meminit
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmc_strinit
-\family default
- Creates a new hxmc_t object from the supplied string and returns it.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmc_meminit
-\family default
- Creates a new hxmc_t object from the supplied memory buffer of the given
- size and returns it.
- 
-\family typewriter
-HXmc_meminit(NULL, len)
-\family default
- may be used to obtain an empty container with a preallocated region of
- 
-\family typewriter
-len
-\family default
- bytes (zero is accepted for 
-\family typewriter
-len
-\family default
-).
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-void
-\series default
- HXmc_free(hxmc_t 
-\series bold
-*
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmc_free
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXmc_zvecfree(hxmc_t 
-\series bold
-**
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmc_zvecfree
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmc_free
-\family default
- Frees the hxmc object.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmc_zvecfree
-\family default
- Frees all hxmc objects in the NULL-terminated array, and finally frees
- the array itself, similar to 
-\family typewriter
-HX_zvecfree
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-Data manipulation
-\end_layout
-
-\begin_layout Subsubsection
-Binary-based
-\end_layout
-
-\begin_layout LyX-Code
-hxmc_t 
-\series bold
-*
-\series default
-HXmc_trunc(hxmc_t 
-\series bold
-**
-\series default
-mc, 
-\series bold
-size_t
-\series default
- len);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXmc_trunc
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-hxmc_t 
-\series bold
-*
-\series default
-HXmc_setlen(hxmc_t 
-\series bold
-**
-\series default
-mc, 
-\series bold
-size_t
-\series default
- len);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXmc_setlen
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-hxmc_t 
-\series bold
-*
-\series default
-HXmc_memcpy(hxmc_t 
-\series bold
-**
-\series default
-mc, 
-\series bold
-const void *
-\series default
-ptr, 
-\series bold
-size_t
-\series default
- len);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXmc_memcpy
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-hxmc_t 
-\series bold
-*
-\series default
-HXmc_memcat(hxmc_t 
-\series bold
-**
-\series default
-mc, 
-\series bold
-const void *
-\series default
-ptr, 
-\series bold
-size_t
-\series default
- len);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXmc_memcat
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-hxmc_t 
-\series bold
-*
-\series default
-HXmc_mempcat(hxmc_t 
-\series bold
-**
-\series default
-mc, 
-\series bold
-const void *
-\series default
-ptr, 
-\series bold
-size_t
-\series default
- len);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXmc_mempcat
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-hxmc_t 
-\series bold
-*
-\series default
-HXmc_memins(hxmc_t 
-\series bold
-**
-\series default
-mc, 
-\series bold
-size_t
-\series default
- pos, 
-\series bold
-const void *
-\series default
-ptr, 
-\series bold
-size_t
-\series default
- len);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_memins
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-hxmc_t 
-\series bold
-*
-\series default
-HXmc_memdel(hxmc_t 
-\series bold
-**
-\series default
-mc, 
-\series bold
-size_t
-\series default
- pos, 
-\series bold
-size_t
-\series default
- len);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_memdel
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-When 
-\family typewriter
-ptr
-\family default
- is 
-\family typewriter
-NULL
-\family default
-, each call behaves as if 
-\family typewriter
-len
-\family default
- would be zero.
- Specifically, no undefined behavior will result of the use of 
-\family typewriter
-NULL
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmc_trunc
-\family default
- Truncates the container's data to 
-\family typewriter
-len
-\family default
- size.
- If 
-\family typewriter
-len
-\family default
- is greater than the current data size of the container, the length is in
- fact 
-\shape italic
-not
-\shape default
- updated, but a reallocation may be triggered, which can be used to do explicit
- allocation.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmc_setlen
-\family default
- Set the data length, doing a reallocation of the memory container if needed.
- The newly available bytes are uninitialized.
- Make use of this function when letting 3rd party functions write to the
- buffer, but it should not be used with 
-\family typewriter
-HXmc_str*
-\family default
-(), 
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmc_memcpy
-\family default
- Truncates the container's data and copies 
-\family typewriter
-len
-\family default
- bytes from the memory area pointed to by 
-\family typewriter
-ptr
-\family default
- to the container.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmc_memcat
-\family default
- Concatenates (appends) 
-\family typewriter
-len
-\family default
- bytes from the memory area pointed to by 
-\family typewriter
-ptr
-\family default
- to the container's data.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmc_mempcat
-\family default
- Prepends 
-\family typewriter
-len
-\family default
- bytes from the memory area pointed to by 
-\family typewriter
-ptr
-\family default
- to the container's data.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmc_memins
-\family default
- Prepends 
-\family typewriter
-len
-\family default
- bytes from the memory area pointed to by 
-\family typewriter
-ptr
-\family default
- to the 
-\family typewriter
-pos
-\family default
-'th byte of the container's data.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmc_memdel
-\family default
- Deletes 
-\family typewriter
-len
-\family default
- bytes from the container beginning at position 
-\family typewriter
-pos
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-In case of a memory allocation failure, the 
-\family typewriter
-HXmc_*
-\family default
- functions will return 
-\family typewriter
-NULL
-\family default
-.
-\end_layout
-
-\begin_layout Subsubsection
-String-based
-\end_layout
-
-\begin_layout Standard
-The string-based functions correspond to their binary-based equivalents
- with a 
-\family typewriter
-len
-\family default
- argument of 
-\family typewriter
-strlen(s)
-\family default
-.
-\end_layout
-
-\begin_layout LyX-Code
-hxmc_t 
-\series bold
-*
-\series default
-HXmc_strcpy(hxmc_t 
-\series bold
-**
-\series default
-mc, 
-\series bold
-const char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXmc_strcpy
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-hxmc_t 
-\series bold
-*
-\series default
-HXmc_strcat(hxmc_t 
-\series bold
-**
-\series default
-mc, 
-\series bold
-const char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXmc_strcat
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-hxmc_t 
-\series bold
-*
-\series default
-HXmc_strpcat(hxmc_t 
-\series bold
-**
-\series default
-mc, 
-\series bold
-const char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXmc_strpcat
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-hxmc_t 
-\series bold
-*
-\series default
-HXmc_strins(hxmc_t 
-\series bold
-**
-\series default
-mc, 
-\series bold
-size_t
-\series default
- pos, 
-\series bold
-const char *
-\series default
-s);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXmc_strins
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmc_strcpy
-\family default
- Copies the string pointed to by 
-\family typewriter
-s
-\family default
- into the memory container given by 
-\family typewriter
-mc
-\family default
-.
- If 
-\family typewriter
-mc
-\family default
- is 
-\family typewriter
-NULL
-\family default
-, the memory container will be deallocated, that is, 
-\family typewriter
-*mc
-\family default
- becomes 
-\family typewriter
-NULL
-\family default
-.
-\end_layout
-
-\begin_layout Subsubsection
-From auxiliary sources
-\end_layout
-
-\begin_layout LyX-Code
-hxmc_t 
-\series bold
-*
-\series default
-HX_getl(hxmc_t 
-\series bold
-**
-\series default
-mc, FILE 
-\series bold
-*
-\series default
-fp);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_getl
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_getl
-\family default
- Read the next line from 
-\family typewriter
-fp
-\family default
- and store the result in the container.
- Returns 
-\family typewriter
-NULL
-\family default
- on error, or when end of file occurs while no characters have been read.
-\end_layout
-
-\begin_layout Subsection
-Container properties
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-size_t
-\series default
- HXmc_length(
-\series bold
-const
-\series default
- hxmc_t 
-\series bold
-**
-\series default
-mc);
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXmc_length
-\family default
- Returns the length of the memory container.
- This is not always equal to the actual string length.
- For example, if 
-\family typewriter
-HX_chomp
-\family default
- was used on an MC-backed string, 
-\family typewriter
-strlen
-\family default
- will return less than 
-\family typewriter
-HXmc_length
-\family default
- if newline control characters (
-\family typewriter
-'
-\backslash
-r'
-\family default
- and 
-\family typewriter
-'
-\backslash
-n'
-\family default
-) were removed.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Format templates
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:format"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-HXfmt is a small template system for by-name variable expansion.
- It can be used to substitute placeholders in format strings supplied by
- the user by appropriate expanded values defined by the program.
- Such can be used to allow for flexible configuration files that define
- key-value mappings such as
-\end_layout
-
-\begin_layout LyX-Code
-detect_peer = ping6 -c1 %(ADDR)
-\begin_inset Newline newline
-\end_inset
-
-#detect_peer = nmap -sP %(ADDR) | grep -Eq "appears to be up"
-\end_layout
-
-\begin_layout Standard
-Consider for example a monitoring daemon that allows the administrator to
- specify a program of his choice with which to detect whether a peer is
- alive or not.
- The user can choose any program that is desired, but evidently needs to
- pass the address to be tested to the program.
- This is where the daemon will do a substitution of the string 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-ping -c1 %(ADDR)
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- it read from the config file, and put the actual address in it before finally
- executing the command.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout LyX-Code
-printf("%s has %u files
-\backslash
-n", user, num);
-\begin_inset Newline newline
-\end_inset
-
-printf("%2$u files belong to %1$s
-\backslash
-n", num, user);
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-%s
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- (or 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-%1$s
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- here) specifies how large 
-\begin_inset Quotes eld
-\end_inset
-
-user
-\begin_inset Quotes erd
-\end_inset
-
- is
-\begin_inset space ~
-\end_inset
-
-— 
-\family typewriter
-sizeof(const char *)
-\family default
- in this case.
- If that is missing, there is no way to know the offset of 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-num
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- relative to 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-user
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-, making varargs retrieval impossible.
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption Standard
-
-\begin_layout Plain Layout
-
-\family typewriter
-printf
-\family default
- positional parameters
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-printf
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-printf
-\end_layout
-
-\end_inset
-
-, at least from GNU libc, has something vaguely similar: positional parameters
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-positional parameters
-\end_layout
-
-\end_inset
-
-.
- They have inherent drawbacks, though.
- One is of course the question of portability, but there is a bigger issue.
- All parameters must be specified, otherwise there is no way to determine
- the location of all following objects following the missing one on the
- stack in a varargs-function like 
-\family typewriter
-printf
-\family default
-., which makes it unsuitable to be used with templates where omitting some
- placeholders is allowed.
-\end_layout
-
-\begin_layout Subsection
-Initialization, use and deallocation
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/option.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/option.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXformat_map 
-\series bold
-*
-\series default
-HXformat_init(
-\series bold
-void
-\series default
-);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXformat_init
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXformat_free(
-\series bold
-struct
-\series default
- HXformat_map 
-\series bold
-*
-\series default
-table);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXformat_free
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HXformat_add(
-\series bold
-struct
-\series default
- HXformat_map 
-\series bold
-*
-\series default
-table, 
-\series bold
-const char *
-\series default
-key,
-\begin_inset Newline newline
-\end_inset
-
-                 
-\series bold
-const void *
-\series default
-ptr, 
-\series bold
-unsigned int
-\series default
- ptr_type);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXformat_add
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HXformat_init
-\family default
- will allocate and set up a simple string-to-string map that is used for
- the underlying storage, and returns it.
-\end_layout
-
-\begin_layout Standard
-To release the substitution table and memory associated with it, call 
-\family typewriter
-HXformat_free
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HXformat_add
-\family default
- is used to add substitution entries.
- One can also specify other types such as numeral types.
- 
-\family typewriter
-ptr_type
-\family default
- describes the type behind 
-\family typewriter
-ptr
-\family default
- and are constants from 
-\family typewriter
-option.h
-\family default
- (cf.
-\begin_inset space \space{}
-\end_inset
-
-section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "subsec:option-types"
-
-\end_inset
-
-)
-\begin_inset space ~
-\end_inset
-
-— not all constants can be used, though, and their meaning also differs
- from what 
-\family typewriter
-HX_getopt
-\family default
- or 
-\family typewriter
-HX_shconfig
-\family default
- use them for
-\begin_inset space ~
-\end_inset
-
-— the two could be seen as 
-\begin_inset Quotes eld
-\end_inset
-
-read
-\begin_inset Quotes erd
-\end_inset
-
- operations, while HXformat is a write operation.
-\end_layout
-
-\begin_layout Subsubsection
-Immediate types
-\end_layout
-
-\begin_layout Standard
-\begin_inset Quotes eld
-\end_inset
-
-Immediate types
-\begin_inset Quotes erd
-\end_inset
-
- are resolved when 
-\family typewriter
-HXformat_add
-\family default
- is called, that is, they are copied and inserted into the tree, and are
- subsequently independent from any changes to variables in the program.
- Because the HXopt-originating type name, that is, 
-\family typewriter
-HXTYPE_*
-\family default
-, is also used for deferred types, the constant 
-\family typewriter
-HXFORMAT_IMMED
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXFORMAT_IMMED
-\end_layout
-
-\end_inset
-
-
-\family default
- needs to be specified on some types to denote an immediate value.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-HXTYPE_STRING
-\family default
-
-\begin_inset space ~
-\end_inset
-
-— 
-\family typewriter
-ptr
-\family default
- is a 
-\family typewriter
-const char *
-\family default
-.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-HXTYPE_
-\family default
-{
-\family typewriter
-U
-\family default
-,}{
-\family typewriter
-CHAR
-\family default
-,
-\family typewriter
-SHORT
-\family default
-,
-\family typewriter
-INT
-\family default
-,
-\family typewriter
-LONG
-\family default
-,
-\family typewriter
-LLONG
-\family default
-}
-\family typewriter
- | HXFORMAT_IMMED
-\family default
-
-\begin_inset space ~
-\end_inset
-
-— mapping to the standard types
-\end_layout
-
-\begin_layout Subsubsection
-Deferred types
-\end_layout
-
-\begin_layout Standard
-\begin_inset Quotes eld
-\end_inset
-
-Deferred types
-\begin_inset Quotes erd
-\end_inset
-
- are resolved on every invocation of a formatter function (
-\family typewriter
-HXformat_*printf
-\family default
-).
- The expansions may be changed by modifying the underlying variable pointed
- to, but the pointer must remain valid and its pointee not go out of scope.
- Figure
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:hxformat-immediate-deferred"
-
-\end_inset
-
- shows the difference in a code sample.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-HXTYPE_STRP
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_STRP
-\end_layout
-
-\end_inset
-
-
-\begin_inset space ~
-\end_inset
-
-— 
-\family typewriter
-ptr
-\family default
- is a 
-\family typewriter
-const char *const *
-\family default
-; the pointer resolution is deferred until the formatter is called with
- one of the 
-\family typewriter
-HXformat_*printf
-\family default
- functions.
- Deferred in the sense it is always resolved anew.
- 
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-HXTYPE_BOOL
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_BOOL
-\end_layout
-
-\end_inset
-
-
-\begin_inset space ~
-\end_inset
-
-— 
-\family typewriter
-ptr
-\family default
- is a 
-\family typewriter
-const int
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-HXTYPE_
-\family default
-{
-\family typewriter
-U
-\family default
-,}{
-\family typewriter
-CHAR
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_CHAR
-\end_layout
-
-\end_inset
-
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UCHAR
-\end_layout
-
-\end_inset
-
-,
-\family typewriter
-SHORT
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_SHORT
-\end_layout
-
-\end_inset
-
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_USHORT
-\end_layout
-
-\end_inset
-
-,
-\family typewriter
-INT
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_INT
-\end_layout
-
-\end_inset
-
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UINT
-\end_layout
-
-\end_inset
-
-,
-\family typewriter
-LONG
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_LONG
-\end_layout
-
-\end_inset
-
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_ULONG
-\end_layout
-
-\end_inset
-
-,
-\family typewriter
-LLONG
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_LLONG
-\end_layout
-
-\end_inset
-
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_ULLONG
-\end_layout
-
-\end_inset
-
-}
-\begin_inset space ~
-\end_inset
-
-— mapping to the standard types with one indirection (e.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
-\begin_inset space \space{}
-\end_inset
-
-
-\family typewriter
-int
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-)
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-HXTYPE_
-\family default
-{
-\family typewriter
-FLOAT
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_FLOAT
-\end_layout
-
-\end_inset
-
-,
-\family typewriter
-DOUBLE
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_DOUBLE
-\end_layout
-
-\end_inset
-
-}
-\begin_inset space ~
-\end_inset
-
-— mapping to the two floating-point types with one indirection (e.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
-\begin_inset space \space{}
-\end_inset
-
-
-\family typewriter
-double
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-)
-\end_layout
-
-\begin_layout Subsection
-Invoking the formatter
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-int
-\series default
- HXformat_aprintf(
-\series bold
-struct
-\series default
- HXformat_map 
-\series bold
-*
-\series default
-table, hxmc_t 
-\series bold
-**
-\series default
-dest, 
-\series bold
-const char *
-\series default
-template);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXformat_aprintf
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HXformat_sprintf(
-\series bold
-struct
-\series default
- HXformat_map 
-\series bold
-*
-\series default
-table, 
-\series bold
-char *
-\series default
-dest, 
-\series bold
-size_t
-\series default
- size, 
-\series bold
-const char *
-\series default
-template);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXformat_sprintf
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HXformat_fprintf(
-\series bold
-struct
-\series default
- HXformat_map 
-\series bold
-*
-\series default
-table, FILE 
-\series bold
-*
-\series default
-filp, 
-\series bold
-const char *
-\series default
-template);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXformat_fprintf
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXformat_aprintf
-\family default
- Substitute placeholders in 
-\family typewriter
-template
-\family default
- using the given table.
- This will produce a string in a HX memory container (
-\family typewriter
-hxmc_t
-\family default
-), and the pointer is put into 
-\family typewriter
-*dest
-\family default
-.
- The caller will be responsible for freeing it later when it is done using
- the result.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXformat_sprintf
-\family default
- Do substitution and store the expanded result in the buffer 
-\family typewriter
-dest
-\family default
- which is of size 
-\family typewriter
-size
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXformat_fprintf
-\family default
- Do substituion and directly output the expansion to the given stdio stream.
-\end_layout
-
-\begin_layout Standard
-On success, the length of the expanded string is returned, excluding the
- trailing 
-\family typewriter
-'
-\backslash
-0'
-\family default
-.
- While 
-\family typewriter
-HXformat_sprintf
-\family default
- will not write more than 
-\family typewriter
-size
-\family default
- bytes (including the 
-\family typewriter
-'
-\backslash
-0'
-\family default
-), the length it would have taken is returned, similar to what 
-\family typewriter
-sprintf
-\family default
- does.
- On error, negative errno is returned.
-\end_layout
-
-\begin_layout Standard
-The HXformat function family recognizes make-style like functions and recursive
- expansion, described below.
-\end_layout
-
-\begin_layout Subsection
-Functions
-\end_layout
-
-\begin_layout Standard
-To expand a variable, one uses a syntax like 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-%(NAME)
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- in the format string.
- Recursive expansion like 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-%(%(USER))
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- is supported; assuming 
-\family typewriter
-%(USER)
-\family default
- would expand to 
-\begin_inset Quotes eld
-\end_inset
-
-linux
-\begin_inset Quotes erd
-\end_inset
-
-, HXformat would try to resolve 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-%(linux)
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- next.
- Besides these variable substitutions, HXformat also provides function calls
- whose syntax is 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-%(nameOfFunction parameters[...])
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-.
- Parameters can be any text, including variables.
- Paramters are separated from another by a delimiter specific to each function.
- See this list for details:
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-%(env
-\family default
- 
-\shape italic
-variable
-\family typewriter
-\shape default
-)
-\begin_inset Newline newline
-\end_inset
-
-
-\family default
-The 
-\family typewriter
-env
-\family default
- function expands to the string that is stored in the environmental variable
- by the given name.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-%(exec 
-\family default
-\shape italic
-command
-\family typewriter
-\shape default
- 
-\family default
-[
-\shape italic
-args
-\shape default
-...]
-\family typewriter
-)
-\family default
-
-\begin_inset Newline newline
-\end_inset
-
-The 
-\family typewriter
-exec
-\family default
- function expands to the standard output of the command.
- The command is directly run without shell invocation, so no special character
- expansion (wildcards, etc.) takes place.
- stdin is set to 
-\family typewriter
-/dev\SpecialChar breakableslash
-null
-\family default
-.
- The parameter delimiter is the space character.
- To be able to use this function
-\begin_inset space ~
-\end_inset
-
-— as it is relevant to security
-\begin_inset space ~
-\end_inset
-
-— the fmt table needs to have a key called 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-/libhx/exec
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-.
- See example
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "fig:hxformat-exec"
-
-\end_inset
-
- for details.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-%(if 
-\family default
-\shape italic
-condition
-\family typewriter
-\shape default
-,
-\family default
-[
-\shape italic
-then
-\shape default
-][
-\family typewriter
-,
-\family default
-[
-\shape italic
-else
-\shape default
-]]
-\family typewriter
-)
-\family default
-
-\begin_inset Newline newline
-\end_inset
-
-If the condition parameter expands to a string of non-zero length, the function
- expands to the 
-\begin_inset Quotes eld
-\end_inset
-
-then
-\begin_inset Quotes erd
-\end_inset
-
- block, otherwise the 
-\begin_inset Quotes eld
-\end_inset
-
-else
-\begin_inset Quotes erd
-\end_inset
-
- block.
- The delimiter used is a comma.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-%(lower 
-\family default
-\shape italic
-text
-\family typewriter
-\shape default
-)
-\family default
-, 
-\family typewriter
-%(upper 
-\family default
-\shape italic
-text
-\family typewriter
-\shape default
-)
-\family default
-
-\begin_inset Newline newline
-\end_inset
-
-Lowercases or uppercases the supplied argument.
- As these functions are meant to take only one argument, there is no delimiter
- defined that would need escaping if multiple arguments were supposed to
- be passed.
- 
-\family typewriter
-%(lower a,b)
-\family default
- is equivalent to 
-\family typewriter
-%(lower "a,b")
-\family default
-.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-%(shell 
-\family default
-\shape italic
-command
-\family typewriter
-\shape default
- 
-\family default
-[
-\shape italic
-args
-\shape default
-...]
-\family typewriter
-)
-\family default
-
-\begin_inset Newline newline
-\end_inset
-
-Similar to 
-\family typewriter
-%(exec)
-\family default
-, but invokes the shell inbetween (i.
-\begin_inset space \thinspace{}
-\end_inset
-
-e.
-\begin_inset space \space{}
-\end_inset
-
-`
-\family typewriter
-sh -c '
-\family default
-\shape italic
-command
-\shape default
-...
-\family typewriter
-'
-\family default
-`) such that special characters, redirection, and so on can be used.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-%(substr 
-\family default
-\shape italic
-text
-\family typewriter
-\shape default
-,
-\family default
-\shape italic
-offset
-\shape default
-[
-\family typewriter
-,
-\family default
-\shape italic
-length
-\shape default
-]
-\family typewriter
-)
-\family default
-
-\begin_inset Newline newline
-\end_inset
-
-Extracts a substring out of the given text, starting at 
-\shape italic
-offset
-\shape default
- and running for the given length.
- If no length is given, will extract until the end of the string.
- If 
-\shape italic
-offset
-\shape default
- is negative, it specifies the offset from the end of the string.
- If 
-\shape italic
-length
-\shape default
- is negative, that many characters are left off the end.
-\end_layout
-
-\begin_layout Itemize
-
-\family typewriter
-%(snl 
-\family default
-\shape italic
-text
-\family typewriter
-\shape default
-)
-\family default
-
-\begin_inset Newline newline
-\end_inset
-
-Strips trailing newlines from text and replaces any other newline by a space.
- What happens implicity in Makefiles' 
-\family typewriter
-$(shell 
-\family default
-...
-\family typewriter
-)
-\family default
- statements usually is explicitly separate in libHX.
-\end_layout
-
-\begin_layout Subsection
-Examples
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout LyX-Code
-
-\series bold
-const char *
-\series default
-b = "Hello World";
-\begin_inset Newline newline
-\end_inset
-
-
-\family typewriter
-\series bold
-char
-\series default
- c
-\family default
-\series bold
-[]
-\family typewriter
-\series default
- = "Hello World";
-\family default
-
-\begin_inset Newline newline
-\end_inset
-
-
-\family typewriter
-\series bold
-struct
-\series default
- HXformat_map 
-\series bold
-*
-\series default
-table = HXformat_init();
-\begin_inset Newline newline
-\end_inset
-
-HXformat_add(table, "%(GREETING1)", b, HXTYPE_STRING);
-\begin_inset Newline newline
-\end_inset
-
-HXformat_add(table, "%(GREETING2)", &c, HXTYPE_STRP);
-\begin_inset Newline newline
-\end_inset
-
-b = NULL;
-\begin_inset Newline newline
-\end_inset
-
-snprintf(c, 
-\family default
-\series bold
-sizeof
-\family typewriter
-\series default
-(c), "Hello Home");
-\begin_inset Newline newline
-\end_inset
-
-HXformat_aprintf(...);
-\end_layout
-
-\begin_layout Plain Layout
-Upon calling 
-\family typewriter
-HXformat_*printf
-\family default
-, 
-\family typewriter
-%(GREETING1)
-\family default
- will expand to 
-\begin_inset Quotes eld
-\end_inset
-
-Hello World
-\begin_inset Quotes erd
-\end_inset
-
- whereas 
-\family typewriter
-%(GREETING2)
-\family default
- will expand to 
-\begin_inset Quotes eld
-\end_inset
-
-Hello Home
-\begin_inset Quotes erd
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption Standard
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:hxformat-immediate-deferred"
-
-\end_inset
-
-Immediate and deferred resolution
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Float figure
-wide false
-sideways false
-status open
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- HXformat_map 
-\series bold
-*
-\series default
-table = HXformat_init();
-\begin_inset Newline newline
-\end_inset
-
-HXformat_add(table, "/libhx/exec", NULL, HXTYPE_IMMED);
-\begin_inset Newline newline
-\end_inset
-
-HXformat_aprintf(table, &result, "%(exec uname -s)");
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption Standard
-
-\begin_layout Plain Layout
-\begin_inset CommandInset label
-LatexCommand label
-name "fig:hxformat-exec"
-
-\end_inset
-
-Using the 
-\family typewriter
-%(exec)
-\family default
- function
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Part
-Filesystem operations
-\end_layout
-
-\begin_layout Section
-Dentry operations
-\end_layout
-
-\begin_layout Subsection
-Synopsis
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include <libHX/io.h>
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_readlink(hxmc_t 
-\series bold
-**
-\series default
-buf, 
-\series bold
-const char *
-\series default
-path);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_readlink
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_realpath(hxmc_t 
-\series bold
-**
-\series default
-buf, 
-\series bold
-const char *
-\series default
-path, 
-\series bold
-unsigned int
-\series default
- flags);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_realpath
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HX_readlink
-\family default
- calls through to 
-\family typewriter
-readlink
-\family default
- to read the target of a symbolic link, and stores the result in the memory
- container referenced by 
-\family typewriter
-*buf
-\family default
- (similar to 
-\family typewriter
-HX_getl
-\family default
- semantics).
- If 
-\family typewriter
-*buf
-\family default
- is 
-\family typewriter
-NULL
-\family default
-, a new container will be allocated and a pointer to it stored in 
-\family typewriter
-*buf
-\family default
-.
- The container's content is naturally zero-terminated automatically.
- The return value of the function will be the length of the link target,
- or negative to indicate the system error value.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HX_realpath
-\family default
- will normalize the given path by transforming various path components into
- alternate descriptions.
- The 
-\family typewriter
-flags
-\family default
- parameter controls its actions:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_REALPATH_DEFAULT
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_REALPATH_DEFAULT
-\end_layout
-
-\end_inset
-
- A mnemonic for a set of standard flags: 
-\family typewriter
-HX_\SpecialChar softhyphen
-REALPATH_\SpecialChar softhyphen
-SELF
-\begin_inset space ~
-\end_inset
-
-| HX_\SpecialChar softhyphen
-REALPATH_\SpecialChar softhyphen
-PARENT
-\family default
-.
- Note that 
-\family typewriter
-HX_\SpecialChar softhyphen
-REALPATH_\SpecialChar softhyphen
-ABSOLUTE
-\family default
-, which would also be required to get libc's 
-\family typewriter
-realpath
-\family default
-(3) behavior, is not included in the set.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_REALPATH_ABSOLUTE
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_REALPATH_ABSOLUTE
-\end_layout
-
-\end_inset
-
- Requests that the output path shall be absolute.
- In the absence of this flag, an absolute output path will only be produced
- if the input path is also absolute.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_REALPATH_SELF
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_REALPATH_SELF
-\end_layout
-
-\end_inset
-
- Request resolution of 
-\begin_inset Quotes eld
-\end_inset
-
-.
-\begin_inset Quotes erd
-\end_inset
-
- path components.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_REALPATH_PARENT
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_REALPATH_PARENT
-\end_layout
-
-\end_inset
-
- Request resolution of 
-\begin_inset Quotes eld
-\end_inset
-
-..
-\begin_inset Quotes erd
-\end_inset
-
- path components.
-\end_layout
-
-\begin_layout Standard
-The result is stored in a memory container whose pointer is returned through
- 
-\family typewriter
-*buf
-\family default
-.
- The return value of the function will be negative to indicate a possible
- system error, or be positive non-zero for success.
-\end_layout
-
-\begin_layout Section
-Directory traversal
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:dir-ops1"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-libHX provides a minimal readdir-style wrapper for cross-platform directory
- traversal.
- This is needed because the Win32 platforms does not have readdir, and there
- is some housekeeping to do on Unixish platforms, since the 
-\family typewriter
-dirent
-\family default
- structure needs allocation of a path-specific size.
-\end_layout
-
-\begin_layout Subsection
-Synopsis
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/io.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/io.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXdir 
-\series bold
-*
-\series default
-HXdir_open(
-\series bold
-const char *
-\series default
-directory);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXdir_open
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-const char *
-\series default
-HXdir_read(
-\series bold
-struct
-\series default
- HXdir 
-\series bold
-*
-\series default
-handle);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXdir_read
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-void
-\series default
- HXdir_close(
-\series bold
-struct
-\series default
- HXdir 
-\series bold
-*
-\series default
-handle);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXdir_close
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HXdir_open
-\family default
- returns a pointer to its private data area, or 
-\family typewriter
-NULL
-\family default
- upon failure, in which case 
-\family typewriter
-errno
-\family default
- is preserved from the underlying system calls.
- 
-\family typewriter
-HXdir_read
-\family default
- causes the next entry from the directory to be fetched.
- The pointer returned by 
-\family typewriter
-HXdir_read
-\family default
- must not be freed, and the data is overwritten in subsequent calls to the
- same handle.
- If you want to keep it around, you will have to duplicate it yourself.
- 
-\family typewriter
-HXdir_close
-\family default
- will close the directory and free the private data it held.
-\end_layout
-
-\begin_layout Subsection
-Example
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <errno.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <stdio.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <libHX/io.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXdir 
-\series bold
-*
-\series default
-dh;
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-if
-\series default
- ((dh = HXdir_open(".")) == NULL) {
-\begin_inset Newline newline
-\end_inset
-
-        fprintf(stderr, "Could not open directory: %s
-\backslash
-n", strerror(errno));
-\begin_inset Newline newline
-\end_inset
-
-        return;
-\begin_inset Newline newline
-\end_inset
-
-}
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-while
-\series default
- ((dentry = HXdir_read(dh)) != NULL)
-\begin_inset Newline newline
-\end_inset
-
-        printf("%s
-\backslash
-n", dentry);
-\begin_inset Newline newline
-\end_inset
-
-HXdir_close(dh);
-\end_layout
-
-\begin_layout Standard
-This sample will open the current directory, and print out all entries as
- it iterates over them.
-\end_layout
-
-\begin_layout Section
-Directory operations
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:dir-ops2"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Synopsis
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/io.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/io.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_mkdir(
-\series bold
-const char *
-\series default
-path, 
-\series bold
-unsigned int
-\series default
- mode);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-HX_mkdir
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_rrmdir(
-\series bold
-const char *
-\series default
-path);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_rrmdir
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HX_mkdir
-\family default
- will create the directory given by 
-\family typewriter
-path
-\family default
- and all its parents that do not exist yet using the given 
-\family typewriter
-mode
-\family default
-.
- It is equivalent to the `
-\family typewriter
-mkdir -p
-\family default
-` shell command.
- It will return >0 for success, or 
-\family typewriter
--errno
-\family default
- on error.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HX_rrmdir
-\family default
- also maps to an operation commonly done on the shell, `
-\family typewriter
-rm -Rf
-\family default
-`, deleting the directory given by 
-\family typewriter
-path
-\family default
-, including all files within it and its subdirectories.
- Errors during deletion are ignored, but if there was any, the errno value
- of the first one is returned negated.
-\end_layout
-
-\begin_layout Section
-File operations
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:file-ops"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Synopsis
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/io.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/io.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_copy_file(
-\series bold
-const char *
-\series default
-src, 
-\series bold
-const char *
-\series default
-dest, 
-\series bold
-unsigned int
-\series default
- flags, ...);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_copy_file
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_copy_dir(
-\series bold
-const char *
-\series default
-src, 
-\series bold
-const char *
-\series default
-dest, 
-\series bold
-unsigned int
-\series default
- flags, ...);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_copy_dir
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Possible flags that can be used with the functions:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXF_KEEP
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXF_KEEP
-\end_layout
-
-\end_inset
-
- Do not overwrite existing files.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXF_UID
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXF_UID
-\end_layout
-
-\end_inset
-
- Change the new file's owner to the UID given in the varargs section (
-\family typewriter
-...
-\family default
-).
- 
-\family typewriter
-HXF_UID
-\family default
- is processed before 
-\family typewriter
-HXF_GID
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXF_GID
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXF_GID
-\end_layout
-
-\end_inset
-
- Change the new file's group owner to the GID given in the varargs section.
- This is processed after 
-\family typewriter
-HXF_UID
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-Error checking is flakey.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HX_copy_file
-\family default
- will return >0 on success, or 
-\family typewriter
--errno
-\family default
- on failure.
- Errors can arise from the use of the syscalls 
-\family typewriter
-open
-\family default
-, 
-\family typewriter
-read
-\family default
- and 
-\family typewriter
-write
-\family default
-.
- The return value of 
-\family typewriter
-fchmod
-\family default
-, which is used to set the UID and GID, is actually ignored, which means
- verifying that the owner has been set cannot be detected with 
-\family typewriter
-HX_copy_file
-\family default
- alone (historic negligience?).
-\end_layout
-
-\begin_layout Subsection
-Filedescriptor I/O
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/io.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/io.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-ssize_t
-\series default
- HXio_fullread(
-\series bold
-int
-\series default
- fd, 
-\series bold
-void *
-\series default
-buf, 
-\series bold
-size_t
-\series default
- size, 
-\series bold
-unsigned int
-\series default
- flags);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXio_fullread
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-ssize_t
-\series default
- HXio_fullwrite(
-\series bold
-int
-\series default
- fd, 
-\series bold
-const void *
-\series default
-buf, 
-\series bold
-size_t
-\series default
- size, 
-\series bold
-unsigned int
-\series default
- flags);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXio_fullwrite
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Since plain 
-\family typewriter
-read
-\family default
-(2) and 
-\family typewriter
-write
-\family default
-(2) may process only part of the buffer
-\begin_inset space ~
-\end_inset
-
-— even more likely so with sockets
-\begin_inset space ~
-\end_inset
-
-—, libHX provides two functions that calls these in a loop to retry said
- operations until the full amount has been processed.
- Since 
-\family typewriter
-read
-\family default
- and 
-\family typewriter
-write
-\family default
- can also be used with socket file descriptors, so can these.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Part
-Options and Configuration Files
-\end_layout
-
-\begin_layout Section
-Option parsing
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:option"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-libHX uses a table-based approach like libpopt
-\begin_inset Foot
-status open
-
-\begin_layout Plain Layout
-The alternative would be an iterative, open-coded approach like 
-\family typewriter
-getopt
-\family default
-(3) requires.
-\end_layout
-
-\end_inset
-
-.
- It provides for both long and short options and the different styles associated
- with them, such as absence or presence of an equals sign for long options
- (
-\family typewriter
---foo=bar
-\family default
- and 
-\family typewriter
---foo bar
-\family default
-), bundling (writing 
-\family typewriter
--abc
-\family default
- for non-argument taking options 
-\family typewriter
--a -b -c
-\family default
-), squashing (writing 
-\family typewriter
--fbar
-\family default
- for an argument-requiring option 
-\family typewriter
--f
-\begin_inset space ~
-\end_inset
-
-bar
-\family default
-).
- The 
-\begin_inset Quotes eld
-\end_inset
-
-lone dash
-\begin_inset Quotes erd
-\end_inset
-
- that is often used to indicate standard input or standard output, is correctly
- handled
-\begin_inset Foot
-status open
-
-\begin_layout Plain Layout
-popt failed to do this for a long time.
-\end_layout
-
-\end_inset
-
-, as in 
-\family typewriter
--f
-\begin_inset space ~
-\end_inset
-
--
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-A table-based approach allows for the parser to run as one atomic block
- of code (callbacks are, by definition, 
-\begin_inset Quotes eld
-\end_inset
-
-special
-\begin_inset Quotes erd
-\end_inset
-
- exceptions), making it more opaque than an open-coded 
-\family typewriter
-getopt
-\family default
-(3) loop.
- You give it your argument vector and the table, snip the finger (call the
- parser function once), and it is done.
- In getopt on the other hand, the 
-\family typewriter
-getopt
-\family default
- function returns for every argument it parsed and needs to be called repeatedly.
-\end_layout
-
-\begin_layout Subsection
-Synopsis
-\begin_inset CommandInset label
-LatexCommand label
-name "subsec:option-synopsis"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/option.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/option.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXoption {
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-struct HXoption
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-const char
-\series default
- *ln;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-char
-\series default
- sh;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-unsigned int
-\series default
- type;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-void *
-\series default
-ptr, 
-\series bold
-*
-\series default
-uptr;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-void (*
-\series default
-cb
-\series bold
-)
-\series default
-(
-\series bold
-const struct
-\series default
- HXoptcb 
-\series bold
-*
-\series default
-);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-int
-\series default
- val;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-const char *
-\series default
-help, 
-\series bold
-*
-\series default
-htyp;
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_getopt(
-\series bold
-const struct
-\series default
- HXoption 
-\series bold
-*
-\series default
-options_table, 
-\series bold
-int *
-\series default
-argc,
-\begin_inset Newline newline
-\end_inset
-
-              
-\series bold
-const char ***
-\series default
-argv, 
-\series bold
-unsigned int
-\series default
- flags);
-\end_layout
-
-\begin_layout Standard
-The various fields of 
-\family typewriter
-struct HXoption
-\family default
- are:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-ln
-\family default
- The long option name, if any.
- May be 
-\family typewriter
-NULL
-\family default
- if none is to be assigned for this entry.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-sh
-\family default
- The short option name/character, if any.
- May be 
-\family typewriter
-'
-\backslash
-0'
-\family default
- if none is to be assigned for this entry.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-type
-\family default
- The type of the entry, essentially denoting the type of the target variable.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-val
-\family default
- An integer value to be stored into 
-\family typewriter
-*(int
-\begin_inset space ~
-\end_inset
-
-*)ptr
-\family default
- when 
-\family typewriter
-HXTYPE_IVAL
-\family default
- is used.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-ptr
-\family default
- A pointer to the variable so that the option parser can store the requested
- data in it.
- The pointer may be 
-\family typewriter
-NULL
-\family default
- in which case no data is stored (but 
-\family typewriter
-cb
-\family default
- is still called if defined, with the data).
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-uptr
-\family default
- A user-supplied pointer.
- Its value is passed verbatim to the callback, and may be used for any purpose
- the user wishes.
- If 
-\family typewriter
-type
-\family default
- is 
-\family typewriter
-HXTYPE_SVAL
-\family default
-, it is the value in 
-\family typewriter
-uptr
-\family default
- that will be used to populate 
-\family typewriter
-*(const char
-\begin_inset space ~
-\end_inset
-
-**)ptr
-\family default
-.
- (The original 
-\family typewriter
-.sval
-\family default
- field has been removed in libHX 3.12.)
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-cb
-\family default
- If not 
-\family typewriter
-NULL
-\family default
-, call out to the referenced function after the option has been parsed (and
- the results possibly be stored in 
-\family typewriter
-ptr
-\family default
-)
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-help
-\family default
- A help string that is shown for the option when the option table is dumped
- by request (e.
-\begin_inset space \thinspace{}
-\end_inset
-
-g.
-\begin_inset space \space{}
-\end_inset
-
-
-\family typewriter
-yourprgram --help
-\family default
-)
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-htyp
-\family default
- String containing a keyword to aid the user in understanding the available
- options during dump.
- See examples.
-\end_layout
-
-\begin_layout Standard
-Due to the amount of fields, it is advised to use C99 named initializers
- to populate a struct, as they allow to omit unspecified fields, and assume
- no specific order of the members:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- HXoption e = {.sh = 'f', .help = "Force"};
-\end_layout
-
-\begin_layout Standard
-It is a sad fact that C++ has not gotten around to implement these yet.
- It is advised to put the option parsing code into a separate 
-\family typewriter
-.c
-\family default
- file that can then be compiled in C99 rather than C++ mode.
-\end_layout
-
-\begin_layout Subsection
-Type map
-\begin_inset CommandInset label
-LatexCommand label
-name "subsec:option-types"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXTYPE_NONE
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXTYPE_NONE
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- The option does not take any argument, but the presence of the option may
- be record by setting the 
-\family typewriter
-*(int
-\begin_inset space ~
-\end_inset
-
-*)ptr
-\family default
- to 1.
- Other rules apply when 
-\family typewriter
-HXOPT_\SpecialChar softhyphen
-INC
-\family default
- or 
-\family typewriter
-HXOPT_\SpecialChar softhyphen
-DEC
-\family default
- are specified as flags (see section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "subsec:option-flags"
-
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXTYPE_VAL
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXTYPE_VAL
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Use the integer value specified by 
-\family typewriter
-ival
-\family default
- and store it in 
-\family typewriter
-*(int
-\begin_inset space ~
-\end_inset
-
-*)ptr
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXTYPE_SVAL
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXTYPE_SVAL
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Use the memory location specified by 
-\family typewriter
-sval
-\family default
- and store it in 
-\family typewriter
-*(const char
-\begin_inset space ~
-\end_inset
-
-**)ptr
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXTYPE_BOOL
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXTYPE_BOOL
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Interpret the supplied argument as a boolean descriptive (must be 
-\begin_inset Quotes eld
-\end_inset
-
-yes
-\begin_inset Quotes erd
-\end_inset
-
-, 
-\begin_inset Quotes eld
-\end_inset
-
-no
-\begin_inset Quotes erd
-\end_inset
-
-, 
-\begin_inset Quotes eld
-\end_inset
-
-on
-\begin_inset Quotes erd
-\end_inset
-
-, 
-\begin_inset Quotes eld
-\end_inset
-
-off
-\begin_inset Quotes erd
-\end_inset
-
-, 
-\begin_inset Quotes eld
-\end_inset
-
-true
-\begin_inset Quotes erd
-\end_inset
-
-, 
-\begin_inset Quotes eld
-\end_inset
-
-false
-\begin_inset Quotes erd
-\end_inset
-
-, 
-\begin_inset Quotes eld
-\end_inset
-
-0
-\begin_inset Quotes erd
-\end_inset
-
- or 
-\begin_inset Quotes eld
-\end_inset
-
-1
-\begin_inset Quotes erd
-\end_inset
-
-) and store the result in 
-\family typewriter
-*(int
-\begin_inset space ~
-\end_inset
-
-*)ptr
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXTYPE_STRING
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_STRING
-\end_layout
-
-\end_inset
-
-
-\family default
- The argument string is duplicated to a new memory region and the resulting
- pointer stored into 
-\family typewriter
-*(char
-\begin_inset space ~
-\end_inset
-
-**)ptr
-\family default
-.
- This incurs an allocation so that subsequently modifying the original argument
- string in any way will not falsely propagate.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXTYPE_STRDQ
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXTYPE_STRDQ
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- The argument string is duplicated to a new memory region and the resulting
- pointer is added to the given HXdeque.
- Note that you often need to use deferred initialization of the options
- table to avoid putting 
-\family typewriter
-NULL
-\family default
- into the entry.
- See section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "subsec:option-pitfalls-static"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-The following table lists the types that map to the common integral and
- floating-point types.
- Signed and unsigned integeral types are processed using 
-\family typewriter
-strtol
-\family default
- and 
-\family typewriter
-strtoul
-\family default
-, respectively.
- 
-\family typewriter
-strtol
-\family default
- and 
-\family typewriter
-strtoul
-\family default
- will be called with automatic base detection.
- This usually means that a leading 
-\begin_inset Quotes eld
-\end_inset
-
-0
-\begin_inset Quotes erd
-\end_inset
-
- indicates the string is given in octal (8) base, a leading 
-\begin_inset Quotes eld
-\end_inset
-
-0x
-\begin_inset Quotes erd
-\end_inset
-
- indicates hexadecimal (16) base, and decimal (10) otherwise.
- 
-\family typewriter
-HXTYPE_\SpecialChar softhyphen
-LLONG
-\family default
-,
-\family typewriter
- HXTYPE_\SpecialChar softhyphen
-ULLONG
-\family default
-,
-\family typewriter
- HXTYPE_\SpecialChar softhyphen
-INT64
-\family default
- and
-\family typewriter
- HXTYPE_\SpecialChar softhyphen
-UINT64
-\family default
- use
-\family typewriter
- strtoll
-\family default
- and/or
-\family typewriter
- strtoull
-\family default
-, which may not be available on all platforms.
-\begin_inset Separator latexpar
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-\align center
-\begin_inset Float table
-placement H
-wide false
-sideways false
-status open
-
-\begin_layout Plain Layout
-\align center
-\begin_inset Tabular
-<lyxtabular version="3" rows="12" columns="4">
-<features tabularvalignment="middle">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="bottom">
-<column alignment="center" valignment="top">
-<column alignment="center" valignment="top">
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series bold
-type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Type of pointee
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-type
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\series bold
-Type of pointee
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_CHAR
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_CHAR
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-char
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_INT8
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_INT8
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-int8_t
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UCHAR
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UCHAR
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-unsigned char
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UINT8
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UINT8
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-uint8_t
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_SHORT
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_SHORT
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-short
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_INT16
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_INT16
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-int16_t
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_USHORT
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_USHORT
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-unsigned short
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UINT16
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UINT16
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-uint16_t
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_INT
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_INT
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-int
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_INT32
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_INT32
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-int32_t
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UINT
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UINT
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-unsigned int
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UINT32
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UINT32
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-uint32_t
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_LONG
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_LONG
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-long
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_INT64
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_INT64
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-int64_t
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_ULONG
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_ULONG
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-unsigned long
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UINT64
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_UINT64
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-uint64_t
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_LLONG
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_LLONG
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-long long
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_FLOAT
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_FLOAT
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-float
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_ULLONG
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_ULLONG
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-unsigned long long
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_DOUBLE
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_DOUBLE
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-double
-\end_layout
-
-\end_inset
-</cell>
-</row>
-<row>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_SIZE_T
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXTYPE_SIZE_T
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\family typewriter
-size_t
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Plain Layout
-\begin_inset Caption Standard
-
-\begin_layout Plain Layout
-Integral and floating-point types for the libHX option parser
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HXTYPE_\SpecialChar softhyphen
-FLOAT
-\family default
- and 
-\family typewriter
-HXTYPE_\SpecialChar softhyphen
-DOUBLE
-\family default
- make use of 
-\family typewriter
-strtod
-\family default
- (
-\family typewriter
-strtof
-\family default
- is not used).
- A corresponding 
-\family typewriter
-type
-\family default
- for the 
-\begin_inset Quotes eld
-\end_inset
-
-long double
-\begin_inset Quotes erd
-\end_inset
-
- format is not specified, but may be implemented on behalf of the user via
- a callback (see section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "subsec:option-example-cb"
-
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Subsection
-Flags
-\begin_inset CommandInset label
-LatexCommand label
-name "subsec:option-flags"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Flags can be combined into the 
-\family typewriter
-type
-\family default
- parameter by OR'ing them.
- It is valid to not specify any flags at all, but most flags collide with
- one another.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_INC
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXOPT_INC
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Perform an increment on the memory location specified by the 
-\family typewriter
-*(int
-\begin_inset space ~
-\end_inset
-
-*)ptr
-\family default
- pointer.
- Make sure the referenced variable is initialized before!
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_DEC
-\family default
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXOPT_DEC
-\end_layout
-
-\end_inset
-
-
-\series default
- Perform a decrement on the pointee.
-\end_layout
-
-\begin_layout Standard
-Only one of 
-\family typewriter
-HXOPT_\SpecialChar softhyphen
-INC
-\family default
- and 
-\family typewriter
-HXOPT_\SpecialChar softhyphen
-DEC
-\family default
- may be specified at a time, and they require that the base type is 
-\family typewriter
-HXTYPE_\SpecialChar softhyphen
-NONE
-\family default
-, or they will have no effect.
- An example may be found in section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "subsec:option-example-incdec"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_NOT
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXOPT_NOT
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Binary negation of the argument directly after reading it from the command
- line into memory.
- Any of the three following operations are executed with the already-negated
- value.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_OR
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXOPT_OR
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Binary 
-\begin_inset Quotes eld
-\end_inset
-
-OR
-\begin_inset Quotes erd
-\end_inset
-
-s the pointee with the specified\SpecialChar breakableslash
-transformed value.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_AND
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXOPT_AND
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Binary 
-\begin_inset Quotes eld
-\end_inset
-
-AND
-\begin_inset Quotes erd
-\end_inset
-
-s the pointee with the specified\SpecialChar breakableslash
-transformed value.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_XOR
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXOPT_XOR
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Binary 
-\begin_inset Quotes eld
-\end_inset
-
-XOR
-\begin_inset Quotes erd
-\end_inset
-
-s the pointee with the specified\SpecialChar breakableslash
-transformed value.
-\end_layout
-
-\begin_layout Standard
-Only one of (
-\family typewriter
-HXOPT_OR
-\family default
-, 
-\family typewriter
-HXOPT_\SpecialChar softhyphen
-AND
-\family default
-, 
-\family typewriter
-HXOPT_\SpecialChar softhyphen
-XOR
-\family default
-) may be specified at a time, but they can be used with any integral 
-\family typewriter
-type
-\family default
- (
-\family typewriter
-HXTYPE_\SpecialChar softhyphen
-UINT
-\family default
-, 
-\family typewriter
-HXTYPE_\SpecialChar softhyphen
-ULONG
-\family default
-, etc.).
- An example can be found in section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "subsec:option-example-mask"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_OPTIONAL
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXOPT_OPTIONAL
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- This flag allows for an option to take zero or one argument.
- Needless to say that this can be confusing to the user.
- 
-\shape italic
-iptables
-\shape default
-'s 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--L
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- option for example is one of this kind (though it does not use the libHX
- option parser).
- When this flag is used, 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--f -b
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- is interpreted as 
-\family typewriter
--f
-\family default
- without an argument, as is 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--f --bar
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-
-\begin_inset space ~
-\end_inset
-
-— things that look like an option take precedence over an option with an
- optional argument.
- 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--f -
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- of course denotes an option with an argument, as 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- is used to indicate standard input/output.
-\end_layout
-
-\begin_layout Subsection
-Special entries
-\end_layout
-
-\begin_layout Standard
-HXopt provides two special entries via macros:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_AUTOHELP
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXOPT_AUTOHELP
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Adds entries to recognize 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--?
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- and 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
---help
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- that will display the (long-format) help screen, and 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
---usage
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- that will display the short option syntax overview.
- All three options will exit the program afterwards.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_TABLEEND
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXOPT_TABLEEND
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- This sentinel marks the end of the table and is required on all tables.
- (See examples for details.)
-\end_layout
-
-\begin_layout Subsection
-Invoking the parser
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-int
-\series default
- HX_getopt(
-\series bold
-const struct
-\series default
- HXoption 
-\series bold
-*
-\series default
-options_table, 
-\series bold
-int *
-\series default
-argc,
-\begin_inset Newline newline
-\end_inset
-
-              
-\series bold
-const char ***
-\series default
-argv, 
-\series bold
-unsigned int
-\series default
- flags);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_getopt
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HX_getopt
-\family default
- is the actual parsing function.
- It takes the option table, and a pointer to your 
-\family typewriter
-argc
-\family default
- and 
-\family typewriter
-argv
-\family default
- variables that you get from the 
-\family typewriter
-main
-\family default
- function.
- The parser will, unlike GNU getopt, literally 
-\begin_inset Quotes eld
-\end_inset
-
-eat
-\begin_inset Quotes erd
-\end_inset
-
- all options and their arguments, leaving only non-options in 
-\family typewriter
-argv
-\family default
-, and 
-\family typewriter
-argc
-\family default
- updated, when finished.
- This is similar to how Perl's 
-\begin_inset Quotes eld
-\end_inset
-
-Getopt::Long
-\begin_inset Quotes erd
-\end_inset
-
- module works.
- Additional flags can control the exact behavior of 
-\family typewriter
-HX_getopt
-\family default
-:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_PTHRU
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXOPT_PTHRU
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- 
-\begin_inset Quotes eld
-\end_inset
-
-Passthrough mode
-\begin_inset Quotes erd
-\end_inset
-
-.
- Any unknown options are not 
-\begin_inset Quotes eld
-\end_inset
-
-eaten
-\begin_inset Quotes erd
-\end_inset
-
- and are instead passed back into the resulting 
-\family typewriter
-argv
-\family default
- array.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_QUIET
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXOPT_QUIET
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Do not print any diagnostics when encountering errors in the user's input.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_HELPONERR
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXOPT_HELPONERR
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Display the (long-format) help when an error, such as an unknown option
- or a violation of syntax, is encountered.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_USAGEONERR
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXOPT_USAGEONERR
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Display the short-format usage syntax when an error is encountered.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_RQ_ORDER
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXOPT_RQ_ORDER
-\end_layout
-
-\end_inset
-
- Specifying this option terminates option processing when the first non-option
- argument in 
-\family typewriter
-argv
-\family default
- is encountered.
- This behavior is also implicit when the environment variable 
-\family typewriter
-POSIXLY_CORRECT
-\family default
- is set.
-\end_layout
-
-\begin_layout Standard
-The return value can be one of the following:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_ERR_SUCCESS
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXOPT_ERR_SUCCESS
-\end_layout
-
-\end_inset
-
- Parsing was successful.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_ERR_UNKN
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXOPT_ERR_UNKN
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- An unknown option was encountered.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_ERR_VOID
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXOPT_ERR_VOID
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- An argument was given for an option which does not allow one.
- In practice this only happens with 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
---foo=bar
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- when 
-\family typewriter
---foo
-\family default
- is of type 
-\family typewriter
-HXTYPE_\SpecialChar softhyphen
-NONE
-\family default
-, 
-\family typewriter
-HXTYPE_\SpecialChar softhyphen
-VAL
-\family default
- or 
-\family typewriter
-HXTYPE_\SpecialChar softhyphen
-SVAL
-\family default
-.
- This does not affect 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
---foo bar
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-, because this can be unambiguously interpreted as 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-bar
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- being a remaining argument to the program.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_ERR_MIS
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXOPT_ERR_MIS
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Missing argument for an option that requires one.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXOPT_ERR_AMBIG
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXOPT_ERR_AMBIG
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- An abbreviation of a long option was ambiguous.
-\end_layout
-
-\begin_layout Description
-negative
-\begin_inset space ~
-\end_inset
-
-non-zero Failure on behalf of lower-level calls; errno.
-\end_layout
-
-\begin_layout Subsection
-Pitfalls
-\end_layout
-
-\begin_layout Subsubsection
-Staticness of tables
-\begin_inset CommandInset label
-LatexCommand label
-name "subsec:option-pitfalls-static"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The following is an example of a possible pitfall regarding 
-\family typewriter
-HXTYPE_\SpecialChar softhyphen
-STRDQ
-\family default
-:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-static struct
-\series default
- HXdeque 
-\series bold
-*
-\series default
-dq;
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static bool
-\series default
- get_options(
-\series bold
-int *
-\series default
-argc, 
-\series bold
-const char ***
-\series default
-argv)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-static const struct
-\series default
- HXoption options_table
-\series bold
-[]
-\series default
- = {
-\begin_inset Newline newline
-\end_inset
-
-                {.sh = 'N', .type = HXTYPE_STRDQ, .q_strdq = dq,
-\begin_inset Newline newline
-\end_inset
-
-                 .help = "Add name"},
-\begin_inset Newline newline
-\end_inset
-
-                HXOPT_TABLEEND,
-\begin_inset Newline newline
-\end_inset
-
-        };
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-return
-\series default
- HX_getopt(options_table, argc, argv, HXOPT_USAGEONERR) ==
-\begin_inset Newline newline
-\end_inset
-
-               HXOPT_ERR_SUCCESS;
-\begin_inset Newline newline
-\end_inset
-
-}
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- main(
-\series bold
-int
-\series default
- argc, 
-\series bold
-const char **
-\series default
-argv)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        dq = HXdeque_init();
-\begin_inset Newline newline
-\end_inset
-
-        get_options(&argc, &argv);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-return
-\series default
- 0;
-\begin_inset Newline newline
-\end_inset
-
-}
-\end_layout
-
-\begin_layout Standard
-The problem here is that 
-\family typewriter
-options_\SpecialChar softhyphen
-table
-\family default
- is, due to the 
-\family typewriter
-static
-\family default
- keyword, initialized at compile-time where 
-\family typewriter
-dq
-\family default
- is still 
-\family typewriter
-NULL
-\family default
-.
- To counter this problem and have it doing the right thing, you must remove
- the 
-\family typewriter
-static
-\family default
- qualifier on the options table when used with 
-\family typewriter
-HXTYPE_\SpecialChar softhyphen
-STRDQ
-\family default
-, so that it will be evaluated when it is first executed.
-\end_layout
-
-\begin_layout Standard
-It was not deemed worthwhile to have 
-\family typewriter
-HXTYPE_\SpecialChar softhyphen
-STRDQ
-\family default
- take an indirect HXdeque (
-\family typewriter
-struct HXdeque
-\begin_inset space ~
-\end_inset
-
-**
-\family default
-) instead just to bypass this issue.
- (Live with it.)
-\end_layout
-
-\begin_layout Subsection
-Limitations
-\end_layout
-
-\begin_layout Standard
-The HX option parser has been influenced by both popt and Getopt::Long,
- but eventually, there are differences:
-\end_layout
-
-\begin_layout Itemize
-Long options with a single dash (
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--foo bar
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-).
- This unsupported syntax clashes very easily with support for option bundling
- or squashing.
- In case of bundling, 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--foo
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- might actually be 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--f -o -o
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-, or 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
--f oo
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- in case of squashing.
- It also introduces redundant ways to specify options, which is not in the
- spirit of the author.
-\end_layout
-
-\begin_layout Itemize
-Options using a 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-+
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- as a prefix, as in 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-+foo
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-.
- Xterm for example uses it as a way to negate an option.
- In the author's opinion, using one character to specify options is enough
-\begin_inset space ~
-\end_inset
-
-— by GNU standards, a negator is named 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
---no-foo
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-.
- Even Microsoft stuck to a single option introducing character (that would
- be 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-/
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-).
-\end_layout
-
-\begin_layout Itemize
-Table nesting like implemented in popt.
- HXopt has no provision for nested tables, as the need has not come up yet.
- It does however support chained processing (see section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "subsec:option-example-chained"
-
-\end_inset
-
-).
- You cannot do nested tables even with callbacks, as the new 
-\family typewriter
-argv
-\family default
- array is only put in place shortly before 
-\family typewriter
-HX_getopt
-\family default
- returns.
-\end_layout
-
-\begin_layout Subsection
-Examples
-\end_layout
-
-\begin_layout Subsubsection
-Basic example
-\end_layout
-
-\begin_layout Standard
-The following code snippet should provide an equivalent of the GNU getopt
- sample
-\begin_inset Foot
-status open
-
-\begin_layout Plain Layout
-\begin_inset Flex URL
-status open
-
-\begin_layout Plain Layout
-
-http://www.gnu.org/software/libtool/manual/libc/Example-of-Getopt.html
-\backslash
-#Example-of-Getopt
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <stdio.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <stdilb.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-#include
-\series default
- <libHX/option.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- main(
-\series bold
-int
-\series default
- argc, 
-\series bold
-const char **
-\series default
-argv)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-int
-\series default
- aflag = 0;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-int
-\series default
- bflag = 0;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-char *
-\series default
-cflag = NULL;
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- HXoption options_table
-\series bold
-[]
-\series default
- = {
-\begin_inset Newline newline
-\end_inset
-
-                {.sh = 'a', .type = HXTYPE_NONE, .ptr = &aflag},
-\begin_inset Newline newline
-\end_inset
-
-                {.sh = 'b', .type = HXTYPE_NONE, .ptr = &bflag},
-\begin_inset Newline newline
-\end_inset
-
-                {.sh = 'c', .type = HXTYPE_STRING, .ptr = &cflag},
-\begin_inset Newline newline
-\end_inset
-
-                HXOPT_AUTOHELP,
-\end_layout
-
-\begin_layout LyX-Code
-                HXOPT_TABLEEND,
-\begin_inset Newline newline
-\end_inset
-
-        };
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-if
-\series default
- (HX_getopt(options_table, &argc, &argv, HXOPT_USAGEONERR) !=
-\begin_inset Newline newline
-\end_inset
-
-            HXOPT_ERR_SUCCESS)
-\end_layout
-
-\begin_layout LyX-Code
-                
-\series bold
-return
-\series default
- EXIT_FAILURE;
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        printf("aflag = %d, bflag = %d, cvalue = %s
-\backslash
-n",
-\begin_inset Newline newline
-\end_inset
-
-               aflag, bflag, cvalue);
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-while
-\series default
- (*++argv != NULL)
-\begin_inset Newline newline
-\end_inset
-
-                printf("Non-option argument %s
-\backslash
-n", *argv);
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-return
-\series default
- EXIT_SUCCESS;
-\begin_inset Newline newline
-\end_inset
-
-}
-\end_layout
-
-\begin_layout Subsubsection
-Verbosity levels
-\begin_inset CommandInset label
-LatexCommand label
-name "subsec:option-example-incdec"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-static int
-\series default
- verbosity = 1; 
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-somewhat silent by default
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static const struct
-\series default
- HXoption options_table
-\series bold
-[]
-\series default
- = {
-\begin_inset Newline newline
-\end_inset
-
-        {.sh = 'q', .type = HXTYPE_NONE | HXOPT_DEC, .q_int = &verbosity,
-\begin_inset Newline newline
-\end_inset
-
-         .help = "Reduce verbosity"},
-\begin_inset Newline newline
-\end_inset
-
-        {.sh = 'v', .type = HXTYPE_NONE | HXOPT_INC, .q_int = &verbosity,
-\begin_inset Newline newline
-\end_inset
-
-         .help = "Increase verbosity"},
-\begin_inset Newline newline
-\end_inset
-
-        HXOPT_TABLEEND,
-\begin_inset Newline newline
-\end_inset
-
-};
-\end_layout
-
-\begin_layout Standard
-This sample option table makes it possible to turn the verbosity of the
- program up or down, depending on whether the user specified 
-\family typewriter
--q
-\family default
- or 
-\family typewriter
--v
-\family default
-.
- By passing multiple 
-\family typewriter
--v
-\family default
- flags, the verbosity can be turned up even more.
- The range depends on the 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-int
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- data type for your particular platform and compiler; if you want to have
- the verbosity capped at a specific level, you will need to use an extra
- callback:
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-static int
-\series default
- verbosity = 1;
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static void
-\series default
- v_check(
-\series bold
-const struct
-\series default
- HXoptcb 
-\series bold
-*
-\series default
-cbi)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-if
-\series default
- (verbosity < 0)
-\begin_inset Newline newline
-\end_inset
-
-                verbosity = 0;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-else if
-\series default
- (verbosity > 4)
-\begin_inset Newline newline
-\end_inset
-
-                verbosity = 4;
-\begin_inset Newline newline
-\end_inset
-
-}
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static const struct
-\series default
- HXoption options_table
-\series bold
-[]
-\series default
- = {
-\begin_inset Newline newline
-\end_inset
-
-        {.sh = 'q', .type = HXTYPE_NONE | HXOPT_DEC, .q_int = &verbosity,
-\begin_inset Newline newline
-\end_inset
-
-         .cb = v_check, .help = "Lower verbosity"},
-\begin_inset Newline newline
-\end_inset
-
-        {.sh = 'v', .type = HXTYPE_NONE | HXOPT_INC, .q_int = &verbosity,
-\begin_inset Newline newline
-\end_inset
-
-         .cb = v_check, .help = "Raise verbosity"},
-\begin_inset Newline newline
-\end_inset
-
-        HXOPT_TABLEEND,
-\begin_inset Newline newline
-\end_inset
-
-};
-\end_layout
-
-\begin_layout Subsubsection
-Mask operations
-\begin_inset CommandInset label
-LatexCommand label
-name "subsec:option-example-mask"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-run on all CPU cores by default
-\family default
-\series bold
-\shape default
- *
-\series default
-/
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static unsigned int
-\series default
- cpu_mask = ~0U
-\series bold
-;
-\begin_inset Newline newline
-\end_inset
-
-/* 
-\family roman
-\series default
-\shape italic
-use no network connections by default
-\family default
-\shape default
- 
-\series bold
-*/
-\begin_inset Newline newline
-\end_inset
-
-static unsigned int
-\series default
- net_mask = 0;
-\series bold
-
-\begin_inset Newline newline
-\end_inset
-
-static struct
-\series default
- HXoption options_table
-\series bold
-[]
-\series default
- = {
-\begin_inset Newline newline
-\end_inset
-
-        {.sh = 'c', .type = HXTYPE_UINT | HXOPT_NOT | HXOPT_AND,
-\begin_inset Newline newline
-\end_inset
-
-         .q_uint = &cpu_mask,
-\begin_inset Newline newline
-\end_inset
-
-         .help = "Mask of cores to exclude", .htyp = "cpu_mask"},
-\begin_inset Newline newline
-\end_inset
-
-        {.sh = 'n', .type = HXTYPE_UINT | HXOPT_OR, .q_uint = &net_mask,
-\end_layout
-
-\begin_layout LyX-Code
-         .help = "Mask of network channels to additionally use",
-\begin_inset Newline newline
-\end_inset
-
-         .htyp = "channel_mask"},
-\begin_inset Newline newline
-\end_inset
-
-        HXOPT_TABLEEND,
-\begin_inset Newline newline
-\end_inset
-
-};
-\end_layout
-
-\begin_layout Standard
-What this options table does is 
-\family typewriter
-cpu_mask &= ~x
-\family default
- and 
-\family typewriter
-net_mask |= y
-\family default
-, the classic operations of clearing and setting bits.
-\end_layout
-
-\begin_layout Subsubsection
-Support for non-standard actions
-\begin_inset CommandInset label
-LatexCommand label
-name "subsec:option-example-cb"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Supporting additional types or custom storage formats is easy, by simply
- using 
-\family typewriter
-HXTYPE_\SpecialChar softhyphen
-STRING
-\family default
-, 
-\family typewriter
-NULL
-\family default
- as the data pointer (usually by not specifying it at all), the pointer
- to your data in the user-specified pointer 
-\family typewriter
-uptr
-\family default
-, and the callback function in 
-\family typewriter
-cb
-\family default
-.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-struct
-\series default
- fixed_point {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-int
-\series default
- integral;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-unsigned int
-\series default
- fraction;
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static struct
-\series default
- fixed_point number;
-\end_layout
-
-\begin_layout LyX-Code
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static void
-\series default
- fixed_point_parse
-\series bold
-(const struct
-\series default
- HXoptcb
-\series bold
- 
-\series default
-*cbi)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-char *
-\series default
-end;
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        number.integral = strtol(cbi->data, &end, 0);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-if
-\series default
- (*end == '
-\backslash
-0')
-\begin_inset Newline newline
-\end_inset
-
-                number.fraction = 0;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-else if
-\series default
- (*end == '.')
-\begin_inset Newline newline
-\end_inset
-
-                number.fraction = strtoul(end + 1, NULL, 0);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-else
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-                fprintf(stderr, "Illegal input.
-\backslash
-n");
-\begin_inset Newline newline
-\end_inset
-
-}
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-
-\begin_inset Newline newline
-\end_inset
-
-static const struct
-\series default
- HXoption options_table
-\series bold
-[]
-\series default
- = {
-\begin_inset Newline newline
-\end_inset
-
-        {.sh = 'n', .type = HXTYPE_STRING, .cb = fixed_point_parse,
-\begin_inset Newline newline
-\end_inset
-
-         .uptr = &number, .help = "Do this or that",
-\begin_inset Newline newline
-\end_inset
-
-        HXOPT_TABLEEND,
-\end_layout
-
-\begin_layout LyX-Code
-};
-\end_layout
-
-\begin_layout Subsubsection
-Chained argument processing
-\begin_inset CommandInset label
-LatexCommand label
-name "subsec:option-example-chained"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-On the first run, only 
-\family typewriter
---cake
-\family default
- and 
-\family typewriter
---fruit
-\family default
- is considered, which is then used to select the next set of accepted options.
- Note that 
-\family typewriter
-HXOPT_\SpecialChar softhyphen
-DESTROY_\SpecialChar softhyphen
-OLD
-\family default
- is used here, which causes the argv that is produced by the first invocation
- of 
-\family typewriter
-HX_getopt
-\family default
- in the 
-\family typewriter
-get_options
-\family default
- function to be freed as it gets replaced by a new argv again by 
-\family typewriter
-HX_getopt
-\family default
- in 
-\family typewriter
-get_cakes
-\family default
-\SpecialChar breakableslash
-
-\family typewriter
-get_fruit
-\family default
-.
- 
-\family typewriter
-HXOPT_\SpecialChar softhyphen
-DESTROY_\SpecialChar softhyphen
-OLD
-\family default
- is however 
-\shape italic
-not
-\shape default
- specified in the first invocation, because the initial argv resides on
- the stack and cannot be freed.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-static bool
-\series default
- get_cakes(
-\series bold
-int *
-\series default
-argc, 
-\series bold
-const char ***
-\series default
-argv)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- HXoption option_table
-\series bold
-[]
-\series default
- = {
-\begin_inset Newline newline
-\end_inset
-
-                ...
-\begin_inset Newline newline
-\end_inset
-
-        };
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-return
-\series default
- HX_getopt(cake_table, argc, argv,
-\begin_inset Newline newline
-\end_inset
-
-               HXOPT_USAGEONERR | HXOPT_DESTROY_OLD) == HXOPT_ERR_SUCCESS;
-\begin_inset Newline newline
-\end_inset
-
-}
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static bool
-\series default
- get_fruit(
-\series bold
-int *
-\series default
-argc, 
-\series bold
-const char ***
-\series default
-argv)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- HXoption fruit_table
-\series bold
-[]
-\series default
- = {
-\begin_inset Newline newline
-\end_inset
-
-                ...
-\begin_inset Newline newline
-\end_inset
-
-        };
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-return
-\series default
- HX_getopt(fruit_table, argc, argv,
-\begin_inset Newline newline
-\end_inset
-
-               HXOPT_USAGEONERR | HXOPT_DESTROY_OLD) == HXOPT_ERR_SUCCESS;
-\begin_inset Newline newline
-\end_inset
-
-}
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-static bool
-\series default
- get_options(
-\series bold
-int *
-\series default
-argc, 
-\series bold
-const char ***
-\series default
-argv)
-\begin_inset Newline newline
-\end_inset
-
-{
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-int
-\series default
- cake = 0, fruit = 0;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-struct
-\series default
- HXoption option_table
-\series bold
-[]
-\series default
- = {
-\begin_inset Newline newline
-\end_inset
-
-                {.ln = "cake",  .type = HXTYPE_NONE, .ptr = &cake},
-\begin_inset Newline newline
-\end_inset
-
-                {.ln = "fruit", .type = HXTYPE_NONE, .ptr = &fruit},
-\begin_inset Newline newline
-\end_inset
-
-                HXOPT_TABLEEND,
-\begin_inset Newline newline
-\end_inset
-
-        };
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-if
-\series default
- (HX_getopt(option_table, argc, argv, HXOPT_PTHRU) !=
-\begin_inset Newline newline
-\end_inset
-
-            HXOPT_ERR_SUCCESS)
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-return
-\series default
- false;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-if
-\series default
- (cake)
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-return
-\series default
- get_cakes(argc, argv);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-else if
-\series default
- (fruit)
-\begin_inset Newline newline
-\end_inset
-
-                
-\series bold
-return
-\series default
- get_fruit(argc, argv);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-return
-\series default
- false;
-\begin_inset Newline newline
-\end_inset
-
-}
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Shell-style configuration file parser
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:shconf"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-libHX provides functions to read shell-style configuration files.
- Such files are common, for example, in 
-\family typewriter
-/etc/sysconfig
-\family default
- on Linux systems.
- The format is pretty basic; it only knows about 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-key=value
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- pairs and does not even have sections like INI files.
- Not relying on any features however makes them quite interchangable as
- the syntax is accepted by Unix Shells.
-\end_layout
-
-\begin_layout Standard
-Lines beginning with a hash mark (
-\family typewriter
-#
-\family default
-) are ignored, as are empty lines and unrecognized keys.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-# Minimum / maximum values for automatic UID selection
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-UID_MIN=100
-\begin_inset Newline newline
-\end_inset
-
-UID_MAX=65000
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-# Home directory base
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-HOME="/home"
-\begin_inset Newline newline
-\end_inset
-
-#HOME="/export/home"
-\end_layout
-
-\begin_layout Standard
-Any form of variable or parameter substitution or expansion is highly implementa
-tion specific, and is not supported in libHX's reader.
- Even Shell users should not rely on it as you never know in which context
- the configuration files are evaluated.
- Still, you will have to escape specific sequences like you would need to
- in Shell.
- The use of single quotes is acceptable.
- That means:
-\end_layout
-
-\begin_layout LyX-Code
-AMOUNT="US
-\backslash
-$5"
-\begin_inset Newline newline
-\end_inset
-
-AMOUNT='US$5'
-\end_layout
-
-\begin_layout Subsection
-Synopsis
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/option.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/option.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_shconfig(
-\series bold
-const char *
-\series default
-file, 
-\series bold
-const struct
-\series default
- HXoption 
-\series bold
-*
-\series default
-table);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_shconfig
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_shconfig_pv(
-\series bold
-const char **
-\series default
-path_vec, 
-\series bold
-const char *
-\series default
-file,
-\begin_inset Newline newline
-\end_inset
-
-                   
-\series bold
-const struct
-\series default
- HXoption 
-\series bold
-*
-\series default
-table, 
-\series bold
-unsigned int
-\series default
- flags);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_shconfig_pv
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXmap 
-\series bold
-*
-\series default
-HX_shconfig_map(
-\series bold
-const char *
-\series default
-file);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_shconfig_map
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The shconfig parser reuses 
-\family typewriter
-struct HXoption
-\family default
- that fits very well in specifying name-pointer associations.
- 
-\family typewriter
-HX_shconfig
-\family default
- will read the given file using the key-to-pointer mappings from the table
- to store the variable contents.
- Of 
-\family typewriter
-struct HXoption
-\family default
-, described in section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "subsec:option-synopsis"
-
-\end_inset
-
-, only the 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-ln
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-, 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-type
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- and 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-ptr
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- fields are used.
- The list of accepted types is described in section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "subsec:option-types"
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-To parse a file, call 
-\family typewriter
-HX_shconfig
-\family default
- function with the corresponding parameters.
- If you want to read configuration files from different paths, i.
-\begin_inset space \thinspace{}
-\end_inset
-
-e.
-\begin_inset space \space{}
-\end_inset
-
-to build up on default values, you can use 
-\family typewriter
-HX_shconfig_pv
-\family default
-
-\begin_inset Foot
-status open
-
-\begin_layout Plain Layout
-pv = path vector
-\end_layout
-
-\end_inset
-
-, which is a variant for reading a file from multiple locations.
- Its purpose is to facilitate reading system-wide settings which are then
- overriden by a file in the users home directory, for example (per-setting-overr
-ide).
- It is also possible to do per-file-override, that is, a file in the home
- directory has higher precedence than a system-wide one in such a way that
- the system-wide configuration file is not even read.
- This is accomplished by traversing the paths in the 
-\begin_inset Quotes eld
-\end_inset
-
-other
-\begin_inset Quotes erd
-\end_inset
-
- direction (actually you have to turn the array around) and stopping at
- the first existing file by use of the 
-\family typewriter
-SHCONF_\SpecialChar softhyphen
-ONE
-\family default
- flag.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-HX_shconfig_map
-\family default
- will return all entries from the file in a HXmap, usable for parsing arbitrary
- keys without having to specify any static key table.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-SHCONF_ONE
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-SHCONF_ONE
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Parsing files will stop after one file has been successfully parsed.
- This allows for a 
-\begin_inset Quotes eld
-\end_inset
-
-personal overrides system config
-\begin_inset Quotes erd
-\end_inset
-
- style.
-\end_layout
-
-\begin_layout Standard
-The call to 
-\family typewriter
-HX_shconfig
-\family default
- will either return >0 for success, 0 for no success (actually, this is
- never returned) and 
-\family typewriter
--errno
-\family default
- for an error.
-\end_layout
-
-\begin_layout Subsection
-Example
-\end_layout
-
-\begin_layout Subsubsection
-Per-setting-override
-\end_layout
-
-\begin_layout Standard
-This example sources key-value pairs from a configuration file in a system
- location (
-\family typewriter
-/etc
-\family default
-) first, before overriding specific keys with new values from the file in
- the home directory.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-long
-\series default
- uid_min, uid_max;
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-passwd_file;
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXoption options_table
-\series bold
-[]
-\series default
- = {
-\begin_inset Newline newline
-\end_inset
-
-        {.ln = "UID_MIN",  .type = HXTYPE_LONG,   .ptr = &uid_min},
-\begin_inset Newline newline
-\end_inset
-
-        {.ln = "UID_MAX",  .type = HXTYPE_LONG,   .ptr = &uid_max},
-\begin_inset Newline newline
-\end_inset
-
-        {.ln = "PWD_FILE", .type = HXTYPE_STRING, .ptr = &passwd_file},
-\begin_inset Newline newline
-\end_inset
-
-        HXOPT_TABLEEND,
-\begin_inset Newline newline
-\end_inset
-
-};
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-const char *
-\series default
-home = getenv("HOME");
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-const char *
-\series default
-paths
-\series bold
-[]
-\series default
- = {"/etc", home, NULL};
-\begin_inset Newline newline
-\end_inset
-
-HX_shconfig(paths, "test.cf", options_table, 0);
-\end_layout
-
-\begin_layout Subsubsection
-Per-file-override
-\end_layout
-
-\begin_layout Standard
-This particular example reads from the file in the home directory first
- (if it exists), but stops after it has been successfull, so any subsequent
- locations listed in the 
-\family typewriter
-paths
-\family default
- variable are not read.
- This has the effect that the file from the home directory has the highest
- priority too like in the previous example, but without any keys from the
- system files.
- Note the 
-\family typewriter
-SHCONF_ONE
-\family default
- flag.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-const char *
-\series default
-home = getenv("HOME");
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-const char *
-\series default
-paths
-\series bold
-[]
-\series default
- = {home, "/usr/local/etc", "/etc", NULL};
-\begin_inset Newline newline
-\end_inset
-
-HX_shconfig_pv(paths, "test.cf", options_table, SHCONF_ONE);
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Part
-Systems-related components
-\end_layout
-
-\begin_layout Section
-Random numbers
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:random"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsection
-Function overview
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/misc.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/misc.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HX_rand(
-\series bold
-void
-\series default
-);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_rand
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-unsigned int
-\series default
- HX_irand(
-\series bold
-unsigned int
-\series default
- min, 
-\series bold
-unsigned int
-\series default
- max);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_irand
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-double
-\series default
- HX_drand(
-\series bold
-double
-\series default
- min, 
-\series bold
-double
-\series default
- max);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_drand
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_rand
-\family default
- Retrieve the next random number.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_irand
-\family default
- Retrieve the next random number and fold it so that 
-\begin_inset Formula $\textit{min}\le n<\textit{max}$
-\end_inset
-
-, where min and max are unsigned integers.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HX_drand
-\family default
- Retrieve the next random number and fold it so that 
-\begin_inset Formula $\textit{min}\le n<\textit{max}$
-\end_inset
-
-, where min and max are double-precision floating point numbers.
-\end_layout
-
-\begin_layout Subsection
-Implementation information
-\end_layout
-
-\begin_layout Standard
-On systems that provide operating system-level random number generators,
- predominantly Linux and Unix-alikes such as BSD and Solaris, these will
- be used when they are available and random numbers are requested through
- 
-\family typewriter
-HX_rand
-\family default
- or 
-\family typewriter
-HX_irand
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-On Linux, Solaris and the BSDs, this is 
-\family typewriter
-/dev/urandom
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-/dev/urandom
-\end_layout
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Standard
-If no random number generating device is available (and libHX configured
- to use it), it will fall back to using the libc's 
-\family typewriter
-rand
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-rand
-\end_layout
-
-\end_inset
-
- function.
- If libc is selected for random number generation, 
-\family typewriter
-srand
-\family default
- will be called on library initialization with what is believed to be good
- defaults
-\begin_inset space ~
-\end_inset
-
-— usually this will be before a program's 
-\family typewriter
-main
-\family default
- function with normal linking, but may actually happen later when used with
- 
-\family typewriter
-dlopen
-\family default
-.
- The initial seed would be the current microtime when 
-\family typewriter
-gettimeofday
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-gettimeofday
-\end_layout
-
-\end_inset
-
-
-\family default
- is available, or just the seconds with 
-\family typewriter
-time
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-time
-\end_layout
-
-\end_inset
-
-.
- To counter the problem of different programs potentially using the same
- seed within a time window of a second due to the limited granularity of
- standard 
-\family typewriter
-time
-\family default
-, the seed is augmented by process ID and parent process ID where available.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-/dev/random
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-/dev/random
-\end_layout
-
-\end_inset
-
-
-\family default
- is not used on Linux because it may block during read, and 
-\family typewriter
-/dev/urandom
-\family default
- is just as good when there is entropy available.
- If you need definitive PRNG
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-PRNG
-\end_layout
-
-\end_inset
-
- security, perhaps use one from a crypto suite such as OpenSSL.
-\end_layout
-
-\begin_layout Standard
-\begin_inset Newpage clearpage
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Process management
-\begin_inset CommandInset label
-LatexCommand label
-name "sec:proc"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The process code is experimental at this stage (just moved from the pam_mount
- codebase).
- As it also relies on the POSIX functions 
-\family typewriter
-fork
-\family default
-, 
-\family typewriter
-execv
-\family default
-, 
-\family typewriter
-execvp
-\family default
- and 
-\family typewriter
-pipe
-\family default
-(2), so it may not be available everywhere.
- Where this is the case, the functions will return 
-\family typewriter
--ENOSYS
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-Process metadata structure
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/proc.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/proc.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXproc {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-const struct
-\series default
- HXproc_ops 
-\series bold
-*
-\series default
-p_ops;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-void *
-\series default
-p_data;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-unsigned int
-\series default
- p_flags;
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-Following members should only be read
-\family default
-\series bold
-\shape default
- */
-\series default
-
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-int
-\series default
- p_stdin, p_stdout, p_stderr;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-int
-\series default
- p_pid;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-char
-\series default
- p_status;
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-bool
-\series default
- p_exited, p_terminated;
-\begin_inset Newline newline
-\end_inset
-
-};
-\end_layout
-
-\begin_layout Standard
-When creating a new process with the intent of running it asynchronously
- (using 
-\family typewriter
-HXproc_\SpecialChar softhyphen
-run_\SpecialChar softhyphen
-async
-\family default
-), the first three fields must be filled in by the user.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-p_ops
-\family default
- A table of callbacks, generally used for setting and/or restoring signals
- before/after execution.
- This member may be 
-\family typewriter
-NULL
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-p_data
-\family default
- Free pointer for the user to supply.
- Will be passed to the callback functions when they are invoked.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-p_flags
-\family default
- Process creation flags, see below.
-\end_layout
-
-\begin_layout Standard
-After the subprocess has been started, 
-\family typewriter
-HXproc_run_async
-\family default
- will have filled in some fields:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-p_stdin
-\family default
- If 
-\family typewriter
-HXPROC_STDIN
-\family default
- was specified in 
-\family typewriter
-p_flags
-\family default
-, 
-\family typewriter
-p_stdin
-\family default
- will be assigned the write side file descriptor of the subprocess's to-be
- stdin.
- The subprocess will get the read side file descriptor in this member.
- This is so that the correct fd is used in when 
-\family typewriter
-p_ops->p_postfork
-\family default
- is called.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-p_stdout
-\family default
- If 
-\family typewriter
-HXPROC_STDOUT
-\family default
- is specified in 
-\family typewriter
-p_flags
-\family default
-, 
-\family typewriter
-p_stdout
-\family default
- will be assigned the read side file descriptor of the subprocess's to-be
- stdout.
- The subprocess will get the write side file descriptor in this member.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-p_stderr
-\family default
- If 
-\family typewriter
-HXPROC_STDERR
-\family default
- is specified in 
-\family typewriter
-p_flags
-\family default
-, 
-\family typewriter
-p_stderr
-\family default
- will be assigned the read side file descriptor of the subprocess's to-be
- stderr, and the subprocess will get the write side fd.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-p_pid
-\family default
- The process ID of the spawned process.
-\end_layout
-
-\begin_layout Standard
-Upon calling 
-\family typewriter
-HXproc_wait
-\family default
-, further fields will have been filled when the function returns:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-p_exited
-\family default
- Whether the process exited normally (cf.
-\begin_inset space \space{}
-\end_inset
-
-signalled\SpecialChar breakableslash
-terminated).
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-p_terminated
-\family default
- Whether the process was terminated (signalled).
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-p_status
-\family default
- The exit status of the process or the termination signal.
-\end_layout
-
-\begin_layout Subsubsection
-Flags
-\begin_inset CommandInset label
-LatexCommand label
-name "subsec:proc-pflags"
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Possible values for the 
-\family typewriter
-p_flags
-\family default
- member are:
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXPROC_STDIN
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXPROC_STDIN
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- The subprocess's stdin file descriptor shall be connected to the master
- program, that is, not inherit the stdin of the master.
- Cannot be used for 
-\family typewriter
-HXproc_\SpecialChar softhyphen
-run_\SpecialChar softhyphen
-sync
-\family default
- (because there would be no one to provide data in a sync operation).
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXPROC_STDOUT
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXPROC_STDOUT
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Connect the stdout file descriptor of the subprocess with the master.
- Cannot be used for 
-\family typewriter
-HXproc_run_sync
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXPROC_STDERR
-\series medium
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\series medium
-HXPROC_STDERR
-\end_layout
-
-\end_inset
-
-
-\family default
-\series default
- Connect the stderr file descriptor of the subprocess with the master.
- Cannot be used for 
-\family typewriter
-HXproc_run_sync
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXPROC_NULL_STDIN
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXPROC_NULL_STDIN
-\end_layout
-
-\end_inset
-
- The subprocess's stdin file descriptor shall be connected to 
-\family typewriter
-/dev\SpecialChar breakableslash
-null
-\family default
-.
- 
-\family typewriter
-HXPROC_\SpecialChar softhyphen
-STDIN
-\family default
- and 
-\family typewriter
-HXPROC_\SpecialChar softhyphen
-NULL_\SpecialChar softhyphen
-STDIN
-\family default
- are mutually exclusive.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXPROC_NULL_STDOUT
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXPROC_NULL_STDOUT
-\end_layout
-
-\end_inset
-
- Connect the stdout file descriptor of the subprocess to 
-\family typewriter
-/dev\SpecialChar breakableslash
-null
-\family default
-, thereby essentially discarding its output.
- 
-\family typewriter
-HXPROC_\SpecialChar softhyphen
-STDOUT
-\family default
- and 
-\family typewriter
-HXPROC_\SpecialChar softhyphen
-NULL_\SpecialChar softhyphen
-STDOUT
-\family default
- are mutuall exclusive.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXPROC_NULL_STDERR
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXPROC_NULL_STDERR
-\end_layout
-
-\end_inset
-
- Connect the stderr file descriptor of the subprocess to 
-\family typewriter
-/dev\SpecialChar breakableslash
-null
-\family default
-, thereby essentially discarding its output.
- 
-\family typewriter
-HXPROC_\SpecialChar softhyphen
-STDERR
-\family default
- and 
-\family typewriter
-HXPROC_\SpecialChar softhyphen
-NULL_\SpecialChar softhyphen
-STDERR
-\family default
- are mutually exclusive.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXPROC_VERBOSE
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXPROC_VERBOSE
-\end_layout
-
-\end_inset
-
- Have the subprocess print an error message to stderr if exec'ing returned
- an error.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXPROC_A0
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXPROC_A0
-\end_layout
-
-\end_inset
-
- 
-\family typewriter
-argv[0]
-\family default
- refers to program file, while 
-\family typewriter
-argv[1]
-\family default
- to the program invocation name, with 
-\family typewriter
-argv[2]
-\family default
- being the arguments.
- Without this flag, 
-\family typewriter
-argv[0]
-\family default
- will be both the program file and program invocation name, and arguments
- begin at 
-\family typewriter
-argv[1]
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXPROC_EXECV
-\family default
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HXPROC_EXECV
-\end_layout
-
-\end_inset
-
- Normally, 
-\family typewriter
-execvp
-\family default
-(3)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-execvp
-\end_layout
-
-\end_inset
-
- will be used which scans 
-\family typewriter
-$PATH
-\family default
- for the program.
- Use this flag to use 
-\family typewriter
-execv
-\family default
-(3)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-execv
-\end_layout
-
-\end_inset
-
- instead, which will not do such thing.
-\end_layout
-
-\begin_layout Subsection
-Callbacks
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/proc.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-struct
-\series default
- HXproc_ops {
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-void (*
-\series default
-p_prefork
-\series bold
-)
-\series default
-(
-\series bold
-void *
-\series default
-);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-void (*
-\series default
-p_postfork
-\series bold
-)
-\series default
-(
-\series bold
-void *
-\series default
-);
-\begin_inset Newline newline
-\end_inset
-
-        
-\series bold
-void (*
-\series default
-p_complete
-\series bold
-)
-\series default
-(
-\series bold
-void *
-\series default
-);
-\begin_inset Newline newline
-\end_inset
-
-};
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-struct HXproc_ops
-\family default
- provides a way to run user-specified functions just before the fork, after,
- and when the process has been waited for.
- They can be used to set and/or restore signals as needed, for example.
- The function pointers can be 
-\family typewriter
-NULL
-\family default
-.
- The 
-\family typewriter
-p_data
-\family default
- member is passed as an argument.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-p_prefork
-\family default
- Run immediately before calling 
-\family typewriter
-fork
-\family default
-(2).
- This is useful, for taking any action regarding signals, like setting 
-\family typewriter
-SIGCHLD
-\family default
- to 
-\family typewriter
-SIG_DFL
-\family default
-, or 
-\family typewriter
-SIGPIPE
-\family default
- to 
-\family typewriter
-SIG_IGN
-\family default
-, for example.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-p_postfork
-\family default
- Run in the subprocess (and only there) after forking.
- Useful to do a 
-\family typewriter
-setuid
-\family default
-(2) or other change in privilege level.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-p_complete
-\family default
- Run in 
-\family typewriter
-HXproc_wait
-\family default
- when the process has been waited for.
- Useful to restore the signal handler(s).
-\end_layout
-
-\begin_layout Subsection
-Process control
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/proc.h>
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-
-\begin_inset Newline newline
-\end_inset
-
-int
-\series default
- HXproc_run_async(
-\series bold
-const char *const *
-\series default
-argv, 
-\series bold
-struct
-\series default
- HXproc 
-\series bold
-*
-\series default
-proc);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXproc_run_async
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HXproc_run_sync(
-\series bold
-const char *const *
-\series default
-argv, 
-\series bold
-unsigned int
-\series default
- flags);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXproc_run_sync
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- HXproc_wait(
-\series bold
-struct
-\series default
- HXproc 
-\series bold
-*
-\series default
-proc);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HXproc_wait
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXproc_run_async
-\family default
- Start a subprocess according to the parameters in 
-\family typewriter
-proc
-\family default
-.
- Returns a negative errno code if something went wrong, or positive non-zero
- on success.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXproc_run_sync
-\family default
- Start a subprocess synchronously, similar to calling 
-\family typewriter
-system
-\family default
-(3)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-system
-\end_layout
-
-\end_inset
-
-, but with the luxury of being able to specify arguments as separate strings
- (via argv) rather than one big command line that is run through the shell.
- 
-\family typewriter
-flags
-\family default
- is a value composed of the HXproc flags mentioned above in section
-\begin_inset space ~
-\end_inset
-
-
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "subsec:proc-pflags"
-
-\end_inset
-
-.
- 
-\family typewriter
-HXPROC_STDIN
-\family default
-, 
-\family typewriter
-HXPROC_STDOUT
-\family default
- and 
-\family typewriter
-HXPROC_STDERR
-\family default
- are ignored because there would be no one in a synchronous execution that
- could supply data to these file descriptors or read from them
-\begin_inset Foot
-status open
-
-\begin_layout Plain Layout
-Even for threads, please just use the async model.
-\end_layout
-
-\end_inset
-
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-HXproc_wait
-\family default
- Wait for a subprocess to terminate, if it has not already.
- It will also retrieve the exit status of the process and store it in the
- 
-\family typewriter
-struct HXproc
-\family default
-.
-\end_layout
-
-\begin_layout Standard
-Return value will be positive non-zero on success, or negative on error.
- Underlying system function's errors are returned, plus:
-\end_layout
-
-\begin_layout Description
-
-\family sans
-EINVAL
-\family default
- Flags were not accepted.
-\end_layout
-
-\begin_layout Section
-Helper headers
-\end_layout
-
-\begin_layout Subsection
-ctype helpers
-\end_layout
-
-\begin_layout Standard
-Functions from the 
-\family typewriter
-<ctype.h>
-\family default
- header, including, but not limited to, 
-\family typewriter
-isalpha
-\family default
-, 
-\family typewriter
-tolower
-\family default
-, and so forth, are defined to take an 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-int
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- as first argument.
- Strings used in C programs are usually 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-, without any 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-signed
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- or 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-unsigned
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- qualifier.
- By a high-level view, which also matches daily common sense, characters
- (a.
-\begin_inset space \thinspace{}
-\end_inset
-
-k.
-\begin_inset space \thinspace{}
-\end_inset
-
-a.
-\begin_inset space \space{}
-\end_inset
-
-letters) have no notion of signedness
-\begin_inset space ~
-\end_inset
-
-— there is no 
-\begin_inset Quotes eld
-\end_inset
-
-positive
-\begin_inset Quotes erd
-\end_inset
-
- or 
-\begin_inset Quotes eld
-\end_inset
-
-negative
-\begin_inset Quotes erd
-\end_inset
-
- 
-\begin_inset Quotes eld
-\end_inset
-
-A
-\begin_inset Quotes erd
-\end_inset
-
- in at least the Latin alphabet that is mapped into the ASCII set.
- In fact, 
-\family typewriter
-char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
- could either be 
-\family typewriter
-signed char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
- or 
-\family typewriter
-unsigned char
-\begin_inset space ~
-\end_inset
-
-*
-\family default
-, depending on the compiler settings.
- Only when you start interpreting and using characters as a number does
- such become important.
- 
-\end_layout
-
-\begin_layout Standard
-There come the problems.
- Characters are in the same class as numbers in C, that is, can be implicitly
- converted from or to a 
-\begin_inset Quotes eld
-\end_inset
-
-number
-\begin_inset Quotes erd
-\end_inset
-
- (in this case, their ASCII code point) without causing a compiler warning.
- That may be practical in some cases, but is also a bit 
-\begin_inset Quotes eld
-\end_inset
-
-unfortunate
-\begin_inset Quotes erd
-\end_inset
-
-.
- Characters, when interpreted as the 8-bit signed numeric quantity they
- are implicitly convertable to, run from 0 to 127 and \SpecialChar nobreakdash
-128 to \SpecialChar nobreakdash
-1.
- Since the 
-\family typewriter
-isalpha
-\family default
- function and others from 
-\family typewriter
-ctype.h
-\family default
- take a (signed) 
-\family typewriter
-int
-\family default
- as argument means that values fed to 
-\family typewriter
-isalpha
-\family default
- are sign-extended, preserving negative values.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-/* 
-\family roman
-\series default
-\shape italic
-
-\begin_inset Quotes eld
-\end_inset
-
-hyvää yötä
-\begin_inset Quotes erd
-\end_inset
-
-, UTF-8 encoded
-\family default
-\series bold
-\shape default
- */
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-const char 
-\series default
-h
-\series bold
-[]
-\series default
- = {'h', 'y', 'v', 0xc3, 0xa4, 0xc3, 0xa4, ' ',
-\begin_inset Newline newline
-\end_inset
-
-                  'y', 0xc3, 0xb6, 't', 0xc3, 0xa4};
-\end_layout
-
-\begin_layout Standard
-When you now pass 
-\family typewriter
-h[3]
-\family default
- to 
-\family typewriter
-isalpha
-\family default
- for example (regardless of whether doing so actually produces a meaningful
- result), the CPU is instructed to copy 
-\begin_inset Quotes eld
-\end_inset
-
-0xc3
-\begin_inset Quotes erd
-\end_inset
-
- into a register and sign-extend it (because 
-\begin_inset Quotes eld
-\end_inset
-
-char
-\begin_inset Quotes erd
-\end_inset
-
- is often 
-\begin_inset Quotes eld
-\end_inset
-
-signed char
-\begin_inset Quotes erd
-\end_inset
-
-, see above), producing 0xffffffc3 (\SpecialChar nobreakdash
-61).
- But passing \SpecialChar nobreakdash
-61 is not what was intended.
-\end_layout
-
-\begin_layout Standard
-libHX's 
-\family typewriter
-ctype_helper.h
-\family default
- therefore provides wrappers with a different function signature that uses
- zero extension (not sign extension) by means of using an 
-\family typewriter
-unsigned
-\family default
- quantity.
- Currently this is
-\family typewriter
- unsigned char
-\family default
-, because 
-\family typewriter
-isalpha
-\family default
-'s domain only goes from 0–255.
- The implication is that you cannot pass 
-\family typewriter
-EOF
-\family default
- to 
-\family typewriter
-HX_isalpha
-\family default
-.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/ctype_helper.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/ctype_helper.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-bool
-\series default
- HX_isalnum(
-\series bold
-unsigned char
-\series default
- c);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_isalnum
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-bool
-\series default
- HX_isalpha(
-\series bold
-unsigned char
-\series default
- c);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_isalpha
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-bool
-\series default
- HX_isdigit(
-\series bold
-unsigned char
-\series default
- c);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_isdigit
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-bool
-\series default
- HX_islower(
-\series bold
-unsigned char
-\series default
- c);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_islower
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-bool
-\series default
- HX_isprint(
-\series bold
-unsigned char
-\series default
- c);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_isprint
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-bool
-\series default
- HX_isspace(
-\series bold
-unsigned char
-\series default
- c);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_isspace
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-bool
-\series default
- HX_isupper(
-\series bold
-unsigned char
-\series default
- c);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-HX_isupper
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-bool
-\series default
- HX_isxdigit(
-\series bold
-unsigned char
-\series default
- c);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_isxdigit
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-unsigned char
-\series default
- HX_tolower(
-\series bold
-unsigned char
-\series default
- c);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_tolower
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-unsigned char
-\series default
- HX_toupper(
-\series bold
-unsigned char
-\series default
- c);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-HX_toupper
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The 
-\family typewriter
-is*
-\family default
- functions also differ from ctype's in that they return 
-\family typewriter
-bool
-\family default
- instead of 
-\family typewriter
-int
-\family default
-.
- Not all functions from 
-\family typewriter
-ctype.h
-\family default
- are present either; 
-\family typewriter
-isascii
-\family default
-, 
-\family typewriter
-isblank
-\family default
-, 
-\family typewriter
-iscntrl
-\family default
-, 
-\family typewriter
-isgraph
-\family default
-, 
-\family typewriter
-ispunct
-\family default
- and 
-\family typewriter
-isxdigit
-\family default
- have been omitted as the author has never needed them so far.
-\end_layout
-
-\begin_layout Subsection
-libxml2 helpers
-\end_layout
-
-\begin_layout Standard
-libxml2 uses an 
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-xmlChar
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
- type as an underlying type for the strings that it reads and outputs.
- 
-\family typewriter
-xmlChar
-\family default
- is typedef'ed to 
-\family typewriter
-unsigned char
-\family default
- by libxml2, causing compiler warnings related to differing signedness whenever
- interacting with strings from the outside world, which are usually just
- a pointer to 
-\family typewriter
-char
-\family default
-.
- Because casting would be a real chore, 
-\family typewriter
-libxml_helper.h
-\family default
- will do it by providing some wrappers with better argument types.
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/libxml_helper.h>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/libxml_helper.h
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- xml_strcmp(
-\series bold
-const
-\series default
- xmlChar 
-\series bold
-*
-\series default
-a, 
-\series bold
-const char *
-\series default
-b);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-xml_strcmp
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-int
-\series default
- xml_strcasecmp(
-\series bold
-const
-\series default
- xmlChar 
-\series bold
-*
-\series default
-a, 
-\series bold
-const char *
-\series default
-b);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-xml_strcasecmp
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-char *
-\series default
-xml_getprop(xmlNode 
-\series bold
-*
-\series default
-node, 
-\series bold
-const char *
-\series default
-attr);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-xml_getprop
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-char *xml_getnsprop(
-\series bold
-xmlNode *
-\series default
-node, 
-\series bold
-const char *
-\series default
-nsprefix, 
-\series bold
-const char *
-\series default
-attr);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-xml_getnsprop
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-xmlAttr 
-\series bold
-*
-\series default
-xml_newprop(xmlNode 
-\series bold
-*
-\series default
-node, 
-\series bold
-const char *
-\series default
-attr);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-xml_newprop
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-xmlNode 
-\series bold
-*
-\series default
-xml_newnode(xmlNode 
-\series bold
-*
-\series default
-parent, 
-\series bold
-const char *
-\series default
-name, 
-\series bold
-const char *
-\series default
-value);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-xml_newnode
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-xmlAttr 
-\series bold
-*
-\series default
-xml_setprop(xmlNode 
-\series bold
-*
-\series default
-node, 
-\series bold
-const char *
-\series default
-name, 
-\series bold
-const char *
-\series default
-value);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-\size normal
-\color none
-xml_setprop
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The functions map to 
-\family typewriter
-strcmp
-\family default
-(3)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-strcmp
-\end_layout
-
-\end_inset
-
-, 
-\family typewriter
-strcasecmp
-\family default
-(3)
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-strcasecmp
-\end_layout
-
-\end_inset
-
-, 
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-xmlGetProp
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-xmlGetProp
-\family default
-, 
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-xmlNewProp
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-xmlNewProp
-\family default
-, 
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-xmlNewTextNode
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-xml\SpecialChar softhyphen
-New\SpecialChar softhyphen
-Text\SpecialChar softhyphen
-Node
-\family default
- and 
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-xmlSetProp
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-xml\SpecialChar softhyphen
-Set\SpecialChar softhyphen
-Prop
-\family default
-, respectively.
-\end_layout
-
-\begin_layout Standard
-
-\family typewriter
-xml_getnsprop
-\family default
- works similar to 
-\family typewriter
-xmlGetNsProp
-\family default
-, but instead of taking a namespace URI, it does a lookup by namespace prefix.
- The argument order is also different compared to 
-\family typewriter
-xmlGetNsProp
-\family default
-.
-\end_layout
-
-\begin_layout Subsection
-wxWidgets
-\end_layout
-
-\begin_layout LyX-Code
-
-\series bold
-#include
-\series default
- <libHX/wx_helper.hpp>
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-libHX/wx_helper.hpp
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Subsubsection
-Shortcut macros
-\end_layout
-
-\begin_layout Description
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxACV
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-wxACV
-\family default
- Expands to 
-\family typewriter
-
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxALIGN_CENTER_VERTICAL
-\end_layout
-
-\end_inset
-
-wxALIGN_CENTER_VERTICAL
-\end_layout
-
-\begin_layout Description
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxCDF
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-wxCDF
-\family default
- Expands to a set of common dialog flags for 
-\family typewriter
-wxDialog
-\family default
-s, which includes 
-\family typewriter
-wxDEFAULT_\SpecialChar softhyphen
-FRAME_\SpecialChar softhyphen
-STYLE
-\family default
- and a flag such that the dialog does not create a new window in the task
- bar (
-\family typewriter
-wxFRAME_\SpecialChar softhyphen
-NO_\SpecialChar softhyphen
-TASKBAR
-\family default
-).
-\end_layout
-
-\begin_layout Description
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxDPOS
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-wxDPOS
-\family default
- Expands to 
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxDefaultPosition
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-wxDefaultPosition
-\family default
-.
-\end_layout
-
-\begin_layout Description
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxDSIZE
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-wxDSIZE
-\family default
- Expands to 
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxDefaultSize
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-wxDefaultSize
-\family default
-.
-\end_layout
-
-\begin_layout Description
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxDSPAN
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-wxDSPAN
-\family default
- Expands to 
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxDefaultSpan
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-wxDefaultSpan
-\family default
-.
-\end_layout
-
-\begin_layout Subsubsection
-String conversion
-\end_layout
-
-\begin_layout LyX-Code
-wxString wxfu8(
-\series bold
-const char *
-\series default
-);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxfu8
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-wxString wxfv8(
-\series bold
-const char *
-\series default
-);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxfv8
-\end_layout
-
-\end_inset
-
-
-\begin_inset Newline newline
-\end_inset
-
-
-\series bold
-const char *
-\series default
-wxtu8(
-\series bold
-const
-\series default
- wxString 
-\series bold
-&
-\series default
-);
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxtu8
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-wxfu8
-\family default
- Converts an UTF-8 string to a 
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxString
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-wxString
-\family default
- object.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-wxfv8
-\family default
- Converts an UTF-8 string to an entity usable by 
-\begin_inset Index idx
-status open
-
-\begin_layout Plain Layout
-
-\family typewriter
-wxPrintf
-\end_layout
-
-\end_inset
-
-
-\family typewriter
-wxPrintf
-\family default
-.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-wxtu8
-\family default
- Converts a wxString to a pointer to char usable by 
-\family typewriter
-printf
-\family default
-.
- Note that the validity of the pointer is very limited and usually does
- not extend the statement in which it is used.
- Hence storing the pointer in a variable (
-\begin_inset Quotes eld
-\end_inset
-
-
-\family typewriter
-const char *p = wxtu8(s);
-\family default
-
-\begin_inset Quotes erd
-\end_inset
-
-) will make 
-\family typewriter
-p
-\family default
- pointing to an invalid region as soon as the assignment is done.
-\end_layout
-
-\begin_layout Part
-\start_of_appendix
-Appendix
-\end_layout
-
-\begin_layout Standard
-\begin_inset CommandInset index_print
-LatexCommand printindex
-type "idx"
-name "Index"
-literal "true"
-
-\end_inset
-
-
-\end_layout
-
-\end_body
-\end_document