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

Group Macro Implementation / Owner
C _VICEIOCTL2('C',x) Common functions
V _VICEIOCTL(x) Transarc/IBM and legacy functions
A _ARLAIOCTL(x) Arla (http://www.stacken.kth.se/projekt/arla/)
O _VICEIOCTL2('O',x) OpenAFS (http://www.openafs.org/)

Common ioctl() Codes

Group Code Name Purpose / Usage
C 0 - reserved -
C 239 - reserved - Reserved for code space expansion
C 255 - reserved - Reserved for code space expansion

Transarc/IBM and Legacy ioctl() Codes

Group Code Name Purpose / Usage
V 0 - reserved -
V 1 VIOCCLOSEWAIT Force close() to wait for store
V 2 VIOCABORT Abort close on this fd
V 3 VIOCIGETCELL Get cell name
V 239 - reserved - Reserved for code space expansion
V 240 VIOC_SITE1 Reserved for site-specific extensions
V 241 VIOC_SITE2 Reserved for site-specific extensions
V 242 VIOC_SITE3 Reserved for site-specific extensions
V 243 VIOC_SITE4 Reserved for site-specific extensions
V 244 VIOC_SITE5 Reserved for site-specific extensions
V 245 VIOC_SITE6 Reserved for site-specific extensions
V 246 VIOC_SITE7 Reserved for site-specific extensions
V 247 VIOC_SITE8 Reserved for site-specific extensions
V 248 VIOC_PRIVATE1 Reserved for implementation use
V 249 VIOC_PRIVATE2 Reserved for implementation use
V 250 VIOC_PRIVATE3 Reserved for implementation use
V 251 VIOC_PRIVATE4 Reserved for implementation use
V 252 VIOC_PRIVATE5 Reserved for implementation use
V 253 VIOC_PRIVATE6 Reserved for implementation use
V 254 VIOC_PRIVATE7 Reserved for implementation use
V 255 VIOC_PRIVATE8 Reserved for implementation use

Common pioctl() Codes

Group Code Name Purpose / Usage
C 0 - reserved -
C 1 VIOC_NEWALIAS Add new cell alias
C 2 VIOC_GETALIAS Get cell alias info
C 3 VIOC_CBADDR Push callback address
C 4 VIOC_CHOWN Change file owner
C 5 VIOC_DISCON Set/get diconnected mode
C 6 VIOC_CREATE_MT_PT Create mount point
C 7 VIOCGETTOK2 Get tokens (extended)
C 8 VIOCSETTOK2 Set tokens (extended)
C 9 VIOCNEWUUID Force a new uuid
C 10 VIOCGETPROP Get property
C 11 VIOCSETPROP Set property
C 239 - reserved - Reserved for code space expansion
C 255 - reserved - Reserved for code space expansion

Transarc/IBM and Legacy pioctl() Codes

Group Code Name Purpose / Usage
V 0 - reserved -
V 1 VIOCSETAL Set access control list
V 2 VIOCGETAL Get access control list
V 3 VIOCSETTOK Set authentication tokens
V 4 VIOCGETVOLSTAT Get volume status
V 5 VIOCSETVOLSTAT Set volume status
V 6 VIOCFLUSH Invalidate cache entry
V 7 VIOCSTAT Get file status
V 8 VIOCGETTOK Get authentication tokens
V 9 VIOCUNLOG Invalidate tokens
V 10 VIOCCKSERV Check that servers are up
V 11 VIOCCKBACK Check backup volume mappings
V 12 VIOCCKCONN Check connections for a user
V 13 VIOCGETTIME Make gettime call (historic)
V 14 VIOCWHEREIS Find out where a volume is located
V 15 VIOCPREFETCH Prefetch a file
V 16 VIOCNOP No-op (historic)
V 17 VIOCENGROUP Enable group access (historic)
V 18 VIOCDISGROUP Disable group access (historic)
V 19 VIOCLISTGROUPS List enabled and disabled groups (historic)
V 20 VIOCACCESS Access using PRS_FS bits
V 21 VIOCUNPAG Invalidate pag
V 22 VIOCGETFID Get file ID quickly
V 23 VIOCWAITFOREVER Wait for dead servers forever (historic)
V 24 VIOCSETCACHESIZE Set venus cache size in 1k units
V 25 VIOCFLUSHCB Flush callback only
V 26 VIOCNEWCELL Configure new cell
V 27 VIOCGETCELL Get cell info
V 28 VIOC_AFS_DELETE_MT_PT Delete mount point
V 29 VIOC_AFS_STAT_MT_PT Stat mount point
V 30 VIOC_FILE_CELL_NAME Get cell in which file lives
V 31 VIOC_GET_WS_CELL Get cell in which workstation lives
V 32 VIOC_AFS_MARINER_HOST Get/set mariner (cache manager monitor) host
V 33 VIOC_GET_PRIMARY_CELL Get primary cell for caller
V 34 VIOC_VENUSLOG Enable/Disable venus logging
V 35 VIOC_GETCELLSTATUS Get cell status info
V 36 VIOC_SETCELLSTATUS Set corresponding info
V 37 VIOC_FLUSHVOLUME Flush whole volume's data
V 38 VIOC_AFS_SYSNAME Change @sys value
V 39 VIOC_EXPORTAFS Export afs to nfs clients
V 40 VIOCGETCACHEPARMS Get cache stats
V 41 VIOCGETVCXSTATUS
V 42 VIOC_SETSPREFS33 Set server ranks (deprecated)
V 43 VIOC_GETSPREFS Get server ranks
V 44 VIOC_GAG Silence CM
V 45 VIOC_TWIDDLE Adjust RX knobs
V 46 VIOC_SETSPREFS Set server ranks
V 47 VIOC_STORBEHIND Adjust store asynchrony
V 48 VIOC_GCPAGS Disable automatic pag gc-ing
V 49 VIOC_GETINITPARAMS Get initial cm params
V 50 VIOC_GETCPREFS Get client interface
V 51 VIOC_SETCPREFS Set client interface
V 52 VIOC_AFS_FLUSHMOUNT Flush mount symlink data
V 53 VIOC_RXSTAT_PROC Control process RX stats
V 54 VIOC_RXSTAT_PEER Control peer RX stats
V 55 VIOC_GETRXKCRYPT Get rxkad encryption flag
V 56 VIOC_GETRXKCRYPT Set rxkad encryption flag
V 57 VIOC_FPRIOSTATUS arla: set file prio
V 58 VIOC_FHGET arla: fallback getfh
V 59 VIOC_FHOPEN arla: fallback fhopen
V 60 VIOC_XFSDEBUG arla: controls xfsdebug
V 61 VIOC_ARLADEBUG arla: controls arla debug
V 62 VIOC_AVIATOR arla: debug interface
V 63 VIOC_XFSDEBUG_PRINT arla: print xfs status
V 64 VIOC_CALCULATE_CACHE arla: force cache check
V 65 VIOC_BREAKCELLBACK arla: break callback
V 99 PSetClientContext NFS-pag pioctl (for knfs/rmtsysd)
V 239 - reserved - Reserved for code space expansion
V 240 VIOC_SITE1 Reserved for site-specific extensions
V 241 VIOC_SITE2 Reserved for site-specific extensions
V 242 VIOC_SITE3 Reserved for site-specific extensions
V 243 VIOC_SITE4 Reserved for site-specific extensions
V 244 VIOC_SITE5 Reserved for site-specific extensions
V 245 VIOC_SITE6 Reserved for site-specific extensions
V 246 VIOC_SITE7 Reserved for site-specific extensions
V 247 VIOC_SITE8 Reserved for site-specific extensions
V 248 VIOC_PRIVATE1 Reserved for implementation use
V 249 VIOC_PRIVATE2 Reserved for implementation use
V 250 VIOC_PRIVATE3 Reserved for implementation use
V 251 VIOC_PRIVATE4 Reserved for implementation use
V 252 VIOC_PRIVATE5 Reserved for implementation use
V 253 VIOC_PRIVATE6 Reserved for implementation use
V 254 VIOC_PRIVATE7 Reserved for implementation use
V 255 VIOC_PRIVATE8 Reserved for implementation use

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.

Group Code Name Purpose / Usage
O 0 - reserved -
O 1 VIOC_NFS_NUKE_CREDS nuke creds for all NFS PAG's

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.

Group Code Name Purpose / Usage
A 0 - reserved -
A 1 AIOC_STATISTICS arla: fetch statistics
A 2 AIOC_PTSNAMETOID arla: pts name to id
A 3 AIOC_GETCACHEPARAMS arla: get cache params

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.