Annotation of embedaddon/pimd/libite/README.md, revision 1.1
1.1 ! misho 1: -lite | Frog DNA, basically
! 2: ===========================
! 3: [![Travis Status][]][Travis]
! 4:
! 5: Libite is a lightweight library of *frog DNA*. It can be used to fill
! 6: the gaps in any dinosaur project. It holds useful functions and macros
! 7: developed by both [Finit][1] and the [OpenBSD][2] project. Most notably
! 8: the string functions: [strlcpy(3)][3], [strlcat(3)][3] and the highly
! 9: useful *BSD [sys/queue.h][4] and [sys/tree.h][7] API's.
! 10:
! 11: Libite is the frog DNA missing in GNU libc. However, -lite does not aim
! 12: to become another [GLIB][5]! One noticeable gap in GLIBC is the missing
! 13: `_SAFE` macros in tje BSD `sys/queue.h` API — highly recommended
! 14: when traversing lists to delete/free nodes.
! 15:
! 16: The code is open sourced under a mix of the [MIT/X11 license][MIT], the
! 17: [ISC license][ISC] used by OpenBSD, and [BSD licenses][BSD], all of them
! 18: are extremely liberal and can be used freely in proprietary software if
! 19: needed.
! 20:
! 21: For an introduction to why Libite happened, and how you can use it, see
! 22: [this blog post][6].
! 23:
! 24:
! 25: Using -lite
! 26: -----------
! 27:
! 28: Libite is by default installed as a library and a set of include files.
! 29: To prevent clashing with include files of the same name -lite employs a
! 30: include file namespace `lite/`, which is recommended to use in your
! 31: applications:
! 32:
! 33: #include <lite/lite.h>
! 34: #include <lite/conio.h>
! 35: #include <lite/queue.h>
! 36: #include <lite/tree.h>
! 37:
! 38: The output from the `pkg-config` tool holds no surprises:
! 39:
! 40: $ pkg-config --libs --static --cflags libite
! 41: -I/usr/local/include -L/usr/local/lib -lite @LTLIBINTL@
! 42:
! 43:
! 44: Helper Macros
! 45: -------------
! 46:
! 47: - `atonum(str)`
! 48:
! 49: Convert string to natural number, works for 32-bit non-negative
! 50: integers. Returns -1 on error. (Uses `strtonum()` internally.)
! 51:
! 52: - `blkdev(dev)`
! 53:
! 54: Create block device
! 55:
! 56: - `chardev(dev)`
! 57:
! 58: Create character device
! 59:
! 60: - `erase(path)`
! 61:
! 62: Erase file/directory with `remove()`. Errors on stderr
! 63:
! 64: - `makedir(path)`
! 65:
! 66: Create directory, like `mkdir()`. Errors on stderr
! 67:
! 68: - `makefifo(path)`
! 69:
! 70: Create a FIFO, like `mkfifo()`. Errors on stderr
! 71:
! 72: - `min(a,b)`/`max(a,b)`
! 73:
! 74: These macros take care to avoid double evaluation.
! 75:
! 76: - `touch(path)`
! 77:
! 78: Create a file, or update mtime. Errors on stderr
! 79:
! 80: - `S_ISEXEC(mode_t m)`
! 81:
! 82: Mysteriously missing from GLIBC
! 83:
! 84: - `ISCLR(word,bit)`
! 85:
! 86: Is bit in (integer) word cleared?
! 87:
! 88: - `ISSET(word,bit)`
! 89:
! 90: Is bit in (integer) word set?
! 91:
! 92: - `ISOTHER(word,bit)`
! 93:
! 94: Is any other bits, except bit, in (integer) word set?
! 95:
! 96: - `SETBIT(word,bit)`
! 97:
! 98: Set bit in (integer) word.
! 99:
! 100: - `CLRBIT(word,bit)`
! 101:
! 102: Clear bit in (integer) word.
! 103:
! 104: - `NELEMS(array)`
! 105:
! 106: Returns the number of elements in an array. From the great book, The
! 107: Practice of Programming, by Kernighan and Pike.
! 108:
! 109: - `UNUSED(var)`
! 110:
! 111: Shorter and more readable version of `var __attribute__ ((unused))`
! 112:
! 113:
! 114: Generic Functions
! 115: -----------------
! 116:
! 117: - `chomp(str)`
! 118:
! 119: Perl like chomp function, chop off last char if newline.
! 120:
! 121: - `copyfile(src, dst, len, symlink)`
! 122:
! 123: Like the shell `cp(1)` and `dd(1),` can also create symlinks.
! 124:
! 125: - `dir(dir, ext, filter, list, strip)`
! 126:
! 127: Wrapper for `scandir()` with optional filter. Returns a list of
! 128: names: files and directories that must be freed after use. See
! 129: the unit test at the bottom for an example.
! 130:
! 131: - `fcopyfile(src, dst)`
! 132:
! 133: Like `copyfile()` but uses already open `FILE *` pointers. Copies
! 134: from current file positions to current file positions until EOF.
! 135:
! 136: - `fexist(file)`
! 137:
! 138: Check for the existance of a file, returns True(1) or False(0).
! 139:
! 140: - `fisdir(path)`
! 141:
! 142: Check for the existance of a directory, returns True(1) or False(0).
! 143:
! 144: - `fmode(file)`
! 145:
! 146: Returns the `mode_t` bits of a file or directory.
! 147:
! 148: - `fsendfile(src, dst, len)`
! 149:
! 150: Copy data between file streams, very similar to `fcopyfile()`, but
! 151: `dst` is allowed to be `NULL` to be able to read and discard `len`
! 152: bytes from `src`.
! 153:
! 154: - `ifconfig(ifname, addr, mask, up)`
! 155:
! 156: Basic ifconfig like operations on an interface. Only supports IPv4
! 157: adresses. Note that mask is not CIDR notation.
! 158:
! 159: - `lfopen(file, sep)`, `lfclose(lf)`
! 160:
! 161: API for parsing UNIX style configuration files like `/etc/protocols`
! 162: and `/etc/services`.
! 163:
! 164: - `lftok(lf)`
! 165:
! 166: Read tokens, delimeted by `sep`, from file opened with `lfopen()`.
! 167:
! 168: - `lfgetkey(lf, key)`
! 169:
! 170: Find `key` in file opened with `lfopen()`, return value/argument.
! 171:
! 172: - `lfgetint(lf, key)`
! 173:
! 174: Wrapper for `lfgetkey()`, returns positive integer value to `key`,
! 175: or `-1` if `key` is not found.
! 176:
! 177: - `fgetint(file, sep, key)`
! 178:
! 179: Wrapper for `lfopen()`, `lfgetint()`, and `lfclose()`. Useful for
! 180: when only reading a single `key` from a file.
! 181:
! 182: - `makepath(dir)`
! 183:
! 184: Create all components of the specified directory.
! 185:
! 186: - `mkpath(dir, mode)`
! 187:
! 188: Like `makepath()`, but also takes a `mode_t` permission mode argument.
! 189:
! 190: - `movefile(src, dst)`
! 191:
! 192: Like `copyfile()`, but renames `src` to `dst`, or recreates symlink
! 193: with the `dst` name. On successful operation the source is removed
! 194: and the function returns POSIX OK (0).
! 195:
! 196: - `pidfile(basename)`
! 197:
! 198: Create a daemon PID file in `_PATH_VARRUN` using either `basename` or,
! 199: if `basename` is `NULL`, `__progname`. The resulting file name is
! 200: available to the user as a read-only pointer:
! 201:
! 202: extern char *__pidfile_name;
! 203:
! 204: Use this function to create a PID file for your daemon when it is
! 205: ready to receive signals. A client application may poll for the
! 206: existence of this file, so make sure to have your signal handlers
! 207: properly setup before calling this function.
! 208:
! 209: The pidfile is removed when the program exits, using an `atexit()`
! 210: handler. However, depending on how the program terminates the file
! 211: may still exist even though the program is no longer running. This
! 212: is only a problem for clients.
! 213:
! 214: Calling this function multiple times updates the mtime of the file.
! 215: Only one `atexit()` handler is created, regardless of the amount of
! 216: times the function is called.
! 217:
! 218: See below for link to OpenBSD man page.
! 219:
! 220: - `pidfile_read(pidfile)`
! 221:
! 222: Read PID from pid file created by `pidfile()`.
! 223:
! 224: - `pidfile_signal(pidfile, signal)`
! 225:
! 226: Send signal to PID found in pid file created by `pidfile()`.
! 227:
! 228: - `progress(percent, max_width)`
! 229:
! 230: Simple ASCII progress bar with a spinner. Start it with `percent=0`
! 231: and set the `max_width=chars` to indicate width of the progress bar.
! 232: Called multiple times with the same percentage value cause spinner to
! 233: spin.
! 234:
! 235: - `rsync(src, dst, delete, *filter())`
! 236:
! 237: Very simple `rsync()` to copy files files and directories
! 238: recursively.
! 239:
! 240: - `tempfile()`
! 241:
! 242: Secure replacement for `tmpfile()`. Creates an invisible temporary
! 243: file in `/tmp` that is removed when the returned `FILE` pointer is
! 244: closed.
! 245:
! 246: **Note:** Requires Linux v3.11, or later, will fall back to the old
! 247: and unsafe `tmpfile()` on older systems.
! 248:
! 249: - `tree(path, show_perms)`
! 250:
! 251: Very simple `/bin/tree` replacement. Draw ASCII tree of `path`, with
! 252: optional listing of file and directory permissions if `show_perms` is
! 253: set. The `path` argument should be a directory.
! 254:
! 255:
! 256: OpenBSD Functions
! 257: -----------------
! 258:
! 259: The following are popular OpenBSD functions and highly useful macros.
! 260:
! 261: - `pidfile(basename)`
! 262:
! 263: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/pidfile.3
! 264:
! 265: **Note:** this version of `pidfile()` has been extended to handle it
! 266: being called multiple times, and also to export the path to the PID
! 267: file `__pidfile_name`, similar to `__progname`. See previous section
! 268: for details.
! 269:
! 270: - `strlcpy(dst, src, len)`
! 271:
! 272: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/strlcpy.3
! 273:
! 274: - `strlcat(dst, src, len)`
! 275:
! 276: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/strlcat.3
! 277:
! 278: - `strtonum()`
! 279:
! 280: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/strtonum.3
! 281:
! 282: - `sys/queue.h` API
! 283:
! 284: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/LIST_EMPTY.3
! 285:
! 286: - `sys/tree.h` API
! 287:
! 288: Niels Provos' famous splay and red-black tree implementation.
! 289:
! 290: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/SPLAY_FOREACH.3
! 291:
! 292:
! 293: Build & Install
! 294: ---------------
! 295:
! 296: The library is built for and developed on GNU/Linux systems as a light
! 297: weight utility library. Libite (LITE) employs the de facto standard GNU
! 298: configure and build system:
! 299:
! 300: ./configure
! 301: make all
! 302: make install
! 303:
! 304:
! 305: TODO
! 306: ----
! 307:
! 308: - Improve documentation, possibly use kdoc or gdoc2 to generate docs from API.
! 309: - Continuously, update OpenBSD functions/macros.
! 310:
! 311: [1]: https://github.com/troglobit/finit
! 312: [2]: http://www.openbsd.org/
! 313: [3]: http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy
! 314: [4]: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/LIST_EMPTY.3
! 315: [5]: https://developer.gnome.org/glib/
! 316: [6]: http://troglobit.com/blog/2015/07/02/howto-using-lite-with-a-git-based-application/
! 317: [7]: http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/man3/SPLAY_FOREACH.3
! 318: [MIT]: https://en.wikipedia.org/wiki/MIT_License
! 319: [ISC]: https://en.wikipedia.org/wiki/ISC_license
! 320: [BSD]: https://en.wikipedia.org/wiki/BSD_licenses
! 321: [Travis]: https://travis-ci.org/troglobit/libite
! 322: [Travis Status]: https://travis-ci.org/troglobit/libite.png?branch=master
! 323:
! 324: <!--
! 325: -- Local Variables:
! 326: -- mode: markdown
! 327: -- End:
! 328: -->
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README.md CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pimd / libite