Most programmers are first introduced to linked lists in a classroom setting: a small struct with a next pointer, perhaps followed by a prev pointer, and a few insertion and deletion functions written by the professor on a whiteboard. Those examples are useful, but they are not how the idea becomes real-world-truly-interesting. To see this, study a linked list in a real operating system - albeit a dead one.

The OpenSolaris kernel offers exactly that: a generic linked list implementation that is compact, carefully crafted, and revealing. It lives in usr/src/uts/common/sys/list_impl.h and usr/src/uts/common/os/list.c, and it truly rewards slow reading.

The first surprise is that the list is intrusive. In a textbook implementation, the list node often wraps the payload: a node contains data and links. Here, the payload object only contains the links. The fundamental node type is only this:

struct list_node {

struct list_node *list_next;

struct list_node *list_prev;

};

And the list itself looks like this:

struct list {

size_t list_size;

size_t list_offset;

struct list_node list_head;

};

That list_offset field is the key to the whole design. It tells the list code where, inside a larger object, the embedded list_node lives. This allows the same implementation to manage lists of many different object types without allocating wrapper nodes. In kernel code, that is an excellent trade: fewer allocations, less indirection, and tighter control over memory layout.

Once you understand that design, two small macros become the bridge between “user object” and “list node”:

#define list_d2l(a, obj) ((list_node_t *)(((char *)obj) + (a)->list_offset))

#define list_object(a, node) ((void *)(((char *)node) - (a)->list_offset))

The first takes an object and finds its embedded link field. The second takes a link field and reconstructs the object that contains it. This is a classic systems-programming move: keep the abstraction generic, but make the cost explicit and low.

The second thing worth noticing is the use of a sentinel head node. When the list is created, the head’s next and prev pointers both point back to the head itself:

list->list_head.list_next = list->list_head.list_prev = &list->list_head;

This means an empty list is represented not by a NULL, but by a tiny circular structure. That choice simplifies the rest of the code - insertion and removal do not need separate “empty list” logic and head & tail operations become ordinary pointer updates around the sentinel.

The insertion code is a nice example of how much clarity can fit in a few lines. Here is the essence of inserting after a node:

lnew->list_prev = node;

lnew->list_next = node->list_next;

node->list_next->list_prev = lnew;

node->list_next = lnew;

This is the kind of source code worth reading - it is short, but it encodes a structural invariant: every forward link must have a matching backward link, and every update must preserve that symmetry. There are only four assignments.

Removal is equally direct:

node->list_prev->list_next = node->list_next;

node->list_next->list_prev = node->list_prev;

node->list_next = node->list_prev = NULL;

The last line is especially telling. The implementation deliberately clears the removed node’s pointers. That is not strictly necessary for the list to function, but it is good engineering practice. A removed node is now visibly inactive. If somebody tries to remove it again, or mistakes it for a live element - the bug would be easier to detect.

Traversal is built on the same sentinel idea. Internally, the list is circular. Externally, the API presents a simpler interface: once iteration reaches the head again, it returns NULL. So client code gets the clean, familiar form:

for (p = list_head(listp); p != NULL; p = list_next(listp, p)) {/* use p */}

That pattern appears in real OpenSolaris code. In pci_boot.c, for example, the kernel walks a list of cached PCI unit-address entries using list_head() and list_next(). This is such simple abstraction!

What, then, does this implementation teach us about linked lists?

First, linked lists are less about the shape of a node than about the invariants that govern mutation. Good list code makes those invariants easy to see and hard to violate.

Second, production systems code often chooses intrusive structures because they are efficient and flexible. A beginner may think of this as an advanced trick but in reality, it is an expression of a basic principle: put the machinery where it costs the least.

Third, elegance in low-level code often means removing special cases. The sentinel node is not decorative. It exists because it simplifies every operation around it.

And finally, reading code like this reminds us that “data structures” are not just academic exercises. In a kernel, a linked list is not there to illustrate a concept. It is there because someone needed a generic, reusable, predictable mechanism, and this was the design that best satisfied those constraints.

If you want to get better at reading systems software, this is an ideal specimen. Start with the structures. Then read the conversion macros. Then insertion, removal, and traversal. With this you learn more than just how a linked list works - you get an intuition of how experienced engineers turn a familiar idea into robust infrastructure.

I found the answer in the "Writing in the Age of Distraction" article published in the January 2009 issue of Locus magazine. Turns out Cory is so productive not despite of, but because of the choice of minimalist tooling. In the article Cory advises other writers: "Kill your word-processor" and "use a text-editor, like vi, Emacs, TextPad, BBEdit, Gedit, KWrite or any of a host of editors."

Doctorow recommends these text editors because they are "some of the most venerable, reliable, powerful tools in the history of software (since they're at the core of all other software) and they have almost no distracting features — but they do have powerful search-and-replace functions."

Now that I understand the principles behind Cory’s preference for Gedit, I wondered if there is some other robust, OSS, UNIX tool out there that is even more minimal than Gedit.

ed came to mind. As it is well understood, ed is the standard text editor. Presumably, if you want to call your operating system a UNIX, you need to conform to the Single UNIX Specification (SUS). That would oblige you to include some version of ed in your Linux distribution too. And so ed runs on everything — even IBM zOS.

ed was created by Ken Thompson in 1969 at AT&T Bell Labs. The first version was written in assembler. Later versions of ed were implemented in C.

In 1993 Andrew Moore was inspired by the “ed algorithm” as described in Brian W. Kernighan and P. J. Plauger's book "Software Tools in Pascal" (Addison-Wesley, 1981) recreated the editor within the GNU ecosystem. The 1993 version is the one Apple includes in macOS as well. The 1993 version by Andrew Moore is what we'll explore here.

Taking a cursory look at the source code - the editor is essentially 8 fairly small C files:

1. buf.c - 6,682 bytes

2. cbc.c - 10,066 bytes

3. glbl.c - 6,107 bytes

4. io.c - 8,486 bytes

5. main.c - 33,050 bytes

6. re.c - 3,721 bytes

7. sub.c - 6,859 bytes

8. undo.c - 4,313 bytes

Before we jump into main.c, which is the largest one (33K) let's go over a few ed sample commands to get a feel of how this works. Much like vi, which originates from ed, ed has 2 modes: command and input. Once launched (ed article.txt to open a file) it is in command mode.

1. 1p — prints the first line of the opened file

2. 1i — inserts a new first line

3. . — when in edit mode completes the text insertion

4. ,n — prints all lines by prepending a line number

5. 2s/foo/bar/g — replace foo with bar on the second line

Classic C opening:

/* ed: line editor */
int
main(int argc, char *argv[])
{

The comments are fantastic. The clarity of the comments rivals that of Lion's Commentary. Here are the declarations of global variables as an example:

/* static buffers */
char stdinbuf[1];		          /* stdin buffer */
char *shcmd;			/* shell command buffer */
int shcmdsz;			/* shell command buffer size */
int shcmdi;			/* shell command buffer index */
char *ibuf;			/* ed command-line buffer */
int ibufsz;			/* ed command-line buffer size */
char *ibufp;			/* pointer to ed command-line buffer */

/* global flags */
int des = 0;			/* if set, use crypt(3) for i/o */
...
int sigactive = 0;		/* if set, signal handlers are enabled */
int posixly_correct = 0;	/* if set, POSIX behavior as per */
/* http://www.opengroup.org/onlinepubs/009695399/utilities/ed.html */

...
int lineno;			/* script line number */
const char *prompt;		/* command-line prompt */
const char *dps = "*";		/* default command-line prompt */

One interesting find — early into main() we see the top: label. And of course further down in the source is the "goto top;" statement. Many of us have been taught that GOTO should not be used. This started in 1968 with a letter by Edsger Dijkstra called "Go-to statement considered harmful". But goto top; is here nevertheless. It seems fairly safe and unambiguous as it is used in the context of parsing command line arguments.

After the buffer is initialized and the file is checked, there comes the infinite loop:

for (;;) {

Within the loop there is the inevitable invocation of exec_command().

And as the comment indicates - this is where the command we have given ed is executed. One such example would be ",n", which asks ed to print all lines with a leading line number.

The exec_command() function is one giant case statement. What does ed do when we enter ",n"? Let's search for "case 'n':" in the code:

case 'n':
	if (check_addr_range(current_addr, current_addr) < 0)
		return ERR;
	GET_COMMAND_SUFFIX();
	if (display_lines(first_addr, second_addr, gflag | GNP) < 0)
		return ERR;
	gflag = 0;
	break;

The essence here seems to be the display_lines() function. Presumably by the time we detected the 'n' command, we had already collected the first_addr and second_addr, so now we know the begin and end lines of the range we want to print with line numbers.

The function display_lines() is tiny and a well structured one:

/* display_lines: print a range of lines to stdout */
int
display_lines(long from, long to, int gflag)
{
	line_t *bp;
	line_t *ep;
	char *s;
	if (!from) {
		errmsg = "invalid address";
		return ERR;
	}
	ep = get_addressed_line_node(INC_MOD(to, addr_last));
	bp = get_addressed_line_node(from);
	for (; bp != ep; bp = bp->q_forw) {
		if ((s = get_sbuf_line(bp)) == NULL)
			return ERR;
		if (put_tty_line(s, bp->len, current_addr = from++, gflag) < 0)
			return ERR;
	}
	return 0;
}

The function is given a from and to lines. It will print the range of lines between to and from and will show the line number for each one. In my case, when I entered ",n", ed showed me the full contents of my test file:

,n
1       this is the new first line
2       this was the first line, but NOW it is the second one
3       two
4       three

Despite the excellent comments, in typical C fashion, we have some extremely short variable names. I am not a fan of single or even double-letter variable names. In some cases, when the pattern is well known it is acceptable, for example “for (i=0; ...” But in the case of bp and ep — we are left guessing what these may mean. Since bp is a struct for the "from" line and ep for the "to" line we could assume these perhaps mean:

• bp = Beginning Point (from)

• ep = Eng Point (to)

The loop "for (; bp != ep; bp = bp->q_forw) {" then is going to move the beginning point forward until it overlaps with the end point. That makes sense as we want to start with from and print all the lines until to.

The function "s = get_sbuf_line(bp)" will fetch a pointer to a null terminated string for each line we 'step' on. And put_tty_line(s...) would print it.

Let's take a look at the printer:

/* put_tty_line: print text to stdout */
int
put_tty_line(const char *s, int l, long n, int gflag)
{

This is defined in the io.c file (we were in main.c until now).

The function put_tty_line() is generic and used by a few ed commands. So when we use ',n' - the first if statement will know that this is an 'n' and not just a 'p' (print without line numbers) and will prepend the line number for each line:

		printf("%ld\t", n);

The loop "for (; l--; s++) {" is where the line's characters are printed. We don't need a loop counter or index variable (i) here. Because of the single-letter variable, it is not crystal clear, but "l" in this case is the length of the current line we are working on. So our loop will continue as long as the value of l is greater than 0. The -- operator decrements l by 1 after each iteration, which is actually the output of a character to the TTY.

The several indentation levels of if statements will perform some minimal sanitation to ensure we don't print control characters or stuff our TTY can't handle and will eventually resort to putchar().

And putchar() is a C library function, which writes a character specified by the specified by the "int char" argument char to stdout.

The function will also make sure that we don't go beyond the 72 columns as defined back in main.c

int cols = 72;                          /* wrap column */

There is so much more interesting and well written code in this tiny repo. The ed editor is truly a masterpiece. We will come back to this source code when we examine some of the modern editors and look at how these have been influenced by ed.

Happy Code Reading!

One winter day in the late 1980s my parents dropped me (a kindergartener) off at my grandparents’ house in southern Bulgaria. Left me and one of these:

This plastic Pravetz box came with a book on BASIC - full of short snippets of sample code. I had fun trying to type out various short LISTings from the book.

The best part of the Pravetz computer was - the first thing you saw when you turned the box on - the name of the machine (ПРАВЕЦ) and a cursor: ]█

The blinking green box invited you to type out your first BASIC command.

Jumping from the late 1980’s to July 2020 when I saw a tweet from Sal Collora, who had a freshly refurbished a working Commodore 64…

I got an opportunity to rekindle that old feeling of typing out my first line of source code - so I embraced it. My Commodore 64 arrived, I plugged it in, turned it on and there it was - the BASIC prompt again.

It is so incredible - flip the switch and you are dropped in a BASIC world. All you have at your disposal are 71 keywords. It seem like a tiny and suffocating space and yet it is a fascinating world of endless exploration. Here is one line of code, my favorite, to prove this with an example:

10 PRINT CHR$(205.5+RND(1)); : GOTO 10

In the 1980s this extremely concise BASIC program appeared in so many printed sources - it became a cultural phenomenon. Nick Montfort and colleagues wrote an incredible book on the topic.

While I do aspire to analyze word by word every snippet of code I post here, and I intend to do this weekly, the 10 PRINT has already been elaborately studied in the 10 PRINT book (PDF).

Very peculiar (to me) is the 205.5 number in the code. This number plus a random float between 0 and 1 results in printing either PETSCII character 205 (\) or 206 (/):

The maze with the 205.5 and a random sub-1 float would look like this:

But my second-grade daughter wanted to see what happens if the numbers change, so she tried tweaking the 205.5 to all sorts of other numbers. Here is the same program with 215.5 instead:

The instant feedback from changing a number and then RUNning the program gave my daughter hours of entertainment, exploring Commodore 64 character sets. This reminded me of the great times I had exploring all the things the Pravetz 8c can do.

This is a blog about reading code and we did just that today. This is one simple line of BASIC code but it sparked the imagination of many kids and adults who in turn created great software. This great software is what we will examine scrutinously in this forum here!

Tune in and subscribe for more of our code reading adventures weekly!