-lite | Frog DNA, basically
Table of Contents
- Using -lite
- Helper Macros
- Generic Functions
- OpenBSD Functions
- Build & Install
- Origin & References
NOTE: Incompatible changes in v2.0 compared to v1.x!
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 and the OpenBSD project. Most notably the string functions: strlcpy(3), strlcat(3) and the highly useful *BSD sys/queue.h and sys/tree.h API's.
Libite holds many of the missing pieces in GNU libc, although -lite does
not aim to become another GLIB. 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.
Libite is by default installed as a library and a set of include files.
To prevent clashing with include files of the same name
an include file namespace
lite/, which is strongly recommended to use
in your applications:
#include <lite/lite.h> #include <lite/conio.h> #include <lite/queue.h> #include <lite/tree.h>
The output from the
pkg-config tool holds no surprises in this regard:
$ pkg-config --libs --static --cflags libite -I/usr/local/include -L/usr/local/lib -lite
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
# Check for required libraries PKG_CHECK_MODULES([lite], [libite >= 1.5.0])
and in your
proggy_CFLAGS = $(lite_CFLAGS) proggy_LDADD = $(lite_LIBS)
When using functions like
make sure your
umask() is correct so you do not accidentally create
files and directories accessible to other users than intended.
Convert string to natural number, works for 32-bit non-negative integers. Returns -1 on error. (Uses
Create block device
Create character device
Erase file/directory with
remove(). Errors on
Create directory, like
mkdir(). Errors on
Create a FIFO, like
mkfifo(). Errors on
These macros take care to avoid double evaluation.
Create a file, or update mtime. Errors on
Mysteriously missing from GLIBC
Is bit in (integer) word cleared?
Is bit in (integer) word set?
Are any other bits, except bit, in (integer) word set?
Set bit in (integer) word.
Clear bit in (integer) word.
Returns the number of elements in an array. From the great book, The Practice of Programming, by Kernighan and Pike.
Perl like chomp function, chop off last char if newline.
copyfile(src, dst, len, opt)
Like the shell
dd(1),, can also copy symlinks and preserve the mtime of the source file. The opt argument can be a mask of:
In releases prior to v2.0 the opt argument was called
symlink. The APIs are 100% compatible if the value
1was used to enable the symlink option.
dir(dir, ext, filter, list, strip)
scandir()with optional filter. Returns a list of names: files and directories that must be freed after use. See the unit test for an example, or take a look at
glob(3), it's probably what you want anyway.
copyfile()but uses already open
FILE *pointers. Copies from current file positions to current file positions until EOF.
Check for the existence of a file, returns True(1) or False(0).
Check for the existence of a directory, returns True(1) or False(0).
fopenf(mode, fmt, ...)
fopen(), but takes a formatted string as argument. This greatly simplifies operations that usually consist of composing a filename from parts into a dynamic buffer before actually opening the file.
Notice: the swapped order of
remove(), but takes a formatted string as argument. This greatly simplifies operations that usually consist of composing a filename from parts into a dynamic buffer before actually removing the file.
fsendfile(src, dst, len)
Copy data between file streams, very similar to
dstis allowed to be
NULLto be able to read and discard
ifconfig(ifname, addr, mask, up)
Basic ifconfig like operations on an interface. Only supports IPv4 addresses. Note that mask is not CIDR notation.
LITE file API for parsing UNIX style configuration files like
Read tokens, delimited by
sep, from file opened with
keyin file opened with
lfopen(), return value/argument.
lfgetkey(), returns positive integer value to
keyis not found.
fgetint(file, sep, key)
lfclose(). Useful for when only reading a single
keyfrom a file.
Create all components of the specified directory.
makepath(), but also takes a
mode_tpermission mode argument.
fmkpath(mode, fmt, ...)
mkpath(), but takes a formatted string as argument.
Notice: the swapped order of
copyfile(), but renames
dst, or recreates symlink with the
dstname. On successful operation the source is removed and the function returns POSIX OK (0).
Create a daemon PID file using either the
nameas a full path, if
/, or in
nameas the basename of the application. If
__prognameis used as the basename. The resulting file name is available to the user as a read-only pointer:
extern char *__pidfile_name;
Use this function to create a PID file for your daemon when it is ready to receive signals. A client application may poll for the existence of this file, so make sure to have your signal handlers properly setup before calling this function.
The PID file is removed when the program exits, using an
atexit()handler. However, depending on how the program terminates the file may still exist even though the program is no longer running.
Calling this function multiple times updates the mtime of the file. Only one
atexit()handler is created, regardless of the amount of times the function is called. If the file is removed, subsequent calls to this function will recreate the file.
See below for a link to OpenBSD man page.
Read PID from pid file created by
Send signal to PID found in pid file created by
Simple ASCII progress bar with a spinner. Start it with
percent=0and set the
max_width=charsto indicate width of the progress bar. Called multiple times with the same percentage value cause spinner to spin.
rsync(src, dst, opt, *filter())
rsync()to copy files and directories recursively. It supports pruning files from the destination tree that do not exist in the source tree and preserving the mtime of the source files. The opt argument can be a mask of:
In releases prior to v2.0 the argument controlling pruning was called
delete, it is now called
opt. The APIs are 100% compatible if the value
strnmatch(str, list, len)
Find matching string in an array of strings. Returns index in array on match, or
-1on error or not found.
strnmatch()takes an extra arg to compare only
lennumber of characters from
system(), but takes a formatted string as argument. This greatly simplifies operations that usually consist of composing a command from parts into a dynamic buffer before calling it.
telnet_open(addr, port), telnet_close(ctx), telnet_expect(ctx, script, output)
Poor mans telnet expect in C. Opens connection to a Telnet service; FTP, Telnet, similar, and run an expect-like script.
telnet_session(addr, port, script output)
Wrapper for the above three in one API.
Secure replacement for
tmpfile(). Creates an invisible temporary file in
/tmpthat is removed when the returned
FILEpointer is closed.
Note: Requires Linux v3.11, or later, will fall back to the old and unsafe
tmpfile()on older systems.
truncatef(length, fmt, ...)
truncate(), but takes a formatted string as argument. This simplifies some operations when the filename otherwise have to be composed from parts into a separate array before calling the real function.
C implementation of UNIX which(1). Returns a malloc'ed string with the full path to
cmdon success, otherwise
whichp()is a predicate function, returns
which("/bin/ps aux")will return
TRUE, provided of course
Pose a question to user, appended with
TRUEfor yes (both
Yare handled) and
FALSEfor everything else.
The following are useful GNU functions, that do not exist on *BSD, and some other platforms.
The following are popular functions and highly useful macros from the *BSD world of UNIX that are sadly missing on Linux.
fparseln(fp, *len, *lineno, delim, flags)
Note: the version of
pidfile()in -lite has been extended to handle it being called multiple times, i.e. to not create multiple
atexit()handlers, and also to export a few internal paths:
__pidfile_path: prefix path, default
_PATH_VARRUN. Notice the trailing slash requirement if you want to override it!
__pidfile_name: full path to PID file , similar to
__progname. See previous section for details.
reallocarray(ptr, nmemb, size)
strlcpy(dst, src, len)
strlcat(dst, src, len)
Niels Provos' famous splay and red-black tree implementation.
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.
./configure make -j5 sudo make install-strip sudo ldconfig
Note: When checking out code from GIT, use ./autogen.sh
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 Finit and released under the MIT/X11 license. Joachim Nilsson later improved on the Finit code base and included pieces of software released under the ISC and BSD licenses. See each respective file for license details.