AFS Assigned Numbers Registry - ioctl() and pioctl() function codes

This is a registry of the function codes used for ioctl() and pioctl() functions used on AFS files and for configuring cache managers. While these interfaces are not part of the AFS wire protocol, there is a desire to promote interoperability between AFS implementations by providing a common registry for these codes.

There are several ioctl/pioctl code groups, each of which contains a maximum of 255 available codes. There is a code group for each AFS implementation participating in this registry, plus a group for common implementation-independent functions. The code group list and the common group are managed by the AFS assigned numbers registrar. The lists below is the canonical list, and all unassigned codes are reserved.

The implementation-specific groups are managed by the maintainers of each implementation. The lists below may not be canonical, but will be updated as requested by the implementation maintainers. Unassigned codes must not be used without approval of the implementation maintainer.

Code Groups

Common ioctl() Codes

Transarc/IBM and Legacy ioctl() Codes

Common pioctl() Codes

Transarc/IBM and Legacy pioctl() Codes

OpenAFS pioctl() Codes

The following list is for reference purposes only, and may not be fully up-to-date. For a canonical list of 'O' group pioctl's used in OpenAFS, see the most recent verison of src/config/vioc.h, available A HREF="http://cvs.openafs.org/src/config/vioc.h">via CVSweb.

Arla pioctl() Codes

The following list is for reference purposes only, and may not be fully up-to-date. For a canonical list of 'A' group pioctl's used in Arla, see the most recent verison of arla/include/kafs.h, available via CVSweb.

How to use these codes

These codes are to compute the request number argument to the ioctl() and pioctl() system calls. The exact method of computation varies from platform to platform, and is generally encoded in the definition of the macros listed in the code group table, such that _VICEIOCTL(10) produces the correct request for pioctl code 10 in the 'V' group, and _VICEIOCTL2('C',2) produces the correct request for pioctl code 2 in the 'C' group.

For UNIX systems, the method of computation is the same as that used to compute request numbers for device ioctl() calls. Such systems generally encode a device type, request code, argument type, and argument "direction" (read, write, read/write, or none). For these codes, the device is the code group letter, the direction is 'read/write' ('write' on platforms which don't have read/write), and the argument is of the following type:

  struct ViceIoctl {
    caddr_t in, out;
    short in_size;
    short out_size;
  }

This is accomplished with definitions like the following: #define _VICEIOCTL(x) _IOW('V', x, struct ViceIoctl) #define _VICEIOCTL2(dev,x) _IOW(dev, x, struct ViceIoctl)

Reserved codes

Code 0 is reserved in every group and must not be used.

Codes V.239, C.239, and C.255 are reserved for future code space expansion by the registrar and must not be used for any other purpose. Managers of other code groups are encouraged to reserve codes 239 and 255 for future code space expansion.

Codes V.240 through V.247 (VIOC_SITE1 through VIOC_SITE8) are reserved for use by extensions local to a specific site. They should never be used in any distributed software.

Codes V.248 through V.255 (VIOC_PRIVATE1 through VIOC_PRIVATE8) are reserved for private implementation-specific extensions. They should be used only by software which is absolutely certain which cache manager implementation is in use.

Registration Policy

Codes for ioctl() and pioctl() functions in the 'C' group will be assigned on request for new common, implementation-independent functions supported by any cache manager implementation wishing to provide these interfaces. Codes in other groups are assigned by and at the discretion of the maintainers of the implementation listed for the group.

New code groups will be assinged to any cache manager implementation wishing to provide these interfaces and desiring a private code space.

When a function is already provided by one implementation, other implementors are encouraged to use the same interface in order to provide for maximum interoperability.