Internal APIs
=============

There's some common functionality found in many places like help, parsing
values, sorting, extensible arrays, etc. Not all places are unified and use old
code implementing it manually. Below is list of usable APIs that should be spread
and updated where it's still not. A need for new API might emerge from
cleanups, then it should appear here. The text below gives pointers and is not
extensive, search the definitions and actual use in other code too.

Option parsing
--------------

Files: :file:`common/help.h`, :file:`common/parse-utils.h`

Global options need to be processed and consumed by `clean_args_no_options`,
argument count by `check_argc_*`, `usage_*` for handling usage.

Options are parsed by `getopt` or `getopt_long`. Individual values from options
are recognized by `parse_*`, basic types and custom types are supported.

Size unit pretty printing
-------------------------

Files: :file:`common/units.h`

Many commands print byte sizes with suffixes and the output format can be
affected by command line options. In the help text the options are specified by
either `HELPINFO_UNITS_SHORT_LONG` (both long and short options) or just
`HELPINFO_UNITS_LONG` in case the short option letters would conflict.

Automatic parsing of the options from *argv* is done by `get_unit_mode_from_arg`.
Printing options is done by `pretty_size_mode` which takes the value and option
mode. Default mode is human readable, the macros defining the modes are from
`UNITS_*` namespace.

File path handling
------------------

Files: :file:`common/path-utils.h`

The paths on Linux can be at most PATH_MAX, which is 4096 (:command:`getconf`).
For easier handling use a local variable like :code:`char path[PATH_MAX] = { 0 };`
and for concatenation helpers :code:`path_cat_out()` or
:code:`path_cat_out3()` and check the error values for overflows. There are
helpers to check file type :code:`path_is_*()`.

Dynamic array of pointers
-------------------------

Files: :file:`common/array.h`

Extensible array containing pointers to objects, is reallocated when the
new elements don't fit current capacity. For iteration the array is accessible
as *array->datai[i]* of type *void\** and needs be cast to user type.

TODO
----

Undocumented or incomplete APIs:

* common/cpu-utils.h
* common/device-utils.h
* common/format-output.h
* common/messages.h
* common/open-utils.h
* common/rbtree-utils.h
* common/sort-utils.h
* common/string-table.h
* common/sysfs-utils.h
* common/task-utils.h