clens

From ConformalOpenSource
Jump to: navigation, search

clens is a convenience library to aid in porting code from OpenBSD to different operating systems. Operating systems traditionally have different enough APIs that porting code is painful and can litter pretty code with ugly #ifdef goo. In order to keep code readable and drastically reduce the number of #ifdefs needed, clens brings other APIs or missing functions into specific OS "focus". All our code is primarily developed on OpenBSD and clens brings OpenBSD specific calls to other operating systems. As a result, clens is not required when running OpenBSD code.

Please read the code for a more detailed explanation.

Contents

Installation

Navigate to the clens directory and type:

make
sudo make install

Usage Tips

clens is only useful in situations where the source code uses OpenBSD constructs which aren't portable to other operating systems and are provided by clens. A few example functions provided by OpenBSD which aren't available by default on other platforms are strlcat, strlcpy, and arc4random_buf. A few example defines that also exist on OpenBSD but not other platforms are SA_LEN, __dead, and PASS_MAX. clens provides these functions and defines (along with a few others) as necessary per supported platform.

The first step to use clens is to ensure a flag is defined in the Makefiles for non-OpenBSD platforms as well as specifying the clens include path. An example from a GNUmakefile is:

CFLAGS += -I/usr/local/include/clens
CPPFLAGS += -DNEED_LIBCLENS

Once the flag is defined appropriately on the platforms it is required, adding the following code near the top of a source file that contains non-portable constructs provided by clens:

#ifdef NEED_LIBCLENS
#include <clens.h>
#endif

NOTE: If a header file uses non-portable constructs (such as the __dead define or the PASS_MAX define), the same conditional code block above can be used near the top of the header file as well.

Header List

All headers are placed under /usr/local/include/clens, so as the Usage Tips section indicates, the path should be specified via -I to the compiler.

The following header is the main header which defines the necessary constructs on a per-platform basis:

  • <clens.h>

The following headers are made available on a per-platform basis as necessary:

  • <readpassphrase.h>
  • <sys/queue.h>
  • <sys/tree.h>

Constants/Macro List

The following constants/macros are made available on a per-platform basis as necessary:

  • __dead
  • __packed
  • PASS_MAX
  • SA_LEN

Function List

The following functions are made available on a per-platform basis as necessary:

  • arc4random_buf - arc4 random number generator
  • fgetln - get a line from a stream
  • fmt_scaled - format numbers with a human-readable scale
  • fparseln - return the next logical line from a stream
  • scan_scaled - read numbers with a human-readable scale
  • strlcat - size-bounded string concatenation
  • strlcpy - size-bounded string copying
  • strnvis - visually encode characters
  • strtonum - reliably convert string value to an integer
  • timespeccmp - compares two timespec structures

clens Resources