AFS Assigned Numbers Registry - Error Tables

• AFS com err tables

• AuriStorFS com_err tables

• Non-AFS com_err tables

• AFS Volume Package Errors

• Rx RPC error codes

• rxgen error codes

• Reserved codes

• Registration Policy

This is a registry of the various error code tables used in the AFS protocols. This includes a list of com_err error tables used in AFS, as well as two groups of codes not defined using com_err. As a service to users of com_err outside the context of AFS, this registry also contains a table of com_err error tables used by other software.

AFS com_err tables

In order to allow for various protocols and components to define error codes which do not conflict, AFS uses com_err error codes in nearly every situation. Below is a list of all com_err tables defined by AFS, with links to the registry page for each table.

Note that all of the package names listed below begin with capital letters. This has the effect of insuring that the resulting error codes will have positive values when interpreted as signed 32-bit numbers, which allows applications to distinguish between errors generated by the remote server (normally positive) from errors generated by the Rx protocol layer at either end (always negative).

AuriStorFS com_err tables

Below is a list of all com_err tables defined by AuriStorFS, with links to the registry page for each table. Allocations of entries in the AuriStorFS com_err tables should be made in consultation with afs3@auristor.com.

Note: the AuriStorFS variant of the RXGK error table conflicts with the error table documented in rxgk: GSSAPI based security class for RX. The AuriStorFS RXGK implementation used in conjunction with the yfs-rxgk security class predates the error table in the Internet-Draft by more than two years.

Non-AFS com_err tables

The following is an index of known non-AFS com_err error tables. It is maintained as a service to other users of the com_err package, in order to reduce the likelihood of conflicts and allow users to more easily interpret error codes. Note that while we hope it serves a useful purpose, this list is almost certainly not exhaustive.

Each entry includes a link to the current list of codes and a contact address to obtain more information or to register a code. Except where noted, the contents of these error tables are _not_ administered by the AFS Assigned Numbers Registrar, and the information provided here may not be the most current available.

AFS Volume Package Errors

For historical reasons, AFS volume-related errors are small positive integers starting at 101; these error codes may be returned by the fileserver or volserver. While codes in this range were once "safe", they now conflict with system error codes on many platforms. Callers should use care when interpreting error codes to distinguish system and volume package errors based on context.

Note also that VRESTARTING is -100, a negative number. This is done to "trick" older implementations not supporting this state into believing that the fileserver returning this error is down, allowing them to retry or fail over to another fileserver instead of reporting a permanent error to the user.

AuriStorFS where possible has replaced these error values with those from the V error table.

Rx RPC error codes

The Rx protocol and implementations use a number of small negative error codes to indicate protocol-level errors. These codes should not conflict with any com_err package likely to be used. However, small negative error values are often used by C programmers to represent failure which can be confused with these errors. Also, in the Linux kernel, error values are often negated in ordr to distinguish error values from memory addresses.

These error values are required to be used on the wire. AuriStorFS never exposes these error values outside of the Rx RPC implementation. Instead the Portable RX com_err table values are returned to callers.

rxgen error codes

rxgen uses a number of negative error codes to indicate protocol-level errors. These codes should not conflict with any com_err package likely to be used.

Reserved codes

Error code 0 is reserved for a successful result.

The error package name '', corresponding to positive integers less than 256, is reserved for system error codes. Package names consisting of a single uppercase letter should be avoided in order to allow for a larger number of system error codes in the future.

The error package names '____' and '___9' are reserved for Rx protocol and RPC marshalling errors. Codes in these ranges will continue to be assigned explicitly, without the use of com_err.

Registration Policy

In most cases, new codes will be assigned on request in tables which are coordinated by the AFS Assigned Numbers Registrar. Requests for code assignment must include information about the meaning and usage of the new code(s) to be assigned.

Because of their special nature, codes in the tables of volume package and Rx protocol errors will normally be assigned only when it is the concensus of the AFS development community that a new code is needed.

New AFS-related com_err error tables will be established when there is a demonstrated need not served by any existing table (for example, a new AFS component or protocol whose error should be separate from those in any existing table). Proposals for new tables should include the proposed table name, purpose of the table, and an initial list of codes which the table would contain. If the need is not plainly clear, the registrar may refer the request to the AFS development community for discussion. Once a new table is established, assignment of codes in the new table will normally be coordinated by the AFS Assigned Numbers Registrar.

New com_err error tables for purposes not related to AFS will be registered on request. Registration requests should include the table name, purpose of the table, and a contact address. The registrar will generally not assign table names or insure their uniqueness, but may provide advice in selection of a table name. The AFS Assigned Numbers Registrar will generally not coordinate assignment of codes in error tables that are not AFS-related. However, a link to an official copy of the table will be published, if one is provided by the contact.