Lev Lazinskiy

Reading every manpage

I want to read every man page in stock OpenBSD. I have no idea why, but I am sure that I going to learn something. You can follow along here.

There is a man page for man which tells us where everything is located along with the general top level sections.

1         General commands (tools and utilities).
2         System calls and error numbers.
3         Library functions.
3p        perl(1) programmer's reference guide.
4         Device drivers.
5         File formats.
6         Games.
7         Miscellaneous information.
8         System maintenance and operation commands.
9         Kernel internals.

man1 - General Commands

Starting in /usr/share/man/man1 in alphabetical order.

Fri, 6 Dec 2019 21:23:00 -0800

Internals.1

This page is a part of the Perl Programmers Reference Guide, I am bit confused about why its in man1 since man tells us that all of the perl things are supposed to be in 3p. I asked about this on mastadon.

I found this little blurb interesting.

In theory these routines were not and are not intended to be used outside of the perl core, and are subject to change and removal at any time.

In practice people have come to depend on these over the years, despite being historically undocumented, so we will provide some level of forward compatibility for some time.

PACKAGING.1

Another page about Perl Programmers Reference. This short page is a reference that documents some best practices in packaging perl itself.

acme-client.1

I’ve read this page several times since I’ve been using acme-client to set up HTTPS on all of my sites. This is the first man page in the list that properly reference other man pages. I am fighting the temptation to follow the rabbit hole.

I was not aware that ACME is an RFC 8555, I missed this part since when I read this page before I tended to skip to the parts that I needed. Once I am done here, I am going to go read all of the RFC’s.

addr2line.1

I am not familiar with this program at all. It is a GNU development tool that converts addresses into file names and line numbers. Address in this context refers to:

Given an address in an executable or an offset in a section of a relocatable object

I read this several times and I am still not 100% sure what an address is. I do, however, know what a.out is. The best way to figure out what this thing does is to try to use it.

I made a “Hello World” program in C, compiled it, and then ran addr2line a.out which resulted in this output:

stock# addr2line a.out
??:0

The man page tells us that ??:0 means that the file name or function

can not be determined (??) and the line number can also not be determined (:0).

I am still confused. Now I just have to know what the hell this thing does. I am temporarily giving up, but I learned at this program is a part of GNU binary utilities.

amd64/fdformat.1

This command formats floppy disks. I am not sure if anyone has used this thing in the last decade, but here it is.

apply.1

I have never used this command, but it seems interesting. It allows you to “apply a command to a set of arguments”. At first glace this reminds me of python’s map function and it appears to work the same way.

Sat Dec 7 14:37:23 2019

apropos.1

I think this is my all time favorite Unix command. apropos allows you to search all of the man pages for various things. Man pages are very useful, but if you don’t even know exactly which page you are looking for, this is a great place to start.

Here I learned that whatis is a synonym for apropos -f (which searches for man page names only).

I also learned that you can use logical operators such as -a (and) and -o (or) when writing your search terms. All of my searches with this tool have been very basic, so this is great to know.

You can also use macro keys to perform a deeper search such as searching for specific functions.

One of the most useful sections inside of man pages is the EXAMPLES section. I usually just glance over these, but since I am reading these with intent I tried out all of the examples here just to see what was possible.

This is the first man page that I’ve seen to explicitly reference the POSIX specification which is a whole other can of worms that I’d like to dig into later.

ar.1

This is another part of the GNU binutils. This program creates, modifies, and extracts from archives. I am not exactly sure what the difference between ar and tar are, but I’ll figure this out a bit later.

Also, there are no EXAMPLES in this man page, and I think it might be worth adding some.

arch.1

This is a handy utility that prints out the architecture type.

as.1

as is the portable GNU assembler, it is also a part of GNU binutils. By comparison to other pages so far, this one is pretty meaty. To illustrate this point, here what the “synopsis” looks like.

as [-a[cdhlns][=file]] [--alternate] [-D]
[--defsym sym=val] [-f] [-g] [--gstabs]
[--gstabs+] [--gdwarf-2] [--help] [-I dir] [-J]
[-K] [-L] [--listing-lhs-width=NUM]
[--listing-lhs-width2=NUM] [--listing-rhs-width=NUM]
[--listing-cont-lines=NUM] [--keep-locals] [-o
objfile] [-R] [--reduce-memory-overheads] [--statistics]
[-v] [-version] [--version] [-W] [--warn]
[--fatal-warnings] [-w] [-x] [-Z] [@FILE]
[--target-help] [target-options]
[--|files ...]

In a nutshell:

as is primarily intended to assemble the output of the GNU C compiler “gcc” for use by the linker “ld”.

at.1

This is another new command to me. I’ve never heard of it, but it appears to be related to performing batch processing. This is pretty interesting since it allows you to either perform a task at a specific time or, even more interestingly, when the system load allows it.

This appears to somehow be related to cron, but I am not quite sure how just yet.

I got some great feedback about this on Mastadon.

One note: ‘at’ isn’t related to cron at all, it has its own demon: atd , and its purpose is “deferred” execution - your commands get executed at a specified later time (but just once)

Thank you @guntbert for the comments.

atq.1

This command is complementary to the previous one, where it displays all of the jobs in the at(1) queue.

atrm.1

This command is also complementary to at(1), it removes jobs from at.

aucat.1

This program seems interesting, it allows you to manipulate audio files.

audioctl.1

This is a utility that allows you to work with audio driver variables.

awk.1

This is a very beefy man page since awk is a programming language that is specifically good at “pattern-directed scanning and processing”.

I’ve only ever seen and briefly used awk “one-liners”, I am looking forward to digging in a bit deeper and seeing what I can hack together with this powerful language.

banner.1

This is a fun, random, use-case-less program that prints out strings in large letters on a terminal using “#”.

 #    #   ####   #    #  ######  ######  #####    ####
 #    #  #    #  #    #      #   #       #    #  #
 #    #  #    #  #    #     #    #####   #    #   ####
 # ## #  #    #  # ## #    #     #       #####        #
 ##  ##  #    #  ##  ##   #      #       #   #   #    #
 #    #   ####   #    #  ######  ######  #    #   ####

Sun Dec 8 22:45:24 2019

basename.1

This is a very handy command, especially when used in a script working with files or urls. I’ve used this plenty of times, but ultimately it allows you to easily find the base name of file.

For example:

$ basename /home/levlaz/blog
blog

$ basename https://dev.levlaz.org/blurbs/basename.html
basename.html

bc.1

I’ve heard of this program, but never used it. It is an “arbitrary-precision arithmetic language and calculator”.

The most interesting thing I was the reference to the file that defines some common math functions /usr/share/misc/bc.library using the bc language itself. For example this is what the s(x) sine function looks like:

define s(x) {
	auto a, b, c, s, t, y, p, n, i, r
	r = ibase
	ibase = A
	t = scale
	y = x/.7853
	s = t + length(y) - scale(y)
	if (s < t) s = t
	scale = s
	p = a(1)

	scale = 0
	if (x >= 0) n = (x/(2*p) + 1)/2
	if (x < 0) n = (x/(2*p) - 1)/2
	x = x - 4*n*p
	if (n % 2 != 0) x = -x

	scale = t + length(1.2*t) - scale(1.2*t)
	y = -x*x
	a = x
	b = 1
	s = x
	for (i =3 ; 1 == 1; i = i + 2) {
		a = a*y
		b = b*i*(i - 1)
		c = a/b
		if (c == 0) {
			scale = t
			ibase = r
			return (s/1)
		}
		s = s + c
	}
}

It is fascinating to see what the algorithm for calculating sin looks like.

biff.1

Wow.

People who know me, know that I detest desktop notifications. I was surprised and curious to see that this program is essentially that. Except it was written a very long time ago (appeared in 4.0BSD) and only notifies you about mail (in your terminal session).

Mon Dec 9 23:37:46 2019

c++.1

This is the clang c++ compiler. The man page shown is for clang itself. This is a really cool man page because it provides you with some interesting insights into how gets compiled, assembled, and linked.

This program also includes a static analyzer. Similar to other build tools there are various stages to turning C++ code into an executable binary. The DESCRIPTION of this man page does a wonderful job explaining what the process looks like.

I also learned about Objective C++ for the very first time thanks to this manpage.

c++filt.1

This program, also a part of GNU binutils, allows you to “demangle” C++ and Java symbols. This has to do with name mangling.

Interesting note in this man page.

MS-DOS does not allow “+” characters in file names, so on MS-DOS this program is called CXXFILT.

cal.1

This is a neat program that draws a calendar in your terminal as such:

   December 2019
Su Mo Tu We Th Fr Sa
 1  2  3  4  5  6  7
 8  9 10 11 12 13 14
15 16 17 18 19 20 21
22 23 24 25 26 27 28
29 30 31            

You can also get the calendar for any previous date. I was born in June 1988 so I could look at this:

asus$ cal 6 1988
     June 1988
Su Mo Tu We Th Fr Sa
          1  2  3  4
 5  6  7  8  9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30      

calendar.1

This is a built in reminder service. It looks for a file called calendar and shows lines that begin with today’s date or tomorrow’s. It’s pretty neat.

You can add reminders for specific days and there are also a lot of built-in calendars which show you interesting information about various dates.

For example you can #include <calendar.openbsd> to see information about BSD related events.

asus$ head -n 20 /usr/share/calendar/calendar.openbsd 
/*
 * OpenBSD-related dates to celebrate
 *
 * $OpenBSD: calendar.openbsd,v 1.41 2019/01/30 07:24:53 bentley Exp $
 */

#ifndef _calendar_openbsd_
#define _calendar_openbsd_

Jan 06	IPF gets integrated into the OpenBSD kernel, 1996
Jan 06	NRL IPv6 addition to OpenBSD, 1999
Jan 09	n2k10: Network hackathon, Melbourne, Australia, 17 developers,
2010
Jan 13	n2k13: Network hackathon, Dunedin, New Zealand, 17 developers,
2013
Jan 18	n2k14: Mini-hackathon, Dunedin, New Zealand, 15 developers, 2014
Jan 20	Bind 9 goes into the tree, 2003
Jan 26	Anoncvs service inaugurated, 1996
Jan 26	n2k9: Network hackathon, Basel, Switzerland, 19 developers, 2009
Jan 27	OpenBSD/amd64 port is added, from NetBSD, 2004
Jan 29	"second anoncvs server is 100 miles from the first", 1996
Jan 31	OpenBSD/cats port is added, from NetBSD, 2004

You can browse all of the available local calendars in /usr/share/calendar

Wed Dec 11 16:19:23 2019

cap_mkdb.1

I am not 100% sure what this does or what it is used for. The man page tells us that it is used to “create capability database”. I am not sure what capability this is referring to, but its somehow related to cgetent(3), dbopen(3), and termcap(5). I am sure I will learn more once I get to those sections.

captoinfo.1

This converts termcap to terminfo. Running this command by itself will spit out a bunch of output related to the capabilities of your terminal. Other fun facts: This program was written by the legendary Eric S. Raymond.

cat.1

Everyone knows good old cat.

cc.1

C compiler. This shows the same manpage as c++.1.

Sun, 22 Dec 2019 16:38:38 -0800

cdio.1

This program helps you to work with compact discs. If you are reading this in the future, compact discs were round plastic things that would have data etched on with a laser that could then be read by a different laser. They made a funny sound when inserted into a computer.

check-lib-depends.1

This is a tool for working with ports. This tool will scan binaries to extract libraries and then compare them against the ports registered dependencies.

I found a typo in this page, and sent along my first patch to OpenBSD.

chflags.1

This is a utility that allows you to modify file flags. I have never had to deal with flags before in a real world, but it looks like these impose additional restrictions. Some interesting use cases could be setting the nodump flag which would prevent any files with this flag from being backed up during a dump(8) backup.

chgrp.1

This command allows you to change the group information for files.

chio.1

This is a “medium changer control utility”. In this context, a “medium changer” refers to things that can be found in:

tape and optical disk jukeboxes.

In my mind, I am picturing the CD changer that I had in my mini-van in 2005. Who knew that I could control it with a unix command!

chmod.1

This is a pretty familiar command. It is used to change file modes, I just now realized that is probably why it is called “chmod” since the “mod” part refers to modes. This is a great page to read to familiarize yourself with all of the various options that exist for files. I think that 50% of the troubleshooting that I’ve ever done related to unix issues have been directly related to the file modes.

This page also provides a great overview of absolute vs. symbolic modes.

chpass.1

This command allows you to change user database information. When you are creating a new user with adduser it tells you not to worry because you can make changes later. This is the command that allows you to make those changes.

There is an interesting reference in the SEE ALSO section which refers to a paper written by Robert Morris and Ken Thompson in 1979 which describes the history of the design of a password system. You can read this paper here. It is a fascinating peek into the early design of unix systems.

ci.1

No, this is not a built-in continuous integration system. Instead this command is a part of the rcs(1) program, and specifically allows you to check in a revision. RCS is a revision control system (think git, cvs, svn) which allows you to keep track of changes. The origins of this program date back to the 1980s.

It looks like the main difference between rcs and more modern version control systems is that rcs is intended to work at the individual file level, while other tools are able to keep track of entire directories.

This specific command highlights the limitations of trying to read every man page in alphabetical order, since you tend to read things out of order. I am resisting the urge to follow the breadcrumbs to the rest of the system too early.

Thu, 26 Dec 2019 18:24:33 -0800

cksum.1

This program can be used to display file checksums and block counts. This manpage refers to CRC, which I was not familiar with. I looked it up and it looks like Cyclic Redundancy Check(CRC) is an algorithm that can be used to detect changes to raw data.

There is another article referenced here where the pseudo-code in the article is being implemented in the default calculation that is done by cksum. You can read the full paper here if you have access to the ACM digital library, or here if you don’t.

clang-local.1

This manual describes the OpenBSD specific behavior of the LLVM/clang compiler. Many of the security-focused enhancements that OpenBSD is known for are described here.

clang.1

This is the same man page that we have seen before with cc(1) and c++(1).

clean-old-distfiles.1

This is a BSD ports specific utility that is used to clean up old distfiles.

cmp.1

This is a utility that can be used to compare two files. This is not necessarily a diff, but rather can be used to check to see if two files are the same or not.

co.1

This is the opposite of our friend ci(1) that we met earlier. This can be used to check out an rcs(1) revision.

col.1

I read this page, and I have no idea what this program does. It says that it “filters out reverse line feeds so that the output is in the correct order…” I am not sure what a reverse line feed is, which is likely the root of my confusion.

colrm.1

This program can be used to removed columns from a file.

column.1

This program can be used to format input into multiple columns.

I really wish that col, colrm, and column all had some real world examples in the man page.

comm.1

This command is in the diff(1) and cmp(1) family, it allows you to read two files and see which lines exist in the first, second, and both files.

compress.1

This utility allows you to compress and expand data using adaptive Lempel-Ziv coding.

corelist.1

This is a part of the Perl Programmers Reference Guide, it arguably does not belong in this section.

This is a pretty neat utility because it tells you when a specific module first appeared in Perl.

cp.1

Like cat(1) this has likely been used by every human who has ever logged into a unix shell. This command allows you to copy files.

cpan.1

This command is also a part of the Perl Programmers reference. This allows you to interact with CPAN, the comprehensive perl archive network, over the command line.

cpio.1

This program allows you to copy file archives. This is in the same family as tar(1).

cpp.1

Same as c++(1).

crontab.1

This command is used to install, remove, or list the tables for cron(8). Cron can be used to schedule commands to run. I’ve used cron quite a bit in my life so far. It can be a little bit tricky since some of the environment settings that exist when you are in an interactive shell session are not available to a cron job. I think we will learn more about this when we read about cron(8) itself.

csh.1

csh is a shell. It was one of the first shells to implement history, jobs, and file name completion. Compared to sh, it uses a C-like syntax which might make it a bit easier to grok various scripts.

This is one of the longest man pages I’ve read so far, since it described in great detail every aspect of this shell for the purposes of using it interactively or using it as an interpreter.

Some other interesting facts, this shell was written by Bill Joy who was a co-founder of Sun Microsystems. He also created the vi editor, and more or less began the distribution of BSD.