libsl is an extremely small library used to write better and clearer C programs. The code was created by the suckless community, a small group of C hackers and developers creating powerful yet simple programs for Linux designed to be lightweight, configurable, and easier to maintain then the many other unnecessarily bloated alternatives. You can read more about their philosophy on their website. Some of their most notable projects include dwm, dmenu, st, and surf.

libsl is composed of tiny C99 source and headers files designed to be simply copied into a project’s source tree. This allows the library to be easily used and easily modified to fit every project’s need.

All of libsl is protected under the MIT license, allowing you to use it in your own projects with little strings attached. See LICENSE in the source tree for more.


One of the most utilized and most important files in libsl is arg.h, a C header designed to easily interpret short options from the command line. This removes the necessity to copy complex boiler plate or clunky libraries to simply see if an option has been supplied by the user. While arg.h does not support long options (--option vs -o), if your project’s CLI is relatively straight forward it is a great, simple, and lightweight method to quickly parse short options in your C code.

To start reading short options simply use the macro ARGBEGIN followed by a { in your C program’s main function, don’t forget to #include "arg.h" at the top of the file. This macro loops through all the command line arguments and finds the short option (beginning with a single -) and allows you to select one in a switch statement by using case 'a':, where a can be any character for the desired option.

arg.h also defines other macros to read data in the ARGBEGIN block. One example is ARGC() which is defined to ARGBEGIN’s internal variable argc_, the character for the short option currently being interpreted.

ARGF() is another useful macro to get an argument after an option. For example if a program prog is run as prog -s string then ARGF() in the s case will return string as a C string. This can also be converted to a number through a function such as atoi. A similar macro EARGF(x) can also run the supplied function upon an error. It is common to define a usage() function in suckless projects such as the one below.

	die("usage: %s [-ab] [-c STR] [-d STR] [-n NUM | -NUM]", argv0);

die() is a function in libsl defined in util.c, see the section below for more.

arg.h also defines a string, argv0, which is set to the program’s name, equivalent to argv[0], but global allowing it to be used throughout your code, like in the usage message above.

In this example EARGF(usage()) would display usage info on an error reading the next string.

While ARGF() with atoi() can be used to get a number from given arguments, it is often faster to use the -NUM format (eg prog -4 to get the number 4 instead of prog -n 4). In order to achieve this I have added my own macros to arg.h that can be used.

/* handles -NUM syntax */
#define ARGNUM case '0':\
               case '1':\
               case '2':\
               case '3':\
               case '4':\
               case '5':\
               case '6':\
               case '7':\
               case '8':\
               case '9'

/* get option number */
#define ARGNUMF()	(brk_ = 1, atoi(argv[0]))

The first is ARGNUM which is used in replace of a case statement in the ARG block (eg case 'n': becomes ARGNUM:). Inside of this case replacement ARGNUMF() is used to get the number given by the argument supplied by the user. These macros, while only needing to be defined for 1-9, work on any number over 10 as well.

After running through all the options you want—remembering to use break after each one, possibly including a default in case an argument given is not supported—ARGBEGIN and the curly bracket we opened need to be closed via } ARGEND. ARGEND is essentially just closing all the brackets ARGBEGIN opened, not counting the one we placed.

A complete ARG block example is shown below, don’t forget that it needs to be placed in inside the int main(int argc, char *argv[]) function.

case 'a':
	printf("option a selected\n");
case 'b':
	printf("option b also runs if your not careful\n");
case 'c':
	printf("options can also have arguments: %s\n", ARGF());
case 'd':
	printf("support for error messages: %s\n", EARGF(usage()));
case 'n':
	printf("they can also be numbers: %d\n", atoi(EARGF(usage())));
	printf("or in this format: %d\n", ARGNUMF());
case 'v':
	verbose++; /* define before ARGBEGIN block */
	printf("options can also be repeated: %d\n", verbose);

Note that arg.h modifies argv and argc. If, for example, after parsing the arguments you now want to read any strings after, such as file names, argv[0] is the first argument after the valid options. So if prog -s option filename anotherfile is used, the s case in ARGBEGIN is run with the argument option, then argv[0] will be equal to filename, argv[1] to anotherfile, etc.


The next file in libsl is util.c. This file defines many general purpose C functions used throughout different projects.

One function found here which is common in many C projects, including Linux, is die(). This utility takes a formatted string, adds a newline at the end, and prints it to stderr before exit()ing with a return value of 1. This is useful for writing simple and clean error messages which need to quit the program. die() is used above in the usage() example as well as the quick examples below.

struct MyData data;
data->str = init_str();
if (!data->str || !strcmp(data->str, ""))
	die("%s: error: could not init data->str", argv0);
int strlen = 20;
char *str;
if (!(str = calloc(strlen, sizeof(char))))
	die("fatal: could not calloc() %u bytes", strlen * sizeof(char));

As well as formatting the output similar to printf(), libsl’s die() also supports automatic error messages for functions which set the C global errno. If the string given ends in a colon (:), die() will append a space and the error message thrown by a called function with errno support. Thus the above calloc example can be replaced with the more adaptive:

int strlen = 20;
char *str;
if (!(str = calloc(strlen, sizeof(char))))
	die("calloc:"); /* example error: "calloc: out of memory" */

The above example is the bases for another useful function util defines, ecalloc(). This new function makes sure the pointer allocated by calloc is not NULL, which indicates an error occurred. Using this new wrapper we can replace the example above with the following.

int strlen = 20;
char *str = ecalloc(strlen, sizeof(char));

This function can also be duplicated for other similar functions such as realloc(), malloc(), strdup(), etc. A new example erealloc() function is displayed below.

void *
erealloc(void *p, size_t size)
	if (!(p = realloc(p, size)))

	return p;


The header, as well as defining the previous functions, creates some useful macros.

Two macros which are often copy and pasted between projects and files is MAX() and MIN(). They are fairly simple, two integers are given as arguments and the biggest or smallest one is returned respectively.

#define MAX(A, B)   ((A) > (B) ? (A) : (B))
#define MIN(A, B)   ((A) < (B) ? (A) : (B))
MAX(4, 8);     /* => 8   */
MIN(-38, -18); /* => -38 */
MAX(10, -47);  /* => 10  */

In a similar vain BETWEEN() returns whether the first integer supplied is between the next two given integers.

#define BETWEEN(X, A, B)   ((A) <= (X) && (X) <= (B))
BETWEEN(4, -8, 12); /* => 1 (true)  */
BETWEEN(9, 20, 67); /* => 0 (flase) */

LEN() is also often defined here, it is used to return the size of an array.

#define LEN(X)            (sizeof(X) / sizeof((X)[0]))


drw.c and its header drw.h are used as an X interfaced for making basic graphical programs, for example dmenu. An in depth overview of the many functions and typedefs offered in this file is coming soon as its own post.


I hope this post has be beneficial and will help you create more elegant and cleaner code in C. For other projects putting this philosophy into practice checkout some of my projects, the suckless git repo, and their other recommended projects page.