APLawrence.com -  Resources for Unix and Linux Systems, Bloggers and the self-employed

Numeric Unix Error Messages

© December 2001 Tony Lawrence
December 2001

It's an unfortunate fact that many programmers are lazy about error messages. Very often, all you get is a cryptic "Error 5", and you may be lucky to get that: sometimes all you get is an error return that you have to examine yourself with "echo $?". You can't even depend on that being the actual Unix error, but even if it is, what does it mean?

Well, every Unix/Linux system includes various ".h" files that describe the numeric errors returned by kernel system calls. Unfortunately, those files are only a little bit more illuminating than the numeric errors themselves. For example, here's a couple of lines from a Linux system:

#define EPERM            1      /* Operation not permitted */
#define EACCES          13      /* Permission denied */

What's the difference? When would you get one versus the other? This article attempts to more fully explain what these errors mean and to give examples of what might cause them.

I'm only going to look at the first 32 of these; there are many more, but these are the more common. Understand that the numeric codes can vary from Unix to Unix- you really need to look in the /usr/include files to find the symbolic names, and even those are used in slightly different ways- certain system calls on a BSD system, for example, will return a different error result than they will on a SysV Unix. However, most of that kind of thing is esoteric detail of concern only to programmers working on multiple platforms.

Even where the error numbers and the symbolic constants are the same, the comments may vary. For example, while SCO Unix and Linux systems would look almost exactly alike for the first 30 or 40 errors, some of the comments are markedly different, and higher numbered errors are defined completely differently. So, the thing to keep in mind is that just because you've seen a particular error on a particular platform doesn't mean it is the same somewhere else. There's also nothing that prevents a programmer from misusing these constants in their own error returns, either through ignorance or simple misunderstanding of the historical use of these.

And it also means that the descriptions of what might cause a specific error are heavily dependent on that word "might". Please keep that in mind as you read this.

On a Linux system with source installed, you can cd to /usr/src/linux*/kernel and do a grep -l for the symbolic constant you are interested in. For example, here's the places where EPERM is referenced on a 7.2 Red Hat system:


On Apple OS X, it's even easier. Open Terminal and use "macerror":

$ macerror -5002
Mac OS error -5002 (afpBadUAM): Unknown user authentication method specified

For other Unix systems, pawing through documentation is the only way. For this article, I used:

Unix Internals by Steve Pate
Unix Network Programming by W. Richard Stevens
The Magic Garden by Berny Goodhart and James Cox
Advanced Programming in the Unix Environment by W. Richard Stevens

Again, keep in mind that this is all examples, and may not apply to your specific platform. The system calls shown as examples may not be the only functions that will return these errors; you really need access to the source to know that.

Here's some odd ones:

#define     ENOPKG              65
#define     EISNAM             139

At Rare Error 65 (ENOPKG) occurrence on open() call, Bela Lubkin noted:

There are very few things in the kernel that return ENOPKG. Candidates include the System V shared memory driver ("shm"), the Xenix shared data driver ("xsd"), and the Advanced Power Management drivers ("uapm" and "pwr"). Each of these drivers has "stubs.c" code -- code that gets linked into the kernel when the driver is _not_ present -- that returns ENOPKG for certain operations.

It isn't clear to me whether any of these could return ENOPKG for an
open() call.  More typically it would be on calling shmsys(), any of the
xsd*() functions, and on attempting certain ioctls with the APM stuff.
But... there exists an obscure file type which is an on-disk
representation of a Xenix Shared Data memory segment.  If you had one of
those and tried to open it, it _might_ return ENOPKG if "xsd" wasn't
linked into your kernel.

Or might not.  I just tried it and:

  $ mknod test-m m
  $ cat test-m
  cat: cannot open test-m: Is a name file (error 139)


Got something to add? Send me email.

(OLDER)    <- More Stuff -> (NEWER)    (NEWEST)   

Printer Friendly Version

-> Numeric Unix Error Messages


Inexpensive and informative Apple related e-books:

Take Control of iCloud, Fifth Edition

Take Control of Preview

Take Control of OS X Server

El Capitan: A Take Control Crash Course

Photos: A Take Control Crash Course

More Articles by © Tony Lawrence

Related Articles

Thu Nov 17 03:34:09 2005: 1358   George

Thanks a lot. The article was very informative and was a great help.

Thu Nov 17 04:39:24 2005: 1359   BigDumbDinosaur

Don't forget about the perror library call. It will print an error message to STDERR that will be determined by the error code returned from the most recent system or library call. You can use it something like this:
#include <stdio.h>
extern int errno; /* "universal" error number */
if ((systemcall>)!=0) {
perror("preamble"); /* generate error message w/preamble text */
exit(errno); /* exit & return error to caller */
...program continues...
You can also use this mechanism to log errors by closing STDERR and reopening the channel to a file.

Tue Apr 15 18:12:20 2008: 4042   anonymous

Superb!! Exactly what I wanted!

Tue Apr 6 16:28:27 2010: 8376   TonyLawrence


I came across this recently: Universal Error Numbering System:

Probably won't go anywhere, but there it is.


Printer Friendly Version

Related Articles

Have you tried Searching this site?

This is a Unix/Linux resource website. It contains technical articles about Unix, Linux and general computing related subjects, opinion, news, help files, how-to's, tutorials and more.

Contact us

Printer Friendly Version

After establishing competence and ability, your customer wants to know that you are honest and that you care about their needs. Sell that, because that's what they really want to buy. (Tony Lawrence)

Linux posts

Troubleshooting posts

This post tagged:







Unix/Linux Consultants

Skills Tests

Unix/Linux Book Reviews

My Unix/Linux Troubleshooting Book

This site runs on Linode