OpenAFS Wiki/ devel/ OpenAFSPioctlInterfaceDoc

?PSetACL

Group
V
Function
VIOCSETAL (1) - Set access control list
Arguments
the ACL being set
Outcome
Changed ACL, via direct writing to the wire

Errors

  • EINVAL - if some of the standard arguments aren't set
Side Effects
none listed

?PGetACL

Group
V
Function
VIOCGETAL (2) - Get access control list
Arguments
none
Outcome
Obtain the ACL, based on file ID

Errors

  • EINVAL - if some of the standard arguments aren't set
  • ERANGE - if the vnode of the file id is too large
  • return -1 - if getting the ACL failed
Side Effects
none listed, although there is a hack to tell which type of ACL is being returned, checks the top 2-bytes to judge what type of ACL is it, only for dfs xlator ACLs

?PSetTokens

Group
V
Function
VIOCSETTOK (3) - Set authentication tokens
Arguments
the krb tickets from which to set the afs tokens
Outcome
Set the Tokens for a specific cell name, unless there is none set, then default to primary

Errors

  • EINVAL - if the ticket is either too long or too short
  • EIO - if the AFS initState is below 101
  • ESRCH - if the cell for which the Token is being set can't be found
Side Effects
none listed

?PGetVolumeStatus

Group
V
Function
VIOCGETVOLSTAT (4) - Get volume status
Arguments
none
Outcome
The staus of a volume(based on the FID of the volume), or an offline message/motd

Errors

  • EINVAL: if some of the default arguments don't exist
Side Effects
none listed

?PSetVolumeStatus

Group
V
Function
VIOCSETVOLSTAT (5) - Set volume status
Arguments
values to set the status at, offline message, message of the day, volume name, minimum quota, maximum quota
Outcome
Set the status of a volume, including any offline messages, a minimum quota, and a maximum quota

Errors

  • EINVAL - if some of the default arguments don't exist
  • EROFS - if the volume is read only, or a backup volume
  • ENODEV - if the volume can't be accessed
  • ?E2BIG - if the volume name, offline message, and motd are too big
Side Effects
none listed

PFlush

Group
V
Function
VIOCFLUSH (6) - Invalidate cache entry
Arguments
none
Outcome
Flush any information the cache manager has on an entry

Errors

  • EINVAL - if some of the initial arguments don't exist
Side Effects
none listed

PBogus & PNoop

Group
V
Function
VIOCSTAT (7) - Get file status
Group
V
Function
VIOCGETTIME (13) - Make gettime call (historic)
Group
V
Function
VIOCPREFETCH (15) - Pre-fetch a file
Group
V
Function
VIOCNOP (16) - No-op (historic)
Group
V
Function
VIOCENGROUP (17) - Enable group access (historic)
Group
V
Function
VIOCDISGROUP (18) - Disable group access (historic)
Group
V
Function
VIOCLISTGROUPS (19) - List enabled and disabled groups (historic)
Group
V
Function
VIOC_FPRIOSTATUS (57) - arla: set file 'prio'
Group
V
Function
VIOC_FHGET (58) - arla: fallback getfh
Group
V
Function
VIOC_FHOPEN (59) - arla: fallback fhopen
Group
V
Function
VIOC_XFSDEBUG (60) - arla: controls xfsdebug
Group
V
Function
VIOC_ARLADEBUG (61) - arla: controls arla debug
Group
V
Function
VIOC_AVIATOR (62) - arla: debug interfac
Group
V
Function
VIOC_XFSDEBUG_PRINT (63) - arla: print xfs status
Group
V
Function
VIOC_CALCULATE_CACHE (64) - arla: force cache check
Group
V
Function
VIOC_BREAKCELLBACK (65) - arla: break callback
Group
V
Function
VIOCWAITFOREVER (23) - Wait for dead servers forever (historic)

?PGetTokens

Group
V
Function
VIOCGETTOK (8) - Get authentication tokens
Arguments
An integer that corresponds to a user id, which in turn corresponds to a token
Outcome
If the the input parameter exists, get the token that corresponds to the parameter value, if there is no token at this value, get the token for the first cell

Errors

  • EIO - if the afs daemon hasn't started yet
  • EDOM - if the input parameter is out of the bounds of the available tokens
  • ENOTCONN - if there aren't tokens for this cell
Side Effects
none listed, although it's a weird interface (from comments in code)

PUnlog

Group
V
Function
VIOCUNLOG (9) - Invalidate tokens
Arguments
none
Outcome
remove tokens from a user, specified by a user id

Errors

  • EIO - if the afs daemon hasn't started yet
$ Side Effects
set's the token's time to 0, which then causes it to be removed

//////////////////////////////////////////

Group
V
Function
VIOCUNPAG (21) - Invalidate PAG

///////////////////////////////////////// Unlog is the same as un-pag in ?OpenAFS

?PCheckServers

Group
V
Function
VIOCCKSERV (10) - Check that servers are up
Arguments
The name of the cell that the servers will be a part of.
Outcome
Either a fast check (where it doesn't contact servers) or a local check (checks local cell only)

Errors

  • EIO - if the afs daemon hasn't started yet
  • EACCES - if the user doesn't have super-user credentials
  • ENOENT - if we are unable to obtain the cell
Side Effects
none listed

?PCheckVolNames

Group
V
Function
VIOCCKBACK (11) - Check backup volume mappings
Arguments
none
Outcome
Check the root volume, and then check the names if the volume check variable is set to force, has expired, is busy, or if the mount points variable is set

Errors

  • EIO - if the afs daemon hasn't started yet
Side Effects
none listed

?PCheckAuth

Group
V
Function
VIOCCKCONN (12) - Check connections for a user
Arguments
none
Outcome
check to see if a user has the correct authentication. If so, allow access

Errors

  • EACCES - if no user is specified
  • EACCES - if the user has no tokens set
  • EACCES - if the users tokens are bad
Side Effects
check the connections to all the servers specified

?PFindVolume

Group
V
Function
VIOCWHEREIS (14) - Find out where a volume is located
Arguments
none
Outcome
find a volume, based on a volume file id

Errors

  • EINVAL - if some of the default arguments don't exist
  • ENODEV - if there is no such volume
Side Effects
check each of the servers specified

?PViceAccess

Group
V
Function
VIOCACCESS (20) - Access using PRS_FS bits
Arguments
none
Outcome
check to make sure access is allowed

Errors

  • EINVAL - if some of the initial arguments aren't set
  • EACCES - if access is denied
Side Effects
none listed

?PGetFID

Group
V
Function
VIOCETFID (22) - Get file ID quickly
Arguments
none
Outcome
get the file id of some file

Errors

  • EINVAL - if some fo the initial arguments aren't set
Side Effects
none listed

?PSetCacheSize

Group
V
Function
VIOCSETCACHESIZE (24) - Set venus cache size in 1000 units
Arguments
The size the venus cache should be set to
Outcome
Set the cache size based on user intput. If no size is given, set it to the default ?OpenAFS cache size

Errors

  • EACCES - if the user doen't have super-user credentials
  • EROFS - if the cache is set to be in memory
Side Effects
recompute the general cache parameters for every single block allocated

?PRemoveCallback

Group
V
Function
VIOCFLUSHCB (25) - Flush callback only
Arguments
none
Outcome
Flushes callbacks, by setting the length of callbacks to one, setting the next callback to be sent to the CB_DROPPED value, and then dequeue's everything else

Errors

  • EINVAL - if some of the initial default arguments aren't set return's 0 - if the volume is set to read-only
Side Effects
none listed

?PNewCell

Group
V
Function
VIOCNEWCELL (26) - Configure new cell
Arguments
the name of the cell, the hosts that will be a part of the cell, whether or not it's linked with another cell, the other cel it's linked with, the file server port, and the volume server port
Outcome
creates a new cell

Errors

  • EIO - if the afs daemon hasn't started yet
  • EACCES - if the user doesn't have super-user credentials
  • EINVAL - if some 'magic' var doesn't have a certain bit set
Side Effects
none listed

?PListCells

Group
V
Function
VIOCGETCELL (27) - Get cell info
Arguments
The cell index of a specific cell
Outcome
Lists the cells server names and addresses

Errors

  • EIO - if the afs daemon hasn't started yet
  • EDOM - if there is no cell asked about
Side Effects
none listed

?PRemoveMount

Group
V
Function
VIOC_AFS_DELETE_MT_PT (28) - Delete mount point
Arguments
none // I DON'T THINK
Outcome
Ensure that everything is ok, before deleting the mountpoint. If not, don't delete. Delete a mount point based on a file id

Errors

  • EINVAL - if some of default arguments don't exist
  • ENOTDIR - if the argument to remove is not a directory
  • ENOENT - if there is no cache to remove the mount point from
  • ENOENT - if a vcache doesn't exist
Side Effects
none listed

?PNewStatMount

Group
V
Function
VIOC_AFS_STAT_MT_PT (29) - Stat mount point
Arguments
the last component in a path, related to mountpoint that we're looking for information about
Outcome
get the volume, and cell, as well as the link data for a mount point

Errors

  • EINVAL - if some of the default initial arguments aren't set
  • ENOTDIR - if the 'mount point' argument isn't a directory
  • EIO - if the link data can't be accessed
Side Effects
none listed

?PGetFileCell

Group
V
Function
VIOC_FILE_CELL_NAME (30) - Get cell in which file lives
Arguments
none
Outcome
Get a cell based on a passed in on a passed in file id

Errors

  • EINVAL - if someo f the default initial arguments aren't set
  • ESRCH - if the file isn't part of a cell
Side Effects
none listed

?PGetWSCell

Group
V
Function
VIOC_GET_WS_CELL (31) - Get cell in which workstation lives
Arguments
none
Outcome
Get the primary cell that the machine is a part of

Errors

  • EIO - if the afs daemon hasn't started yet
  • ESRCH - if the machine isn't part of a cell, for whatever reason
Side Effects
none listed

PMariner

Group
V
Function
VIOC_AFS_MARINER_HOST (32) - Get/set mariner (cache manager monitor) host
Arguments
none
Outcome
depending on what whether or not a variable is set, either get the host for the cache manager monitor, or set the old address, and give it a new address

Errors turn off mariner

Side Effects
none listed

?PGetUserCell

Group
V
Function
VIOC_GET_PRIMARY_CELL (33) - Get primary cell for caller
Arguments
none
Outcome
get the primary cell for a certain user, based on the user's uid

Errors

  • ESRCH - if the user corresponding to the uid doesn't have a primary cell specified
Side Effects
none listed

?PVenusLogging

Group
V
Function
VIOC_VENUSLOG (34) - Enable/Disable venus logging
Arguments
none
Outcome
obsoleted, perhaps should be PBogus

Errors

  • EINVAL - this is all the function does, perhaps this pioctl should be PBogus
Side Effects
always throws an error

?PGetCellStatus

Group
V
Function
VIOC_GETCELLSTATUS (35) - Get cell status info
Arguments
the cell you want status information on
Outcome
returns the state of the cell as defined in a struct cell

Errors

  • EIO - the afs daemon hasn't started yet
  • ENOENT - the cell doesn't exist
Side Effects
none listed

?PSetCellStatus

Group
V
Function
VIOC_SETCELLSTATUS (36) - Set corresponding info
Arguments
The cell you want to set information about, and the values you want to set
Outcome
Set the state of the cell in a defined struct cell, based on whether or not ?SetUID is allowed

Errors

  • EIO - the afs daemon hasn't started yet
  • EACCES - the user does not have super-user credentials
Side Effects
none listed

?PFlushVolumeData

Group
V
Function
VIOC_FLUSHVOLUME (37) - Flush whole volume's data
Arguments
none //ALTHOUGH MAYBE A VCACHE CONTAINING WHICH VOLUME
Outcome
Wipe everything on the volume. Dependent on which platform this is is for, as to how it's done

Errors

  • EINVAL - some of the initial default arguments aren't set
  • EIO - the afs daemon hasn't started yet
Side Effects
Does not flush a file that a user has open and is using, because it will be re-created on next write. Also purges the dnlc, because things are screwed up

?PSetSysName

Group
V
Function
VIOC_AFS_SYSNAME (38) - Change @sys value
Arguments
a new value for @sys
Outcome
Set the value of @sys if these things work: if the input isn't too long or if input doesn't start with .0 or ..0

Errors

  • EINVAL - if afsd isn't runing
  • EINVAL - if the new sysname is too large
  • EINVAL - if the new sysname causes issues(starts with a .0 or a ..0
  • EINVAL - if there is no PAG set in the credentials
  • EINVAL - if the user of a PAG can't be found
  • EINVAL - if (!(exporter = au->exporter)) // NOT SURE ON THIS
  • ENODEV - if there isn't already a system named that //I THINK
  • EACCES - if the user doesn't have super-user credentials
Side Effects
local user needs root, remote user does not (because remote user ids aren't trusted)

?PExportAfs

Group
V
Function
VIOC_EXPORTAFS (39) - Export afs to nfs clients
Arguments
A struct Vic * EIOctl containing export values needed to change between nfs and afs
Outcome
//REALLY NOT SURE ON THIS... INPUT WOULD BE NICE

Errors

  • ENODEV - if the exporter doesn't exist
  • EACCES - if the user doesn't have super-user credentials $ Side Effects:none listed

?PGetCacheSize

Group
V
Function
VIOCGETCACHEPARMS (40) - Get cache stats
Arguments
none
Outcome
Get the cache blocks, and how many of the cache blocks there are

Errors

  • none, seemingly
Side Effects
none listed

?PGetVnodeXStatus

Group
V
Function
VIOCGETVCXSTATUS (41) - ???
Arguments
none
Outcome
get's the fid, the data version, any lock, the parent vnode, the parent unique identifier, the truncation position, the callback, cbExpires(probably when the callback expires), if any access is being made, if any files are open, any users executing or writing, the 'flock' count, the states, and the move statistic

Errors

  • EINVAL - if some of the initial default arguments aren't set
  • EACCES - if access to check the mode bits is denied
Side Effects
none listed

?PSetSPrefs33

Group
V
Function
VIOC_SETPREFS33 (42) - Set server ranks (deprecated)
Arguments
the server preferences to be set
Outcome
set the server preferences, calling a function

Errors

  • none
Side Effects
none listed

?PGetSPrefs

Group
V
Function
VIOC_GETSPREFS (43) - Get server ranks
Arguments
none
Outcome
Get the sprefs

Errors

  • EIO - if the afs daemon hasn't started yet
  • ENOENT - is the sprefrequest is too large
Side Effects
none listed

PGag

Group
V
Function
VIOC_GAG (44) - Silence Cache Manager
Arguments
The flags to either gag or de-gag the cache manager
Outcome
set the gag flags, then show these flags

Errors

  • EACCES - if the user doesn't have super-user credentials
Side Effects
none listed

?PTwiddleRx

Group
V
Function
VIOC_TWIDDLE (45) - Adjust RX knobs
Arguments
the previous settings of the 'knobs'
Outcome
build out the struct rxp, from a struct rx

Errors

  • EACCES - if the user doesn't have super-user credentials
Side Effects
none listed

?PSetSPrefs

Group
V
Function
VIOC_SETPREFS (46) - Set server ranks
Arguments
the sprefs value to want the sprefs set to
Outcome
set the sprefs using the afs_setsprefs() function

Errors

  • EIO - if the afs daemon hasn't started yet
  • EACCES - if the user doesn't have super-user credentials
  • EINVAL - if the struct setsprefs is too large
  • EINVAL - if the struct setsprefs multiplied by the number of servers is too large
Side Effects
none listed

?PStoreBehind

Group
V
Function
VIOC_STORBEHIND (47) Adjust store asynchrony
Arguments
sets the sbstruct
Outcome
set asynchrony based on a file, from a struct sbstruct //I THINK

Errors

  • EPERM - if the user doesn't have super-user credentials
  • EACCES - if there isn't enough access to not check the mode bits
Side Effects
none listed

PGCPAGs

Group
V
Function
VIOC_GCPAGS (48) - Disable automatic PAG gc'ing
Arguments
none
Outcome
set the gcpags to GCPAGS_USERDISABLED

Errors

  • EACCES - if the user doesn't have super-user credentials
Side Effects
none listed

?PGetInitParams

Group
V
Function
VIOC_GETINITPARAMS (49) - Get initial cache manager parameters
Arguments
none
Outcome
return the initial cache manager parameters

Errors

  • ?E2BIG - if the initial parameters are bigger than some PIGGYSIZE
Side Effects
none listed

?PGetCPrefs

Group
V
Function
VIOC_GETCPREFS (50) - Get client interface
Arguments
none
Outcome
get the information about the client interface

Errors

    • EIO - the afs daemon hasn't started yet
    • EINVAL - if the request is too large for the struct that will be holding it
Side Effects
none listed

?PSetCPrefs

Group
V
Function
VIOC_SETCPREFS (51) - Set client interface
Arguments
The interfaces you want set
Outcome
set the callback interfaces addresses to those of the hosts

Errors

  • EIO - the afs daemon hasn't started yet
  • EINVAL - the input is too large for the struct
  • ENOMEM - if there are too many servers
Side Effects
none listed

?PFlushMount

Group
V
Function
VIOC_AFS_FLUSHMOUNT (52) - Flush mount symlink data
Arguments
The last part of a path to a mount point, which tells us what to flush
Outcome
remove all of the mount data from the dcache regarding a certain mount point

Errors

  • EINVAL - if some of the initial arguments aren't set
  • ENOTDIR - if the initial argument for the mount point isn't a directory
  • ENOENT - if the dcache entry isn't set

?PRxStatProc

Group
V
Function
VIOC_RXSTAT_PROC (53) - Control process RX statistics
Arguments
The flags that control which statistics to use
Outcome
either enable process RPCStats, disable process RPCStats, or clear the process RPCStats

Errors

  • EACCES - if the user doesn't have super-user credentials
  • EINVAL - if the flag input is too long
Side Effects
none listed

?PRxStatPeer

Group
V
Function
VIOC_RXSTAT_PEER (54) - Control peer RX statistics
Arguments
The flags that control which statistics to use
Outcome
either enable peer RPCStats, disable peer RPCStats, or clear the peer RPCStats

Errors

  • EACCES - if the user doesn't have super-user credentials
  • EINVAL - if the flag input is too long
Side Effects
none listed

?PGetRxkcrypt

Group
V
Function
VIOC_GETRXKCRYPT (55) - Get rxkad encryption flag
Arguments
none
Outcome
get the value of cryptall(presumably whether or not things should be encrypted

Errors

  • none
Side Effects
none listed

?PSetRxkcrypt

Group
V
Function
VIOC_SETRXKCRYPT (56) - Set rxkad encryption flag
Arguments
the argument whether or not things should be encrypted
Outcome
set whether or not things should be encrypted

Errors

  • EPERM - if the user doesn't have super-user credentials
  • EINVAL - if the input is too big, or if the input is outside the bounds of what it can be set to
Side Effects
none really, but may need to be modified at a later date to take into account other values for cryptall(beyond true and false)

?PSetClientContext

Group
V
Function
?PsetClientContext (99) - NFS-PAG pioctl (for knfs/rmtsysd)
Arguments
none
Outcome
Setup caller's credentials, dependent on an AIX 64-bit kernel, HPUX, SUN57 64-bit kernel, SGI 64-mips, or a need for a 32-bit ioctl

Errors

  • none
Side Effects
none listed

//WASN'T SURE WHAT TO DO ABOUT THESE, ALSO NOTE THAT THE ABOVE ARE JUST THE V GROUP PIOCTL()s, I CAN DOCUMENT THE C GROUP, MOST OF WHICH ARE PBogus

Group
V
Function
*reserved* (239) - Reserved for code expansion
Group
V
Function
VIOC_SITE1 (240) - Reserved for site-specific extensions
Group
V
Function
VIOC_STIE2 (241) - Reserved for site-specific extensions
Group
V
Function
VIOC_SITE3 (242) - Reserved for site-specific extensions
Group
V
Function
VIOC_SITE4 (243) - Reserved for site-specific extensions
Group
V
Function
VIOC_SITE5 (244) - Reserved for site-specific extensions
Group
V
Function
VIOC_SITE6 (245) - Reserved for site-specific extensions
Group
V
Function
VIOC_SITE7 (246) - Reserved for site-specific extensions
Group
V
Function
VIOC_SITE8 (247) - Reserved for site-specific extensions
Group
V
Function
VIOC_PRIVATE1 (248) - Reserved for implementation use
Group
V
Function
VIOC_PRIVATE2 (249) - Reserved for implementation use
Group
V
Function
VIOC_PRIVATE3 (250) - Reserved for implementation use
Group
V
Function
VIOC_PRIVATE4 (251) - Reserved for implementation use
Group
V
Function
VIOC_PRIVATE5 (252) - Reserved for implementation use
Group
V
Function
VIOC_PRIVATE6 (253) - Reserved for implementation use
Group
V
Function
VIOC_PRIVATE7 (254) - Reserved for implementation use
Group
V
Function
VIOC_PRIVATE8 (255) - Reserved for implementation use