1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
-lite | Frog DNA, basically
===========================
[![GitHub Status][]][GitHub] [![codedocs status][]][codedocs] [![Coverity Status][]][Coverity Scan]
Table of Contents
-----------------
* [Introduction](#introduction)
* [Using -lite](#using--lite)
* [API](doc/API.md#overview)
* [Important Node](doc/API.md#important-note)
* [Helper Macros](doc/API.md#helper-macros)
* [Generic Functions](doc/API.md#generic-functions)
* [GNU Functions](doc/API.md#gnu-functions)
* [OpenBSD/NetBSD/FreeBSD Functions](doc/API.md#openbsd-netbsd-freebsd-functions)
* [Build & Install](#build--install)
* [Origin & References](#origin--references)
> **NOTE:** Incompatible changes in v2.0 compared to v1.x!
Introduction
------------
Libite is a lightweight library of *frog DNA* that can be used to fill
the gaps in any dinosaur project. It holds useful functions and macros
developed by both [Finit][1] and the [OpenBSD][2] project. Most notably
the string functions: [strlcpy(3)][3], [strlcat(3)][3] and the highly
useful *BSD [sys/queue.h][4] and [sys/tree.h][7] API's.
Libite holds many of the missing pieces in GNU libc, although -lite does
not aim to become another [GLIB][5]. One noticeable gap in GLIBC is the
`_SAFE` macros available in the BSD `sys/queue.h` API — highly
recommended when traversing lists to delete/free nodes.
The code is open sourced under a mix of permissive Open Source licenses:
[MIT/X11 license][MIT], [ISC license][ISC], and [BSD licenses][BSD].
> **Tip:** have a look at my blog post about other useful UNIX API's!
> https://troglobit.com/post/2020-02-22-useful-unix-apis/
Using -lite
-----------
Libite is by default installed as a library and a set of include files.
To prevent clashing with include files of the same name `-lite` employs
an include file namespace `libite/`, which is strongly recommended to
use in your applications:
```C
#include <libite/lite.h>
#include <libite/conio.h>
#include <libite/queue.h>
#include <libite/tree.h>
```
> **Note:** prior to v2.5.0, the `lite/` namespace was used for headers,
> which is still available in the default install. This clashed with
> the headers of the LiTE library from the DirectFB project.
The output from the `pkg-config` tool holds no surprises:
```bash
$ pkg-config --libs --static --cflags libite
-I/usr/local/include -D_LIBITE_LITE -L/usr/local/lib -lite
```
> **Note:** `_LIBITE_LITE` is defined since v2.5.0, useful for software
> that want to be able to build against headers from an older libite:
>
> ```C
> #ifdef _LIBITE_LITE
> # include <libite/lite.h>
> #else
> # include <lite/lite.h>
> #endif
> ```
The prefix path `/usr/local/` shown here is only the default. Use the
`configure` script to select a different prefix when installing libite.
For GNU autotools based projects, use the following in `configure.ac`:
```m4
# Check for required libraries
PKG_CHECK_MODULES([lite], [libite >= 1.5.0])
```
and in your `Makefile.am`:
```Makefile
proggy_CFLAGS = $(lite_CFLAGS)
proggy_LDADD = $(lite_LIBS)
```
> API Documentaion: https://codedocs.xyz/troglobit/libite/
Build & Install
---------------
This library was initially built for and developed on GNU/Linux systems
as a light weight utility library, these days NetBSD should also work.
```bash
$ ./configure
$ make -j5
$ sudo make install-strip
$ sudo ldconfig
```
Use <kbd>./configure --without-symlink</kbd> to prevent the install step
from creating the `lite -> libite/` compatibility symlink for the header
files, required for systems with DirectFB LiTE. The default, however,
is to install the symlink to ensure compatibility with existing software
that depends on the `-lite` library headers in their previous namespace.
**Note:** When checking out code from GIT, use <kbd>./autogen.sh</kbd>
to generate a `configure` script. It is a generated file and otherwise
only included in released tarballs.
Origin & References
-------------------
Much of the code in libite (-lite) is written by [Claudio Matsuoka][]
for the original [Finit][original finit] and released under the MIT/X11
license. Joachim Wiberg later improved on the [Finit][1] code base and
included pieces of software released under the ISC and BSD licenses.
See each respective file for license details.
[1]: https://github.com/troglobit/finit
[2]: http://www.openbsd.org/
[3]: http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy
[4]: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/LIST_EMPTY.3
[5]: https://developer.gnome.org/glib/
[7]: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/SPLAY_FOREACH.3
[MIT]: https://en.wikipedia.org/wiki/MIT_License
[ISC]: https://en.wikipedia.org/wiki/ISC_license
[BSD]: https://en.wikipedia.org/wiki/BSD_licenses
[GitHub]: https://github.com/troglobit/libite/actions/workflows/build.yml/
[GitHub Status]: https://github.com/troglobit/libite/actions/workflows/build.yml/badge.svg
[Coverity Scan]: https://scan.coverity.com/projects/20602
[Coverity Status]: https://img.shields.io/coverity/scan/20602.svg
[codedocs]: https://codedocs.xyz/troglobit/libite.log
[codedocs status]: https://codedocs.xyz/troglobit/libite.svg
[Claudio Matsuoka]: https://github.com/cmatsuoka
[original finit]: http://helllabs.org/finit/
|
