1464[Opcode 137] This call is used to create a file, but not
for creating a
1465directory or a symbolic link. If
this call succeeds, it is the Cache Manager
's
1466responsibility to either create an entry locally in the directory specified by
1467DirFid or to invalidate this directory's cache entry.
1469Rx connection information
for the related File Server is contained in a
1470rxConnP. Volume version information is returned
for synchronization purposes in
1473EACCES The caller is not permitted to perform
this operation.
1474\n EINVAL An internal error in looking up the client record was encountered, or
1475an invalid fid or name was provided.
1476\n ENOTDIR The DirFid parameter references an
object which is not a directory.
1477\n VICETOKENDEAD Caller
's authentication token has expired.
1479 \subsubsection sec5-1-3-7 Section 5.1.3.7: RXAFS Rename - Rename the
1480specified file in the given directory
1483int RXAFS Rename(IN struct rx connection *a rxConnP,
1484 IN AFSFid *a origDirFidP,
1485 IN char *a origNameP,
1486 IN AFSFid *a newDirFidP,
1487 IN char *a newNameP,
1488 OUT AFSFetchStatus *a origDirStatusP,
1489 OUT AFSFetchStatus *a newDirStatusP,
1490 OUT AFSVolSync *a volSyncP)
1493[Opcode 138] Rename file a origNameP in the directory identified by a
1494origDirFidP. Its new name is to be a newNameP, and it will reside in the
1495directory identified by a newDirFidP. Each of these names must be no more than
1496AFSNAMEMAX (256) characters long. The status of the original and new
1497directories after the rename operation completes are deposited in a
1498origDirStatusP and a newDirStatusP respectively. Existing callbacks are broken
1499for all files and directories involved in the operation.
1501Rx connection information for the related File Server is contained in a
1502rxConnP. Volume version information is returned for synchronization purposes in
1505EACCES New file exists but user doesn't have Delete rights in the directory.
1506\n EINVAL Name provided is invalid.
1507\n EISDIR Original
object is a file and
new object is a directory.
1508\n ENOENT The
object to be renamed doesn
't exist in the parent directory.
1509\n ENOTDIR Original object is a directory and new object is a file.
1510\n EXDEV Rename attempted across a volume boundary, or create a pathname loop,
1511or hard links exist to the file.
1513 \subsubsection sec5-1-3-8 Section 5.1.3.8: RXAFS Symlink - Create a
1517int RXAFS Symlink(IN struct rx connection *a rxConnP,
1518 IN AFSFid *a dirFidP,
1520 IN char *a linkContentsP,
1521 IN AFSStoreStatus *a origDirStatP,
1522 OUT AFSFid *a newFidP,
1523 OUT AFSFetchStatus *a newFidStatP,
1524 OUT AFSFetchStatus *a newDirStatP,
1525 OUT AFSVolSync *a volSyncP)
1528[Opcode 139] Create a symbolic link named a nameP in the directory identified
1529by a dirFidP. The text of the symbolic link is provided in a linkContentsP, and
1530the desired status fields for the symbolic link given by a origDirStatP. The
1531name offered in a nameP must be less than AFSNAMEMAX (256) characters long, and
1532the text of the link to which a linkContentsP points must be less than
1533AFSPATHMAX (1,024) characters long. Once the symbolic link has been
1534successfully created, its file identifier is returned in a newFidP. Existing
1535callbacks to the a dirFidP directory are broken before the symbolic link
1536creation completes. The status fields for the symbolic link itself and its
1537parent's directory are returned in a newFidStatP and a newDirStatP
1540Rx connection information
for the related File Server is contained in a
1541rxConnP. Volume version information is returned
for synchronization purposes in
1544EACCES The caller does not have the necessary access rights.
1545\n EINVAL Illegal symbolic link name provided.
1547 \subsubsection sec5-1-3-9 Section 5.1.3.9: RXAFS Link - Create a hard
1551int RXAFS Link(IN
struct rx connection *a rxConnP,
1552 IN AFSFid *a dirFidP,
1554 IN AFSFid *a existingFidP,
1555 OUT AFSFetchStatus *a newFidStatP,
1556 OUT AFSFetchStatus *a newDirStatP,
1557 OUT AFSVolSync *a volSyncP)
1560[Opcode 140] Create a hard link named a nameP in the directory identified by a
1561dirFidP. The file serving as the basis
for the hard link is identified by
1562existingFidP. The name offered in a nameP must be less than AFSNAMEMAX (256)
1563characters
long. Existing callbacks to the a dirFidP directory are broken
1564before the hard link creation completes. The status fields for the file itself
1565and its parent's directory are returned in a newFidStatP and a newDirStatP
1567Rx connection information for the related File Server is contained in a
1568rxConnP. Volume version information is returned for synchronization purposes in
1571EACCES The caller does not have the necessary access rights.
1572\n EISDIR An attempt was made to create a hard link to a directory.
1573\n EXDEV Hard link attempted across directories.
1575 \subsubsection sec5-1-3-10 Section 5.1.3.10: RXAFS MakeDir - Create a
1579int RXAFS MakeDir(IN struct rx connection *a rxConnP,
1580 IN AFSFid *a parentDirFid,P
1581 IN
char *a newDirNameP,
1582 IN AFSStoreStatus *a currStatP,
1583 OUT AFSFid *a newDirFidP,
1584 OUT AFSFetchStatus *a dirFidStatP,
1585 OUT AFSFetchStatus *a parentDirStatP,
1586 OUT AFSCallBack *a newDirCallBackP,
1587 OUT AFSVolSync *a volSyncP)
1590[Opcode 141] Create a directory named a newDirNameP within the directory
1591identified by a parentDirFidP. The initial status fields for the new directory
1592are provided in a currStatP. The new directory's name must be less than
1593AFSNAMEMAX (256) characters
long. The new directory's ACL is inherited from its
1594parent. Existing callbacks on the parent directory are broken before the
1595creation completes. Upon successful directory creation, the new directory's
1596file identifier is returned in a newDirFidP, and the resulting status
1597information for the new and parent directories are stored in a dirFidStatP and
1598a parentDirStatP respectively. In addition, a callback for the new directory is
1599returned in a newDirCallBackP.
1601Rx connection information for the related File Server is contained in a
1602rxConnP. Volume version information is returned for synchronization purposes in
1605EACCES The caller does not have the necessary access rights.
1606\n EINVAL The directory name provided is unacceptable.
1608 \subsubsection sec5-1-3-11 Section 5.1.3.11: RXAFS RemoveDir - Remove a
1612int RXAFS RemoveDir(IN struct rx connection *a rxConnP,
1613 IN AFSFid *a parentDirFidP,
1614 IN
char *a dirNameP,
1615 OUT AFSFetchStatus *a newParentDirStatP,
1616 OUT AFSVolSync *a volSyncP)
1619[Opcode 142] Remove the directory named a dirNameP from within its parent
1620directory, identified by a parentDirFid. The directory being removed must be
1621empty, and its name must be less than AFSNAMEMAX (256) characters
long.
1622Existing callbacks to the directory being removed and its parent directory are
1623broken before the deletion completes. Upon successful deletion, the status
1624fields for the parent directory are returned in a newParentDirStatP.
1626Rx connection information for the related File Server is contained in a
1627rxConnP. Volume version information is returned for synchronization purposes in
1630EACCES The caller does not have the necessary access rights.
1632 \subsubsection sec5-1-3-12 Section 5.1.3.12: RXAFS GetStatistics - Get
1633common File Server statistics
1636int RXAFS GetStatistics(IN struct rx connection *a rxConnP,
1637 OUT ViceStatistics *a FSInfoP)
1640[Opcode 146] Fetch the structure containing a set of common File Server
1641statistics. These numbers represent accumulated readings since the time the
1642File Server last restarted. For a full description of the individual fields
1643contained in this structure, please see Section 5.1.2.6.
1645Rx connection information for the related File Server is contained in a
1648---No error codes generated.
1650 \subsubsection sec5-1-3-13 Section 5.1.3.13: RXAFS GiveUpCallBacks -
1651Ask the File Server to break the given set of callbacks on the corresponding
1652set of file identifiers
1655int RXAFS GiveUpCallBacks(IN struct rx connection *a rxConnP,
1656 IN AFSCBFids *a fidArrayP,
1657 IN AFSCBs *a callBackArrayP)
1660[Opcode 147] Given an array of up to AFSCBMAX file identifiers in a fidArrayP
1661and a corresponding number of callback structures in a callBackArrayP, ask the
1662File Server to remove these callbacks from its register. Note that this routine
1663only affects callbacks outstanding on the given set of files for the host
1664issuing the RXAFS GiveUpCallBacks call. Callback promises made to other
1665machines on any or all of these files are not affected.
1667Rx connection information for the related File Server is contained in a
1670EINVAL More file identifiers were provided in the a fidArrayP than callbacks in
1673 \subsubsection sec5-1-3-14 Section 5.1.3.14: RXAFS GetVolumeInfo - Get
1674information about a volume given its name
1677int RXAFS GetVolumeInfo(IN struct rx connection *a rxConnP,
1678 IN
char *a volNameP,
1679 OUT VolumeInfo *a volInfoP)
1682[Opcode 148] Ask the given File Server for information regarding a volume whose
1683name is a volNameP. The volume name must be less than AFSNAMEMAX characters
1684long, and the volume itself must reside on the File Server being probed.
1686Rx connection information for the related File Server is contained in a
1687rxConnP. Please note that definitions for the error codes with VL prefixes may
1688be found in the vlserver.h include file
1690Could not contact any of the corresponding Volume Location Servers.
1691VL BADNAME An improperly-formatted volume name provided.
1692\n VL ENTDELETED An entry was found for the volume, reporting that the volume
1694\n VL NOENT The given volume was not found.
1696 \subsubsection sec5-1-3-15 Section 5.1.3.15: RXAFS GetVolumeStatus -
1697Get basic status information for the named volume
1700int RXAFS GetVolumeStatus(IN struct rx connection *a rxConnP,
1702 OUT AFSFetchVolumeStatus *a volFetchStatP,
1703 OUT
char *a volNameP,
1704 OUT
char *a offLineMsgP,
1708[Opcode 149] Given the numeric volume identifier contained in a volIDP, fetch
1709the basic status information corresponding to that volume. This status
1710information is stored into a volFetchStatP. A full description of this status
1711structure is found in Section 5.1.2.8. In addition, three other facts about the
1712volume are returned. The volume's character
string name is placed into a
1713volNameP. This name is guaranteed to be less than AFSNAMEMAX characters
long.
1714The volume's offline message, namely the
string recording why the volume is
1715off-line (if it is), is stored in a offLineMsgP . Finally, the volume's
1716"Message of the Day" is placed in a motdP. Each of the character strings
1717deposited into a offLineMsgP and a motdP is guaranteed to be less than
1718AFSOPAQUEMAX (1,024) characters
long.
1720Rx connection information for the related File Server is contained in a
1723EACCES The caller does not have the necessary access rights.
1724\n EINVAL A volume identifier of zero was specified.
1726 \subsubsection sec5-1-3-16 Section 5.1.3.16: RXAFS SetVolumeStatus -
1727Set the basic status information for the named volume
1730int RXAFS SetVolumeStatus(struct rx connection *a rxConnP,
1732 AFSStoreVolumeStatus *a volStoreStatP,
1734 char *a offLineMsgP,
1739[Opcode 150] Given the numeric volume identifier contained in a volIDP, set
1740that volume's basic status information to the values contained in a
1741volStoreStatP. A full description of the fields settable by this call,
1742including the necessary masking, is found in Section 5.1.2.9. In addition,
1743three other items relating to the volume may be set. Non-null character strings
1744found in a volNameP, a offLineMsgP, and a motdP will be stored in the volume's
1745printable name, off-line message, and "Message of the Day" fields respectively.
1746The volume name provided must be less than AFSNAMEMAX (256) characters
long,
1747and the other two strings must be less than AFSOPAQUEMAX (1,024) characters
1750Rx connection information for the related File Server is contained in a
1753EACCES The caller does not have the necessary access rights.
1754\n EINVAL A volume identifier of zero was specified.
1756 \subsubsection sec5-1-3-17 Section 5.1.3.17: RXAFS GetRootVolume -
1757Return the name of the root volume for the file system
1760int RXAFS GetRootVolume(IN struct rx connection *a rxConnP,
1761 OUT
char *a rootVolNameP)
1764[Opcode 151] Fetch the name of the volume which serves as the root of the AFS
1765file system and place it into a rootVolNameP. This name will always be less
1766than AFSNAMEMAX characters
long. Any File Server will respond to this call, not
1767just the one hosting the root volume. The queried File Server first tries to
1768discover the name of the root volume by reading from the
1769/usr/afs/etc/RootVolume file on its local disks. If that file doesn't exist,
1770then it will return the default value, namely "root.afs".
1772Rx connection information for the related File Server is contained in a
1773rxConnP. Volume version information is returned for synchronization purposes in
1776---No error codes generated.
1778 \subsubsection sec5-1-3-18 5.1.3.18: RXAFS CheckToken - (Obsolete)
1779Check that the given user identifier matches the one in the supplied
1783int RXAFS CheckToken(IN struct rx connection *a rxConnP,
1785 IN AFSOpaque *token)
1788[Opcode 152] This function only works for the now-obsolete RPC facility used by
1789AFS, R. For modern systems using the Rx RPC mechanism, we always get an error
1790return from this routine.
1792Rx connection information for the related File Server is contained in a
1795ECONNREFUSED Always returned on Rx connections.
1797 \subsubsection sec5-1-3-19 Section 5.1.3.19: RXAFS GetTime - Get the
1798File Server's time of day
1801int RXAFS GetTime(IN struct rx connection *a rxConnP,
1802 OUT
unsigned long *a secondsP,
1803 OUT
unsigned long *a uSecondsP)
1806[Opcode 153] Get the current time of day from the File Server specified in the
1807Rx connection information contained in a rxConnP. The time is returned in
1808elapsed seconds (a secondsP) and microseconds (a uSecondsP) since that standard
1809unix "start of the world".
1811---No error codes generated.
1813 \subsubsection sec5-1-3-20 Section 5.1.3.20: RXAFS NGetVolumeInfo - Get
1814information about a volume given its name
1817int RXAFS NGetVolumeInfo(IN struct rx connection *a rxConnP,
1818 IN
char *a volNameP,
1819 OUT AFSVolumeInfo *a volInfoP)
1822[Opcode 154] This function is identical to RXAFS GetVolumeInfo() (see Section
18235.1.3.14), except that it returns a struct AFSVolumeInfo instead of a struct
1824VolumeInfo. The basic difference is that struct AFSVolumeInfo also carries an
1825accompanying UDP port value for each File Server listed in the record.
1827 \subsubsection sec5-1-3-21 Section 5.1.3.21: RXAFS BulkStatus - Fetch
1828the status information regarding a set of given file system objects
1831int RXAFS BulkStatus(IN struct rx connection *a rxConnP,
1832 IN AFSCBFids *a fidToStatArrayP,
1833 OUT AFSBulkStats *a currStatArrayP,
1834 OUT AFSCBs *a callBackArrayP,
1835 OUT AFSVolSync *a volSyncP)
1838[Opcode 155] This routine is identical to RXAFS FetchStatus() as described in
1839Section 5.1.3.2, except for the fact that it allows the caller to ask for the
1840current status fields for a set of up to AFSCBMAX (50) file identifiers at
1843Rx connection information for the related File Server is contained in a
1844rxConnP. Volume version information is returned for synchronization purposes in
1847EACCES The caller does not have the necessary access rights.
1848\n EINVAL The number of file descriptors for which status information was
1849requested is illegal.
1851 \subsubsection sec5-1-3-22 Section 5.1.3.22: RXAFS SetLock - Set an
1852advisory lock on the given file identifier
1855int RXAFS SetLock(IN struct rx connection *a rxConnP,
1856 IN AFSFid *a fidToLockP,
1857 IN ViceLockType a lockType,
1858 OUT AFSVolSync *a volSyncP)
1861[Opcode 156] Set an advisory lock on the file identified by a fidToLockP. There
1862are two types of locks that may be specified via a lockType: LockRead and
1863LockWrite. An advisory lock times out after AFS LOCKWAIT (5) minutes, and must
1864be extended in order to stay in force (see RXAFS ExtendLock(), Section
1867Rx connection information for the related File Server is contained in a
1868rxConnP. Volume version information is returned for synchronization purposes in
1871EACCES The caller does not have the necessary access rights.
1872\n EINVAL An illegal lock type was specified.
1873\n EWOULDBLOCK The lock was already incompatibly granted to another party.
1875 \subsubsection sec5-1-3-23 Section 5.1.3.23: RXAFS ExtendLock - Extend
1876an advisory lock on a file
1879int RXAFS ExtendLock(IN struct rx connection *a rxConnP,
1880 IN AFSFid *a fidToBeExtendedP,
1881 OUT AFSVolSync *a volSyncP)
1884[Opcode 157] Extend the advisory lock that has already been granted to the
1885caller on the file identified by a fidToBeExtendedP.
1887Rx connection information for the related File Server is contained in a
1888rxConnP. Volume version information is returned for synchronization purposes in
1891EINVAL The caller does not already have the given file locked.
1893 \subsubsection sec5-1-3-24 Section 5.1.3.24: RXAFS ReleaseLock -
1894Release the advisory lock on a file
1897int RXAFS ReleaseLock(IN struct rx connection *a rxConnP,
1898 IN AFSFid *a fidToUnlockP,
1899 OUT AFSVolSync *a volSyncP)
1902[Opcode 158] Release the advisory lock held on the file identified by a
1903fidToUnlockP. If this was the last lock on this file, the File Server will
1904break all existing callbacks to this file.
1906Rx connection information for the related File Server is contained in a
1907rxConnP. Volume version information is returned for synchronization purposes in
1910EACCES The caller does not have the necessary access rights.
1912 \subsubsection sec5-1-3-25 Section 5.1.3.25: RXAFS XStatsVersion - Get
1913the version number associated with the File Server's extended statistics
1917int RXAFS XStatsVersion(IN struct rx connection *a rxConnP,
1918 OUT
long *a versionNumberP)
1921[Opcode 159] This call asks the File Server for the current version number of
1922the extended statistics structures it exports (see RXAFS GetXStats(), Section
19235.1.3.26). The version number is placed into a versionNumberP.
1925Rx connection information for the related File Server is contained in a
1928---No error codes generated.
1930 \subsubsection sec5-1-3-26 Section 5.1.3.26: RXAFS GetXStats - Get the
1931current contents of the specified extended statistics structure
1934int RXAFS GetXStats(IN struct rx connection *a rxConnP,
1935 IN
long a clientVersionNumber,
1936 IN
long a collectionNumber,
1937 OUT
long *a srvVersionNumberP,
1939 OUT AFS CollData *a dataP)
1942[Opcode 160] This function fetches the contents of the specified File Server
1943extended statistics structure. The caller provides the version number of the
1944data it expects to receive in a clientVersionNumber. Also provided in a
1945collectionNumber is the numerical identifier for the desired data collection.
1946There are currently two of these data collections defined: AFS XSTATSCOLL CALL
1947INFO, which is the list of tallies of the number of invocations of internal
1948File Server procedure calls, and AFS XSTATSCOLL PERF INFO, which is a list of
1949performance-related numbers. The precise contents of these collections are
1950described in Sections 5.1.2.7. The current version number of the File Server
1951collections is returned in a srvVersionNumberP, and is always set upon return,
1952even if the caller has asked for a difierent version. If the correct version
1953number has been specified, and a supported collection number given, then the
1954collection data is returned in a dataP. The time of collection is also
1955returned, being placed in a timeP.
1957Rx connection information for the related File Server is contained in a
1960---No error codes are generated.
1962 \subsection sec5-1-4 Section 5.1.4: Streamed Function Calls
1965There are two streamed functions in the File Server RPC interface, used to
1966fetch and store arbitrary amounts of data from a file. While some non-streamed
1967calls pass such variable-length objects as struct AFSCBFids, these objects have
1968a pre-determined maximum size.
1970The two streamed RPC functions are also distinctive in that their single Rxgen
1971declarations generate not one but two client-side stub routines. The first is
1972used to ship the IN parameters off to the designated File Server, and the
1973second to gather the OUT parameters and the error code. If a streamed
1974definition declares a routine named X YZ(), the two resulting stubs will be
1975named StartX YZ() and EndX YZ(). It is the application programmer's job to
1976first invoke StartX YZ(), then manage the unbounded data transfer, then finish
1977up by calling EndX YZ(). The first longword in the unbounded data stream being
1978fetched from a File Server contains the number of data bytes to follow. The
1979application then reads the specified number of bytes from the stream.
1981The following sections describe the four client-side functions resulting from
1982the Fetch-Data() and StoreData() declarations in the Rxgen interface definition
1983file. These are the actual routines the application programmer will include in
1984the client code. For reference, here are the interface definitions that
1985generate these functions. Note that the split keyword is what causes Rxgen to
1986generate the separate start and end routines. In each case, the number after
1987the equal sign specifies the function's identifying opcode number. The opcode
1988is passed to the File Server by the StartRXAFS FetchData() and StartRXAFS
1989StoreData() stub routines.
1992FetchData(IN AFSFid *a_fidToFetchP,
1994 IN
long a_lenInBytes,
1995 OUT AFSFetchStatus *a_fidStatP,
1996 OUT AFSCallBack *a_callBackP,
1997 OUT AFSVolSync *a_volSyncP) split = 130;
1999StoreData(IN AFSFid *Fid,
2000 IN AFSStoreStatus *InStatus,
2004 OUT AFSFetchStatus *OutStatus,
2005 OUT AFSVolSync *a_volSyncP) split = 133;
2008 \subsubsection sec5-1-4-1 Section 5.1.4.1: StartRXAFS FetchData - Begin
2009a request to fetch file data
2012int StartRXAFS FetchData(IN struct rx call *a rxCallP,
2013 IN AFSFid *a fidToFetchP,
2015 IN
long a lenInBytes)
2019Begin a request for a lenInBytes bytes of data starting at
byte offset a offset
2020from the file identified by a fidToFetchP. After successful completion of this
2021call, the data stream will make the desired bytes accessible. The first
2022longword in the stream contains the number of bytes to actually follow.
2024Rx call information to the related File Server is contained in a rxCallP.
2026---No error codes generated.
2028 \subsubsection sec5-1-4-2 Section 5.1.4.2: EndRXAFS FetchData -
2029Conclude a request to fetch file data
2032int EndRXAFS FetchData(IN struct rx call *a rxCallP,
2033 OUT AFSFetchStatus *a fidStatP,
2034 OUT AFSCallBack *a callBackP,
2035 OUT AFSVolSync *a volSyncP)
2038Conclude a request to fetch file data, as commenced by an StartRXAFS
2039FetchData() invocation. By the time this routine has been called, all of the
2040desired data has been read off the data stream. The status fields for the file
2041from which the data was read are stored in a fidStatP. If the file was from a
2042read/write volume, its callback information is placed in a callBackP.
2044Rx call information to the related File Server is contained in a rxCallP.
2045Volume version information is returned for synchronization purposes in a
2048EACCES The caller does not have the necessary access rights. EIO Given file
2049could not be opened or statted on the File Server, or there was an error
2050reading the given data off the File Server's disk.
2051\n -31 An Rx write into the stream ended prematurely.
2053 \subsubsection sec5-1-4-3 Section 5.1.4.3: StartRXAFS StoreData - Begin
2054a request to store file data
2057int StartRXAFS StoreData(IN struct rx call *a rxCallP,
2058 IN AFSFid *a fidToStoreP,
2059 IN reStatus *a fidStatusP,
2060 IN AFSStolong a offset,
2061 IN
long a lenInBytes,
2062 IN
long a fileLenInBytes)
2065Begin a request to write a lenInBytes of data starting at
byte offset a offset
2066to the file identified by a fidToStoreP, causing that file's length to become a
2067fileLenInBytes bytes. After successful completion of this call, the data stream
2068will be ready to begin accepting the actual data being written.
2070Rx call information to the related File Server is contained in a rxCallP.
2072---No error codes generated.
2074 \subsubsection sec5-1-4-4 Section 5.1.4.4: EndRXAFS StoreData -
2075Conclude a request to store file data
2078int EndRXAFS StoreData(IN struct rx call *a rxCallP,
2079 OUT AFSFetchStatus *a fidStatP,
2080 OUT AFSCallBack *a callBackP,
2081 OUT AFSVolSync *a volSyncP)
2084Conclude a request to store file data, as commenced by a StartRXAFS StoreData()
2085invocation. By the time this routine has been called, all of the file data has
2086been inserted into the data stream. The status fields for the file to which the
2087data was written are stored in a fidStatP. All existing callbacks to the given
2088file are broken before the store concludes.
2090Rx call information to the related File Server is contained in a rxCallP.
2091Volume version information is returned for synchronization purposes in a
2094EACCES The caller does not have the necessary access rights.
2095\n EISDIR The file being written to is a symbolic link.
2096\n ENOSPEC A write to the File Server's file on local disk failed.
2097\n -32 A
short read was encountered by the File Server on the data stream.
2099 \subsection sec5-1-5 Section 5.1.5: Example of Streamed Function Call
2102 \subsubsection sec5-1-5-1 Section 5.1.5.1: Preface
2105The following code fragment is offered as an example of how to use the streamed
2106File Server RPC calls. In this case, a client fetches some amount of data from
2107the given File Server and writes it to a local file it uses to cache the
2108information. For simplicity, many issues faced by a true application programmer
2109are not addressed here. These issues include locking, managing file chunking,
2110data version number mismatches, volume location, Rx connection management,
2111defensive programming (e.g., checking parameters before using them),
2112client-side cache management algorithms, callback management, and full error
2113detection and recovery. Pseudocode is incorporated when appropriate to keep the
2114level of detail reasonable. For further descriptions of some of these details
2115and issues, the reader is referred to such companion documents as AFS-3
2116Programmer's Reference: Specification for the Rx Remote Procedure Call
2117Facility, AFS-3 Programmer's Reference:Volume Server/Volume Location Server
2118Interface, and AFS-3 Programmer's Reference: Architectural Overview.
2120A discussion of the methods used within the example code fragment follows
2121immediately afterwards in Section 5.1.5.3.
2123 \subsubsection sec5-1-5-2 Section 5.1.5.2: Code Fragment Illustrating
2129struct myConnInfo *connP;
2130struct rx_call *rxCallP;
2131struct AFSFid *afsFidP;
2142rxCallP = rx_NewCall(connP->rxConnP);
2143code = StartRXAFS_FetchData( rxCallP,
2149 bytesRead = rx_Read(rxCallP, &bytesFromFS,
sizeof(
long));
2150 if (bytesRead !=
sizeof(
long)) ExitWithError(SHORT_RX_READ);
2151 bytesFromFS = ntohl(bytesFromFS);
2152 xmitBuffer = malloc(FETCH_BUFF_BYTES);
2153 lclFid = open(CacheFileName, O_RDWR, mode);
2154 pos = lseek(lclFid, offsetBytes, L_SET);
2155 while (bytesToFetch > 0) {
2156 currReadBytes = (bytesToFetch > FETCH_BUFF_BYTES) ?
2157 FETCH_BUFF_BYTES : bytesToFetch;
2158 bytesRead = rx_Read(rxCallP, fetchBuffP, currReadBytes);
2159 if (bytesRead != currReadBytes) ExitWithError(SHORT_RX_READ);
2160 code = write(lclFid, fetchBuffP, currReadBytes);
2161 if (code) ExitWithError(LCL_WRITE_FAILED);
2162 bytesToFetch -= bytesRead;
2165}
else ExitWithError(code);
2166code = EndRXAFS_FetchData( rxCallP,
2170 code = rx_EndCall(rxCallP, code);
2174 \subsubsection sec5-1-5-3 Section 5.1.5.3: Discussion and Analysis
2177The opening assumption in
this discussion is that all the information required
2178to
do the fetch has already been set up. These mandatory variables are the
2179client-side connection information
for the File Server hosting the desired
2180file, the corresponding AFS file identifier, the
byte offset into the file, the
2181number of bytes to fetch, and the identifier
for the local file serving as a
2184Given the Rx connection information stored in the client
's connP record, rx
2185NewCall() is used to create a new Rx call to handle this fetch operation. The
2186structure containing this call handle is placed into rxCallP. This call handle
2187is used immediately in the invocation of StartRXAFS FetchData(). If this setup
2188call fails, the fragment exits. Upon success, though, the File Server will
2189commence writing the desired data into the Rx data stream. The File Server
2190first writes a single longword onto the stream announcing to the client how
2191many bytes of data will actually follow. The fragment reads this number with
2192its first rx Read() call. Since all Rx stream data is written in network byte
2193order, the fragment translates the byte count to its own host byte order first
2194to properly interpret it. Once the number of bytes to appear on the stream is
2195known, the client code proceeds to open the appropriate cache file on its own
2196local disk and seeks to the appropriate spot within it. A buffer into which the
2197stream data will be placed is also created at this time.
2199The example code then falls into a loop where it reads all of the data from the
2200File Server and stores it in the corresponding place in the local cache file.
2201For each iteration, the code decides whether to read a full buffer's worth or
2202the remaining number of bytes, whichever is smaller. After all the data is
2203pulled off the Rx stream, the local cache file is closed. At
this point, the
2204example finishes off the RPC by calling EndRXAFS FetchData(). This gathers in
2205the required set of OUT parameters, namely the status fields
for the file just
2206fetched, callback and volume synchronization information, and the overall error
2207code
for the streamed routine. The Rx call created to perform the fetch is then
2208terminated and cleaned up by invoking rx EndCall().
2210 \subsection sec5-1-6 Section 5.1.6: Required Caller Functionality
2213The AFS File Server RPC
interface was originally designed to interact only with
2214Cache Manager agents, and thus made some assumptions about its callers. In
2215particular, the File Server expected that the agents calling it would
2216potentially have stored callback state on file system objects, and would have
2217to be periodically pinged in order to garbage-collect its records, removing
2218information on dead client machines. Thus, any entity making direct calls to
2219this interface must mimic certain Cache Manager actions, and respond to certain
2220Cache Manager RPC interface calls.
2222To be safe, any application calling the File Server RPC interface directly
2223should export the entire Cache Manager RPC interface. Realistically, though, it
2224will only need to provide stubs for the three calls from this interface that
2225File Servers know how to make: RXAFSCB InitCallBackState(), RXAFSCB Probe() and
2226RXAFSCB CallBack(). The very first File Server call made by this application
2227will prompt the given File Server to call RXAFSCB InitCallBackState(). This
2228informs the application that the File Server has no record of its existence and
2229hence this "Cache Manager" should clear all callback information for that
2230server. Once the application responds positively to the inital RXAFSCB
2231InitCallBackState(), the File Server will treat it as a bona fide,
2232fully-fledged Cache Manager, and probe it every so often with RXAFSCB Probe()
2233calls to make sure it is still alive.
2235 \section sec5-2 Section 5.2: Signal Interface
2238While the majority of communication with AFS File Servers occurs over the RPC
2239interface, some important operations are invoked by sending unix signals to the
2240process. This section describes the set of signals recognized by the File
2241Server and the actions they trigger upon receipt, as summarized below:
2242\li SIGQUIT: Shut down a File Server.
2243\li SIGTSTP: Upgrade debugging output level.
2244\li SIGHUP: Reset debugging output level.
2245\li SIGTERM: Generate debugging output specifically concerning open files
2246within the File Server process.
2248 \subsection sec5-2-1 Section 5.2.1: SIGQUIT: Server Shutdown
2251Upon receipt of this signal, the File Server shuts itself down in an orderly
2252fashion. It first writes a message to the console and to its log file
2253(/usr/afs/logs/FileLog) stating that a shutdown has commenced. The File Server
2254then flushes all modified buffers and prints out a set of internal statistics,
2255including cache and disk numbers. Finally, each attached volume is taken
2256offline, which means the volume header is written to disk with the appropriate
2259In typical usage, human operators do not send the SIGQUIT signal directly to
2260the File Server in order to affect an orderly shutdown. Rather, the BOS Server
2261managing the server processes on that machine issues the signal upon receipt of
2262a properly-authorized shutdown RPC request.
2264 \subsection sec5-2-2 Section 5.2.2: SIGTSTP: Upgrade Debugging Level
2267Arrival of a SIGTSTP signal results in an increase of the debugging level used
2268by the File Server. The routines used for writing to log files are sensitive to
2269this debugging level, as recorded in the global LogLevel variable.
2270Specifically, these routines will only generate output if the value of LogLevel
2271is greater than or equal to the value of its threshold parameter. By default,
2272the File Server sets LogLevel to zero upon startup. If a SIGTSTP signal is
2273received when the debugging level is zero, it will be bumped to 1. If the
2274signal arrives when the debugging level is positive, its value will be
2275multiplied by 5. Thus, as more SIGTSTPs are received, the set of debugging
2276messages eligible to be delivered to log files grows.
2278Since the SIGTSTP signal is not supported under IBM's AIX 2.2.1 operating
2279system, this form of debugging output manipulation is not possible on those
2282 \subsection sec5-2-3 Section 5.2.3: SIGHUP: Reset Debugging Level
2285Receiving a SIGHUP signal causes a File Server to reset its debugging level to
2286zero. This effectively reduces the set of debugging messages eligible for
2287delivery to log files to a bare minimum. This signal is used in conjunction
2288with SIGTSTP to manage the verbosity of log information.
2290Since the SIGHUP signal is not supported under IBM's AIX 2.2.1 operating
2291system, this form of debugging output manipulation is not possible on those
2294 \subsection sec5-2-4 Section 5.2.4: SIGTERM: File Descriptor Check
2297Receipt of a SIGTERM signal triggers a routine which sweeps through the given
2298File Server's unix file descriptors. For each possible unix fid slot, an
2299fstat() is performed on that descriptor, and the particulars of each open file
2300are printed out. This action is designed solely for debugging purposes.
2302 \section sec5-3 Section 5.3: Command Line Interface
2305Another interface exported by the File Server is the set of command line
2306switches it accepts. Using these switches, many server parameters and actions
2307can be set. Under normal conditions, the File Server process is started up by
2308the BOS Server on that machine, as described in AFS-3 Programmer's Reference:
2309BOS Server Interface. So, in order to utilize any combination of these
2310command-line options, the system administrator must define the File Server
2311bnode in such a way that these parameters are properly included. Note that the
2312switch names must be typed exactly as listed, and that abbreviations are not
2313allowed. Thus, specifying -b 300 on the command line is unambiguous, directing
2314that 300 buffers are to be allocated. It is not an abbreviation for the -banner
2315switch, asking that a message is to be printed to the console periodically.
2317A description of the set of currently-supported command line switches follows.
2318\li -b <# buffers> Choose the number of 2,048-byte data buffers to allocate at
2319system startup. If this switch is not provided, the File Server will operate
2320with 70 such buffers by default.
2321\li -banner This switch instructs the File Server to print messages to the
2322console every 10 minutes to demonstrate it is still running correctly. The text
2323of the printed message is: File Server is running at <time>.
2324\li -cb <# callbacks stored> Specify the maximum number of callback records
2325stored simultaneously by the File Server. The default pool size is 20,000
2327\li -d <debug level> Set the debugging output level at which File Server runs
2328to the value provided. Specifically, the LogLevel global variable is set to the
2329given value (See Section 5.2.2). If this switch is not provided, the default
2330initial File Server debugging level is set to zero, producing the minimal
2331debugging output to the log files.
2332\li -k <stack size> Set the stack size to provide server LWPs upon creation,
2333measured in 1,024-byte blocks. The default LWP stack size is 24 blocks, or
2335\li -l <large (directory) vnodes> Select the number of "large" vnodes the File
2336Server will cache. These vnodes are suitable for recording information about
2337AFS directories. The extra space in the vnode allows ACL information to be
2338stored along with the directory. The default allocation value is 200 directory
2340\li -pctspare <percent overrun blocks past quota> Similar to the -spare switch,
2341except that the number of allowable overrun blocks is expressed as a percentage
2342of the given volume's quota. Note: this switch cannot be used in combination
2343with the -spare switch.
2344\li -rxdbg Instruct the File Server to open a file named rx dbg in the current
2345directory, into which the Rx package will write general debugging information.
2346If the file is already open (due to the appearance of the -rxdbge switch
2347earlier in the command line), this results in a no-op.
2348\li -rxdbge Instruct the File Server to open a file named rx dbg in the current
2349directory, into which the Rx package will write debugging information related
2350to its event-scheduling activities. If the file is already open (due to the
2351appearance of the -rxdbg switch earlier in the command line), this results in a
2353\li -rxpck <# packets> Set the number of extra Rx packet buffers to hold in
2354reserve. These pre-allocated buffers assist in responding to spikes in network
2355traffic demands. By default, 100 such packet buffers are maintained.
2356\li -s <small (file) vnodes> Select the number of "small" vnodes the File
2357Server will cache. These vnodes are suitable for recording information about
2358non-directory files. As with directory vnodes, the File Server will allocate
2359200 small vnodes by default.
2360\li -spare <# overrun blocks to allow> Tell the File Server to allow users
2361performing a store operation to overrun the host volume's disk quota by a
2362certain number of (1,024-byte) blocks. In other words, the first store
2363resulting in a quota overrun will be allowed to succeed if and only if it uses
2364no more than these many blocks beyond the quota. Further store operations will
2365be rejected until the volume's storage is once again reduced below quota. By
2366default, overruns of 1,024 blocks of 1,024 bytes each (1 megabyte total) are
2367tolerated. Note: this switch cannot be used in combination with the -pctspare
2369\li -w <callback wait interval in seconds> This switch determines how often the
2370File Server periodic daemon lightweight processes run. Among other things,
2371these daemon LWPs check on the validity of callback records, keep disk usage
2372statistics up to date, and check the health of the various client machines that
2373have previously interacted with the File Server. For a full description of
2374these daemon LWPs, consult Section 2.3. The associated argument specifies the
2375number of seconds to sleep between daemon invocations. By default, these
2376periodic daemons run every 300 seconds (5 minutes).
2378 \page chap6 Chapter 6: Cache Manager Interfaces
2380 \section sec6-1 Section 6.1: Overview
2383There are several interfaces offered by the Cache Manager, allowing clients to
2384access the files stored by the community of AFS File Servers, to configure the
2385Cache Manager's behavior and resources, to store and retrieve authentication
2386information, to specify the location of community Authentication Server and
2387Volume Location Server services, and to observe and debug the Cache Manager's
2388state and actions. This chapter will cover the following five interfaces to the
2390\li ioctl(): The standard unix ioctl() system call has been extended to
2391include more operations, namely waiting until data stores to a File Server
2392complete before returning to the caller (VIOCCLOSEWAIT) and getting the name of
2393the cell in which an open file resides (VIOCIGETCELL).
2394\li pioctl(): An additional system call is provided through which
2395applications can access operations specific to AFS, which are often tied to a
2396particular pathname. These operations include Access Control List (ACL) and
2397mount point management, Kerberos ticket management, cache configuration, cell
2398configuration, and status of File Servers.
2399\li RPC: Interface by which outside servers and investigators can
2400manipulate the Cache Manager. There are two main categories of routines:
2401callback management, typically called by the File Server, and
2402debugging/statistics, called by programs such as cmdebug and via the xstat
2403user-level library for collection of extended statistics.
2404\li Files: Much of the Cache Manager's configuration information, as well
2405as its view of the AFS services available from the outside world, is obtained
2406from parsing various files. One set of these files is typically located in
2407/usr/vice/etc, and includes CellServDB, ThisCell, and cacheinfo. Another set is
2408usually found in /usr/vice/cache, namely CacheItems, VolumeItems, and AFSLog.
2409\li Mariner: This is the interface by which file transfer activity between
2410the Cache Manager and File Servers may be monitored. Specifically, it is used
2411to monitor the names of the files and directories being fetched and/or stored
2414Another important component not described in this document is the afsd program.
2415It is afsd's job to initialize the Cache Manager on a given machine and to
2416start up its related daemon threads. It accepts a host of configuration
2417decisions via its command-line interface. In addition, it parses some of the
2418information kept in the configuration files mentioned above and passes that
2419information to the Cache Manager. The reader may find a full description of
2420afsd in the AFS 3.0 Command Reference Manual[2].
2422 \section sec6-2 Section 6.2: Definitions
2425This section defines data structures that are used by the pioctl() calls.
2427 \subsection sec6-2-1 Section 6.2.1: struct VenusFid
2430The Cache Manager is the sole active AFS agent aware of the cellular
2431architecture of the system. Since AFS file identifiers are not guaranteed to be
2432unique across cell boundaries, it must further qualify them for its own
2433internal bookkeeping. The struct VenusFid provides just such additional
2434qualification, attaching the Cache Manager's internal cell identifier to the
2437\li long Cell - The internal identifier for the cell in which the file resides.
2438\li struct ViceFid Fid - The AFS file identifier within the above cell.
2440 \subsection sec6-2-2 Section 6.2.2: struct ClearToken
2443This is the clear-text version of an AFS token of identity. Its fields are
2444encrypted into the secret token format, and are made easily available to the
2445Cache Manager in this structure.
2447\li long AuthHandle - Key version number.
2448\li char HandShakeKey[8] - Session key.
2449\li long ViceId - Identifier for the AFS principal represented by this token.
2450\li long BeginTimestamp - Timestamp of when this token was minted, and hence
2452\li long EndTimestamp - Timestamp of when this token is considered to be
2453expired, and thus disregarded.
2455 \section sec6-3 Section 6.3: ioctl() Interface
2458The standard unix ioctl() system call performs operations on file system
2459objects referenced with an open file descriptor. AFS has augmented this system
2460call with two additional operations, one to perform "safe stores", and one to
2461get the name of the cell in which a file resides. A third ioctl() extension is
2462now obsolete, namely aborting a store operation currently in progress.
2464 \subsection sec6-3-1 Section 6.3.1: VIOCCLOSEWAIT
2467[Opcode 1] Normally, a client performing a unix close() call on an AFS file
2468resumes once the store operation on the given file data to the host File Server
2469has commenced but before it has completed. Thus, it is possible that the store
2470could actually fail (say, because of network partition or server crashes)
2471without the client's knowledge. This new ioctl opcode specifies to the Cache
2472Manager that all future close() operations will wait until the associated store
2473operation to the File Server has completed fully before returning.
2475 \subsection sec6-3-2 Section 6.3.2: VIOCABORT
2478[Opcode 2] This ioctl() extension is now obsolete. This call results in a noop.
2479The original intention of this call was to allow a store operation currently in
2480progress to a File Server on the named fid to be aborted.
2482 \subsection sec6-3-3 Section 6.3.3: VIOIGETCELL
2485[Opcode 3] Get the name of the cell in which the given fid resides. If the file
2486is not an AFS file, then ENOTTY is returned. The output buffer specified in the
2487data area must be large enough to hold the null-terminated string representing
2488the file's cell, otherwise EFAULT is returned. However, an out size value of
2489zero specifies that the cell name is not to be copied into the output buffer.
2490In this case, the caller is simply interested in whether the file is in AFS,
2491and not its exact cell of residence.
2493 \section sec6-4 Section 6.4: pioctl() Interface
2495 \subsection sec6-4-1 Section 6.4.1: Introduction
2498There is a new unix system call, pioctl(), which has been defined especially to
2499support the AFS Cache Manager. Its functional definition is as follows:
2501int afs syscall pioctl(IN char *a pathP,
2503 IN struct ViceIoctl *a paramsP,
2504 IN int a followSymLinks)
2507This new call is much like the standard ioctl() call, but differs in that the
2508affected file (when applicable) is specified by its path, not by a file
2509descriptor. Another difference is the fourth parameter, a followSymLinks,
2510determines which file should be used should a pathP be a symbolic link. If a
2511followSymLinks be set to 1, then the symbolic link is followed to its target,
2512and the pioctl() is applied to that resulting file. If a followSymLinks is set
2513to 0, then the pioctl() applies to the symbolic link itself.
2515Not all pioctl() calls affect files. In those cases, the a pathP parameter
2516should be set to a null pointer. The second parameter to pioctl(), a opcode,
2517specifies which operation is to be performed. The opcode for each of these
2518operations is included in the text of the description. Note that not all
2519pioctl() opcodes are in use. These unused values correspond to obsolete
2522The descriptions that follow identify some of the possible error codes for each
2523pioctl() opcode, but do not offer a comprehensive lists. All pioctl() calls
2524return 0 upon success.
2526The rest of this section proceeds to describe the individual opcodes available.
2527First, though, one asymmetry in this opcode set is pointed out, namely that
2528while various operations are defined on AFS mount points, there is no direct
2529way to create a mount point.
2531This documentation partitions the pioctl() into several groups:
2532\li Volume operations
2533\li File Server operations
2535\li Authentication Operations
2538\li Miscellaneous operations
2541For all pioctl()s, the fields within the a paramsP parameter will be referred
2542to directly. Thus, the values of in, in size, out, and out size are discussed,
2543rather than the settings for a paramsP->in, a paramsP->in size, a paramsP->out,
2544and a paramsP->out size.
2546For convenience of reference, a list of the actively-supported pioctl()s, their
2547opcodes, and brief description appears (in opcode order) below.
2548\li [1] VIOCSETAL : Set the ACL on a directory
2549\li [2] VIOCGETAL : Get the ACL for a directory
2550\li [3] VIOCSETTOK : Set the caller's token for a cell
2551\li [4] VIOCGETVOLSTAT : Get volume status
2552\li [5] VIOCSETVOLSTAT : Set volume status
2553\li [6] VIOCFLUSH : Flush an object from the cache
2554\li [8] VIOCGETTOK : Get the caller's token for a cell
2555\li [9] VIOCUNLOG : Discard authentication information
2556\li [10] VIOCCKSERV : Check the status of one or more File Servers
2557\li [11] VIOCCKBACK : Mark cached volume info as stale
2558\li [12] VIOCCKCONN : Check caller's tokens/connections
2559\li [14] VIOCWHEREIS : Find host(s) for a volume
2560\li [20] VIOCACCESS : Check caller's access on object
2561\li [21] VIOCUNPAG : See [9] VIOCUNLOG
2562\li [22] VIOCGETFID : Get fid for named object
2563\li [24] VIOCSETCACHESIZE : Set maximum cache size in blocks
2564\li [25] VIOCFLUSHCB : Unilaterally drop a callback
2565\li [26] VIOCNEWCELL : Set cell service information
2566\li [27] VIOCGETCELL : Get cell configuration entry
2567\li [28] VIOCAFS DELETE MT PT : Delete a mount point
2568\li [29] VIOC AFS STAT MT PT : Get the contents of a mount point
2569\li [30] VIOC FILE CELL NAME : Get cell hosting a given object
2570\li [31] VIOC GET WS CELL : Get caller's home cell name
2571\li [32] VIOC AFS MARINER HOST : Get/set file transfer monitoring output
2572\li [33] VIOC GET PRIMARY CELL : Get the caller's primary cell
2573\li [34] VIOC VENUSLOG : Enable/disable Cache Manager logging
2574\li [35] VIOC GETCELLSTATUS : Get status info for a cell entry
2575\li [36] VIOC SETCELLSTATUS : Set status info for a cell entry
2576\li [37] VIOC FLUSHVOLUME : Flush cached data from a volume
2577\li [38] VIOC AFS SYSNAME : Get/set the @sys mapping
2578\li [39] VIOC EXPORTAFS : Enable/disable NFS/AFS translation
2579\li [40] VIOCGETCACHEPARAMS : Get current cache parameter values
2581 \subsection sec6-4-2 Section 6.4.2: Mount Point Asymmetry
2584There is an irregularity which deserves to be mentioned regarding the pioctl()
2585interface. There are pioctl() operations for getting information about a mount
2586point (VIOC AFS STAT MT PT) and for deleting a mount point (VIOC AFS DELETE MT
2587PT), but no operation for creating mount points. To create a mount point, a
2588symbolic link obeying a particular format must be created. The first character
2589must be either a "%" or a "#", depending on the type of mount point being
2590created (see the discussion in Section 6.4.4.4). If the mount point carries the
2591name of the cell explicitly, the full cell name will appear next, followed by a
2592colon. In all cases, the next portion of the mount point is the volume name. By
2593convention, the last character of a mount point must always be a period (".").
2594This trailing period is not visible in the output from fs lsmount.
2596 \subsection sec6-4-3 Section 6.4.3: Volume Operations
2599There are several pioctl() opcodes dealing with AFS volumes. It is possible to
2600get and set volume information (VIOCGETVOLSTAT, VIOCSETVOLSTAT), discover which
2601volume hosts a particular file system object (VIOCWHEREIS), remove all objects
2602cached from a given volume (VIOC FLUSHVOLUME), and revalidate cached volume
2603information (VIOCCKBACK).
2605 \subsubsection sec6-4-3-1 Section 6.4.3.1: VIOCGETVOLSTAT: Get volume
2609[Opcode 4] Fetch information concerning the volume that contains the file
2610system object named by a pathP. There is no other input for this call, so in
2611size should be set to zero. The status information is placed into the buffer
2612named by out, if out size is set to a value of sizeof(struct VolumeStatus) or
2613larger. Included in the volume information are the volume's ID, quota, and
2614number of blocks used in the volume as well as the disk partition on which it
2615resides. Internally, the Cache Manager calls the RXAFS GetVolumeInfo() RPC (See
2616Section 5.1.3.14) to fetch the volume status.
2618Among the possible error returns, EINVAL indicates that the object named by a
2619pathP could not be found.
2621 \subsubsection sec6-4-3-2 Section 6.4.3.2: VIOCSETVOLSTAT: Set volume
2625[Opcode 5] Set the status fields for the volume hosting the file system object
2626named by a pathP. The first object placed into the input buffer in is the new
2627status image. Only those fields that may change, namely MinQuota and MaxQuota
2628fields, are interpreted upon receipt by the File Server, and are set to the
2629desired values. Immediately after the struct VolumeStatus image, the caller
2630must place the null-terminated string name of the volume involved in the input
2631buffer. New settings for the offline message and MOTD (Message of the Day)
2632strings may appear after the volume name. If there are no changes in the
2633offline and/or MOTD messages, a null string must appear for that item. The in
2634size parameter must be set to the total number of bytes so inserted, including
2635the nulls after each string. Internally, the Cache Manager calls the RXAFS
2636SetVolumeStatus() RPC (See Section 5.1.3.16) to store the new volume status.
2638Among the possible error returns, EINVAL indicates that the object named by a
2639pathP could not be found.
2641 \subsubsection sec6-4-3-3 Section 6.4.3.3: VIOCWHEREIS: Find the
2642server(s) hosting the pathname's volume
2645[Opcode 14] Find the set of machines that host the volume in which the file
2646system object named by a pathP resides. The input buffer in is not used by this
2647call, so in size should be set to zero. The output buffer indicated by out is
2648filled with up to 8 IP addresses, one for each File Server hosting the
2649indicated volume. Thus, out size should be set to at least (8*sizeof(long)).
2650This group of hosts is terminated by the first zeroed IP address that appears
2651in the list, but under no circumstances are more than 8 host IP addresses
2654Among the possible error returns is EINVAL, indicating that the pathname is not
2655in AFS, hence is not contained within a volume. If ENODEV is returned, the
2656associated volume information could not be obtained.
2658 \subsubsection sec6-4-3-4 Section 6.4.3.4: VIOC FLUSHVOLUME: Flush all
2659data cached from the pathname's volume
2662[Opcode 37] Determine the volume in which the file system object named by a
2663pathP resides, and then throw away all currently cached copies of files that
2664the Cache Manager has obtained from that volume. This call is typically used
2665should a user suspect there is some cache corruption associated with the files
2668 \subsubsection sec6-4-3-5 Section 6.4.3.5: VIOCCKBACK: Check validity
2669of all cached volume information
2672[Opcode 11] Ask the Cache Manager to check the validity of all cached volume
2673information. None of the call's parameters are referenced in this call, so a
2674pathP and in should be set to the null pointer, and in size and out size should
2677This operation is performed in two steps:
2678\li 1 The Cache Manager first refreshes its knowledge of the root volume,
2679usually named root.afs. On success, it wakes up any of its own threads waiting
2680on the arrival of this information, should it have been previously unreachable.
2681This typically happens should the Cache Manager discover in its startup
2682sequence that information on the root volume is unavailable. Lacking this
2683knowledge at startup time, the Cache Manager settles into a semi-quiescent
2684state, checking every so often to see if volume service is available and thus
2685may complete its own initialization.
2686\li 2 Each cached volume record is flagged as being stale. Any future attempt
2687to access information from these volumes will result in the volume record's
2688data first being refreshed from the Volume Location Server.
2690 \subsection sec6-4-4 Section 6.4.4: File Server Operations
2693One group of pioctl() opcodes is aimed at performing operations against one or
2694more File Servers directly. Specifically, a caller may translate a pathname
2695into the corresponding AFS fid (VIOCGETFID), unilaterally discard a set of
2696callback promises (VIOCFLUSHCB), get status on mount points (VIOC AFS STAT MT
2697PT), delete unwanted mount points (VIOC AFS DELETE MT PT), and check the health
2698of a group of File Servers(VIOCCKSERV).
2700 \subsubsection sec6-4-4-1 Section 6.4.4.1: VIOCGETFID: Get augmented
2701fid for named file system object
2704[Opcode 22] Return the augmented file identifier for the file system object
2705named by a pathP. The desired struct VenusFid is placed in the output buffer
2706specified by out. The output buffer size, as indicated by the out size
2707parameter, must be set to the value of sizeof(struct VenusFid) or greater. The
2708input buffer is not referenced in this call, so in should be set to the null
2709pointer and in size set to zero.
2711Among the possible error returns, EINVAL indicates that the object named by a
2714 \subsubsection sec6-4-4-2 Section 6.4.4.2: VIOCFLUSHCB: Unilaterally
2718[Opcode 25] Remove any callback information kept by the Cache Manager on the
2719file system object named by a pathP. Internally, the Cache Manager executes a
2720call to the RXAFS GiveUpCallBacks() RPC (See Section 5.1.3.13) to inform the
2721appropriate File Server that it is being released from its particular callback
2722promise. Note that if the named file resides on a read-only volume, then the
2723above call is not made, and success is returned immediately. This optimization
2724is possible because AFS File Servers do not grant callbacks on files from
2727Among the possible error returns is EINVAL, which indicates that the object
2728named by a pathP was not found.
2730 \subsubsection sec6-4-4-3 Section 6.4.4.3: VIOC AFS DELETE MT PT:
2734[Opcode 28] Remove an AFS mount point. The name of the directory in which the
2735mount point exists is specified by a pathP, and the string name of the mount
2736point within this directory is provided through the in parameter. The input
2737buffer length, in size, is set to the length of the mount point name itself,
2738including the trailing null. The output buffer is not accessed by this call, so
2739out should be set to the null pointer and out size to zero.
2741One important note is that the a followSymLinks argument must be set to zero
2742for correct operation. This is counter-intuitive, since at first glance it
2743seems that a symbolic link that resolves to a directory should be a valid
2744pathname parameter. However, recall that mount points are implemented as
2745symbolic links that do not actually point to another file system object, but
2746rather simply contain cell and volume information (see the description in
2747Section 6.4.2). This "special" symbolic link must not be resolved by the
2748pioctl(), but rather presented as-is to the Cache Manager, which then properly
2749interprets it and generates a reference to the given volume's root directory.
2750As an unfortunate side-effect, a perfectly valid symbolic link referring to a
2751directory will be rejected out of hand by this operation as a value for the a
2754Among the possible error returns, EINVAL reports that the named directory was
2755not found, and ENOTDIR indicates that the pathname contained within a pathP is
2758 \subsubsection sec6-4-4-4 Section 6.4.4.4: VIOC AFS STAT MT PT: Get the
2759contents of a mount point
2762[Opcode 29] Return the contents of the given mount point. The directory in
2763which the mount point in question resides is provided via the a pathP argument,
2764and the in buffer contains the name of the mount point object within this
2765directory. As usual, in size is set to the length of the input buffer,
2766including the trailing null. If the given object is truly a mount point and the
2767out buffer is large enough (its length appears in out size), the mount point's
2768contents are stored into out.
2770The mount point string returned obeys a stylized format, as fully described in
2771Section 5.6.2 of the AFS 3.0 System Administrator's Guide[1]. Briefly, a
2772leading pound sign ("#") indicates a standard mount point, inheriting the
2773read-only or read-write preferences of the mount point's containing volume. On
2774the other hand, a leading percent sign ("%") advises the Cache Manager to cross
2775into the read-write version of the volume, regardless of the existence of
2776read-only clones. If a colon (":") separator occurs, the portion up to the
2777colon itself denotes the fully-qualified cell name hosting the volume. The rest
2778of the string is the volume name itself.
2780Among the possible error codes is EINVAL, indicating that the named object is
2781not an AFS mount point. Should the name passed in a pathP be something other
2782than a directory, then ENOTDIR is returned.
2784 \subsubsection sec6-4-4-5 Section 6.4.4.5: VIOCCKSERV: Check the status
2785of one or more File Servers
2788[Opcode 10] Check the status of the File Servers that have been contacted over
2789the lifetime of the Cache Manager. The a pathP parameter is ignored by this
2790call, so it should be set to the null pointer. The input parameters as
2791specified by in are completely optional. If something is placed in the input
2792buffer, namely in size is not zero, then the first item stored there is a
2793longword used as a bit array of flags. These flags carry instructions as to the
2794domain and the "thoroughness" of this check.
2796Only the settings of the least-significant two bits are recognized. Enabling
2797the lowest bit tells the Cache Manager not to ping its list of servers, but
2798simply report their status as contained in the internal server records.
2799Enabling the next-higher bit limits the search to only those File Servers in a
2800given cell. If in size is greater than sizeof(long),a null-terminated cell name
2801string follows the initial flag array, specifying the cell to check. If this
2802search bit is set but no cell name string follows the longword of flags, then
2803the search is restricted to those servers contacted from the same cell as the
2806This call returns at least one longword into the output buffer out, specifying
2807the number of hosts it discovered to be down. If this number is not zero, then
2808the longword IP address for each dead (or unreachable) host follows in the
2809output buffer. At most 16 server addresses will be returned, as this is the
2810maximum number of servers for which the Cache Manager keeps information.
2812Among the possible error returns is ENOENT, indicating that the optional cell
2813name string input value is not known to the Cache Manager.
2815 \subsection sec6-4-5 Section 6.4.5: Cell Operations
2818The Cache Manager is the only active AFS agent that understands the system's
2819cellular architecture. Thus, it keeps important information concerning the
2820identities of the cells in the community, which cell is in direct
2821administrative control of the machine upon which it is running, status and
2822configuration of its own cell, and what cell-specific operations may be legally
2823executed. The following pioctl()s allow client processes to access and update
2824this cellular information. Supported operations include adding or updating
2825knowledge of a cell, including the cell overseeing the caller's machine
2826(VIOCNEWCELL), fetching the contents of a cell configuration entry
2827(VIOCGETCELL), finding out which cell hosts a given file system object (VIOC
2828FILE CELL NAME), discovering the cell to which the machine belongs (VIOC GET WS
2829CELL), finding out the caller's "primary" cell (VIOC GET PRIMARY CELL), and
2830getting/setting certain other per-cell system parameters (VIOC GETCELLSTATUS,
2833 \subsubsection sec6-4-5-1 Section 6.4.5.1: VIOCNEWCELL: Set cell
2837[Opcode 26] Give the Cache Manager all the information it needs to access an
2838AFS cell. Exactly eight longwords are placed at the beginning of the in input
2839buffer. These specify the IP addresses for the machine providing AFS
2840authentication and volume location authentication services. The first such
2841longword set to zero will signal the end of the list of server IP addresses.
2842After these addresses, the input buffer hosts the null-terminated name of the
2843cell to which the above servers belong. The a pathP parameter is not used, and
2844so should be set to the null pointer.
2846Among the possible error returns is EACCES, indicating that the caller does not
2847have the necessary rights to perform the operation. Only root is allowed to set
2848cell server information. If either the IP address array or the server name is
2849unacceptable, EINVAL will be returned.
2851 \subsubsection sec6-4-5-2 Section 6.4.5.2: VIOCGETCELL: Get cell
2855[Opcode 27] Get the i'th cell configuration entry known to the Cache Manager.
2856The index of the desired entry is placed into the in input buffer as a
2857longword, with the first legal value being zero. If there is a cell associated
2858with the given index, the output buffer will be filled with an array of 8
2859longwords, followed by a null-terminated string.
2861The longwords correspond to the list of IP addresses of the machines providing
2862AFS authentication and volume location services. The string reflects the name
2863of the cell for which the given machines are operating. There is no explicit
2864count returned of the number of valid IP addresses in the longword array.
2865Rather, the list is terminated by the first zero value encountered, or when the
2866eighth slot is filled.
2868This routine is intended to be called repeatedly, with the index starting at
2869zero and increasing each time. The array of cell information records is kept
2870compactly, without holes. A return value of EDOM indicates that the given index
2871does not map to a valid entry, and thus may be used as the terminating
2872condition for the iteration.
2874 \subsubsection sec6-4-5-3 Section 6.4.5.3: VIOC FILE CELL NAME: Get
2875cell hosting a given object
2878[Opcode 30] Ask the Cache Manager to return the name of the cell in which the
2879file system object named by a pathP resides. The input arguments are not used,
2880so in should be set to the null pointer and in size should be set to zero. The
2881null-terminated cell name string is returned in the out output buffer.
2883Among the possible error values, EINVAL indicates that the pathname provided in
2884a pathP is illegal. If there is no cell information associated with the given
2885object, ESRCH is returned.
2887 \subsubsection sec6-4-5-4 Section 6.4.5.4: VIOC GET WS CELL: Get
2888caller's home cell name
2891[Opcode 31] Return the name of the cell to which the caller's machine belongs.
2892This cell name is returned as a null-terminated string in the output buffer.
2893The input arguments are not used, so in should be set to the null pointer and
2894in size should be set to zero.
2896Among the possible error returns is ESRCH, stating that the caller's home cell
2897information was not available.
2899 \subsubsection sec6-4-5-5 Section 6.4.5.5: VIOC GET PRIMARY CELL: Get
2900the caller's primary cell
2903[Opcode 33] Ask the Cache Manager to return the name of the caller's primary
2904cell. Internally, the Cache Manager scans its user records, and the cell
2905information referenced by that record is used to extract the cell's string
2906name. The input arguments are not used, so in should be set to the null pointer
2907and in size should be set to zero. The a pathP pathname argument is not used
2908either, and should similarly be set to the null pointer. The null-terminated
2909cell name string is placed into the output buffer pointed to by out if it has
2912Among the possible error returns is ESRCH, stating that the caller's primary
2913cell information was not available.
2915 \subsubsection sec6-4-5-6 Section 6.4.5.6: VIOC GETCELLSTATUS: Get
2916status info for a cell entry
2919[Opcode 35] Given a cell name, return a single longword of status flags from
2920the Cache Manager's entry for that cell. The null-terminated cell name string
2921is expected to be in the in parameter, with in size set to its length plus one
2922for the trailing null. The status flags are returned in the out buffer, which
2923must have out size set to sizeof(long) or larger.
2925The Cache Manager defines the following output flag values for this operation:
2926\li 0x1 This entry is considered the caller's primary cell.
2927\li 0x2 The unix setuid() operation is not honored.
2928\li 0x4 An obsolete version of the Volume Location Server's database is being
2929used. While defined, this flag should no longer be set in modern systems.
2932Among the possible error returns is ENOENT, informing the caller that the Cache
2933Manager has no knowledge of the given cell name.
2935 \subsubsection sec6-4-5-7 Section 6.4.5.7: VIOC SETCELLSTATUS: Set
2936status info for a cell entry
2939[Opcode 36] Given a cell name and an image of the cell status bits that should
2940be set, record the association in the Cache Manager. The input buffer in must
2941be set up as follows. The first entry is the longword containing the cell
2942status bits to be set (see the VIOC GETCELLSTATUS description above for valid
2943flag definitions). The next entry is another longword, ignored by the Cache
2944Manager. The third and final entry in the input buffer is a null-terminated
2945string containing the name of the cell for which the status flags are to be
2948Among the possible error returns is ENOENT, reflecting the Cache Manager's
2949inability to locate its record for the given cell. Only root is allowed to
2950execute this operation, and an EACCES return indicates the caller was not
2951effectively root when the call took place.
2953 \subsection sec6-4-6 Section 6.4.6: Authentication Operations
2956The Cache Manager serves as the repository for authentication information for
2957AFS clients. Each client process belongs to a single Process Authentication
2958Group (PAG). Each process in a given PAG shares authentication information with
2959the other members, and thus has the identical rights with respect to AFS Access
2960Control Lists (ACLs) as all other processes in the PAG. As the Cache Manager
2961interacts with File Servers as a client process' agent, it automatically and
2962transparently presents the appropriate authentication information as required
2963in order to gain the access to which the caller is entitled. Each PAG can host
2964exactly one token per cell. These tokens are objects that unequivocally codify
2965the principal's identity, and are encrypted for security. Token operations
2966between a Cache Manager and File Server are also encrypted, as are the
2967interchanges between clients and the Authentication Servers that generate these
2970There are actually two different flavors of tokens, namely clear and secret.
2971The data structure representing clear tokens is described in Section 6.2.2, and
2972the secret token appears as an undifferentiated byte stream.
2974This section describes the operations involving these tokens, namely getting
2975and setting the caller's token for a particular cell (VIOCGETTOK, VIOCSETTOK),
2976checking a caller's access on a specified file system object (VIOCACCESS),
2977checking the status of caller's tokens associated with the set of File Server
2978connections maintained on its behalf (VIOCCKCONN), and discarding tokens
2979entirely (VIOCUNLOG, VIOCUNPAG). These abilities are used by such programs as
2980login, klog, unlog, and tokens, which must generate, manipulate, and/or destroy
2983 \subsubsection sec6-4-6-1 Section 6.4.6.1: VIOCSETTOK: Set the caller's
2987[Opcode 3] Store the caller's secret and clear tokens within the Cache Manager.
2988The input buffer is used to hold the following quantities, laid out end to end.
2989The first item placed in the buffer is a longword, specifying the length in
2990bytes of the secret token, followed by the body of the secret token itself. The
2991next field is another longword, this time describing the length in bytes of the
2992struct ClearToken, followed by the structure. These are all required fields.
2993The caller may optionally include two additional fields, following directly
2994after the required ones. The first optional field is a longword which is set to
2995a non-zero value if the cell in which these tokens were generated is to be
2996marked as the caller's primary cell. The second optional argument is a
2997null-terminated string specifying the cell in which these tokens apply. If
2998these two optional arguments do not appear, the Cache Manager will default to
2999using its home cell and marking the entry as non-primary. The a pathP pathname
3000parameter is not used, and thus should be set to the null pointer.
3002If the caller does not have any tokens registered for the cell, the Cache
3003Manager will store them. If the caller already has tokens for the cell, the new
3004values will overwrite their old values. Because these are stored per PAG, the
3005new tokens will thus determine the access rights of all other processes
3006belonging to the PAG.
3008Among the possible error returns is ESRCH, indicating the named cell is not
3009recognized, and EIO, if information on the local cell is not available.
3011 \subsubsection sec6-4-6-2 Section 6.4.6.2: VIOCGETTOK: Get the caller's
3015[Opcode 8] Get the specified authentication tokens associated with the caller.
3016The a pathP parameter is not used, so it should be set to the null pointer.
3017Should the input parameter in be set to a null pointer, then this call will
3018place the user's tokens for the machine's home cell in the out output buffer,
3019if such tokens exist. In this case, the following objects are placed in the
3020output buffer. First, a longword specifying the number of bytes in the body of
3021the secret token is delivered, followed immediately by the secret token itself.
3022Next is a longword indicating the length in bytes of the clear token, followed
3023by the clear token. The input parameter may also consist of a single longword,
3024indicating the index of the token desired. Since the Cache Manager is capable
3025of storing multiple tokens per principal, this allows the caller to iteratively
3026extract the full set of tokens stored for the PAG. The first valid index value
3027is zero. The list of tokens is kept compactly, without holes. A return value of
3028EDOM indicates that the given index does not map to a valid token entry, and
3029thus may be used as the terminating condition for the iteration.
3031Other than EDOM, another possible error return is ENOTCONN, specifying that the
3032caller does not have any AFS tokens whatsoever.
3034 \subsubsection sec6-4-6-3 Section 6.4.6.3: VIOCACCESS: Check caller's
3038[Opcode 20] This operation is used to determine whether the caller has specific
3039access rights on a particular file system object. A single longword is placed
3040into the input buffer, in, representing the set of rights in question. The
3041acceptable values for these access rights are listen in Section 6.4.5. The
3042object to check is named by the a pathP parameter. The output parameters are
3043not accessed, so out should be set to the null pointer, and out size set to
3045If the call returns successfully, the caller has at least the set of rights
3046denoted by the bits set in the input buffer. Otherwise, EACCESS is returned.
3048 \subsubsection sec6-4-6-4 Section 6.4.6.4: VIOCCKCONN: Check status of
3049caller's tokens/connections
3052[Opcode 12] Check whether the suite of File Server connections maintained on
3053behalf of the caller by the Cache Manager has valid authentication tokens. This
3054function always returns successfully, communicating the health of said
3055connections by writing a single longword value to the specified output buffer
3056in out. If zero is returned to the output buffer, then two things are true.
3057First, the caller has tokens for at least one cell. Second, all tokens
3058encountered upon a review of the caller's connections have been properly minted
3059(i.e., have not been generated fraudulently), and, in addition, have not yet
3060expired. If these conditions do not currently hold for the caller, then the
3061output buffer value will be set to EACCES. Neither the a pathP nor input
3062parameters are used by this call.
3064 \subsubsection sec6-4-6-5 Section 6.4.6.5: VIOCUNLOG: Discard
3065authentication information
3068[Opcode 9] Discard all authentication information held in trust for the caller.
3069The Cache Manager sweeps through its user records, destroying all of the
3070caller's associated token information. This results in reducing the rights of
3071all processes within the caller's PAG to the level of file system access
3072granted to the special system:anyuser group.
3074This operation always returns successfully. None of the parameters are
3075referenced, so they should all be set to null pointers and zeroes as
3078 \subsubsection sec6-4-6-6 Section 6.4.6.6: VIOCUNPAG: Discard
3079authentication information
3082[Opcode 21] This call is essentially identical to the VIOCUNLOG operation, and
3083is in fact implemented internally by the same code for VIOCUNLOG.
3085 \subsection sec6-4-7 Section 6.4.7: ACL Operations
3088This set of opcodes allows manipulation of AFS Access Control Lists (ACLs).
3089Callers are allowed to fetch the ACL on a given directory, or to set the ACL on
3090a directory. In AFS-3, ACLs are only maintained on directories, not on
3091individual files. Thus, a directory ACL determines the allowable accesses on
3092all objects within that directory in conjunction with their normal unix mode
3093(owner) bits. Should the a pathP parameter specify a file instead of a
3094directory, the ACL operation will be performed on the directory in which the
3097These pioctl() opcodes deal only in external formats for ACLs, namely the
3098actual text stored in an AFS ACL container. This external format is a character
3099string, composed of a descriptive header followed by some number of individual
3100principal-rights pairs. AFS ACLs actually specify two sublists, namely the
3101positive and negative rights lists. The positive list catalogues the set of
3102rights that certain principals (individual users or groups of users) have,
3103while the negative list contains the set of rights specifically denied to the
3106These external ACL representations differ from the internal format generated by
3107the Cache Manager after a parsing pass. The external format may be easily
3108generated from the internal format as follows. The header format is expressed
3109with the following printf() statement:
3111printf("%d\n%d\n", NumPositiveEntries, NumNegativeEntries);
3114The header first specifies the number of entries on the positive rights list,
3115which appear first in the ACL body. The number of entries on the negative list
3116is the second item in the header. The negative entries appear after the last
3119Each entry in the ACL proper obeys the format imposed by the following printf()
3122printf("%s\t%d\n", UserOrGroupName, RightsMask);
3125Note that the string name for the user or group is stored in an externalized
3126ACL entry. The Protection Server stores the mappings between the numerical
3127identifiers for AFS principals and their character string representations.
3128There are cases where there is no mapping from the numerical identifier to a
3129string name. For example, a user or group may have been deleted sometime after
3130they were added to the ACL and before the Cache Manager externalized the ACL
3131for storage. In this case, the Cache Manager sets UserOrGroupName to the string
3132version of the principal's integer identifier. Should the erz principal be
3133deleted from the Protection Server's database in the above scenario, then the
3134string '1019' will be stored, since it corresponded to erz's former numerical
3137The RightsMask parameter to the above call represents the set of rights the
3138named principal may exercise on the objects covered by the ACL. The following
3139flags may be OR'ed together to construct the desired access rights placed in
3143#define PRSFS_WRITE 2
3144#define PRSFS_INSERT 4
3145#define PRSFS_LOOKUP 8
3146#define PRSFS_DELETE 16
3147#define PRSFS_LOCK 32
3148#define PRSFS_ADMINISTER 64
3151 \subsubsection sec6-4-7-1 Section 6.4.7.1: VIOCSETAL: Set the ACL on a
3155[Opcode 1] Set the contents of the ACL associated with the file system object
3156named by a pathP. Should this pathname indicate a file and not a directory, the
3157Cache Manager will apply this operation to the file's parent directory. The new
3158ACL contents, expressed in their externalized form, are made available in in,
3159with in size set to its length in characters, including the trailing null.
3160There is no output from this call, so out size should be set to zero.
3161Internally, the Cache Manager will call the RXAFS StoreACL() RPC (see Section
31625.1.3.3 to store the new ACL on the proper File Server.
3164Possible error codes include EINVAL, indicating that one of three things may be
3165true: the named path is not in AFS, there are too many entries in the specified
3166ACL, or a non-existent user or group appears on the ACL.
3168 \subsubsection sec6-4-7-2 Section 6.4.7.2: VIOCGETAL: Get the ACL for a
3172[Opcode 2] Get the contents of the ACL associated with the file system object
3173named by a pathP. Should this pathname indicate a file and not a directory, the
3174Cache Manager will apply this operation to the file's parent directory. The ACL
3175contents, expressed in their externalized form, are delivered into the out
3176buffer if out size has been set to a value which indicates that there is enough
3177room for the specified ACL. This ACL string will be null-terminated. There is
3178no input to this call, so in size should be set to zero. Internally, the Cache
3179Manager will call the RXAFS FetchACL() RPC (see Section 5.1.3.1) to fetch the
3180ACL from the proper File Server.
3182Possible error codes include EINVAL, indicating that the named path is not in
3185 \subsection sec6-4-8 Section 6.4.8: Cache Operations
3188It is possible to inquire about and affect various aspects of the cache
3189maintained locally by the Cache Manager through the group of pioctl()s
3190described below. Specifically, one may force certain file system objects to be
3191removed from the cache (VIOCFLUSH), set the maximum number of blocks usable by
3192the cache (VIOCSETCACHESIZE), and ask for information about the cache's current
3193state (VIOCGETCACHEPARAMS).
3195 \subsubsection sec6-4-8-1 Section 6.4.8.1: VIOCFLUSH: Flush an object
3199[Opcode 6] Flush the file system object specified by a pathP out of the local
3200cache. The other parameters are not referenced, so they should be set to the
3201proper combination of null pointers and zeroes.
3203Among the possible error returns is EINVAL, indicating that the value supplied
3204in the a pathP parameter is not acceptable.
3206 \subsubsection sec6-4-8-2 Section 6.4.8.2: VIOCSETCACHESIZE: Set
3207maximum cache size in blocks
3210[Opcode 24] Instructs the Cache Manager to set a new maximum size (in 1 Kbyte
3211blocks) for its local cache. The input buffer located at in contains the new
3212maximum block count. If zero is supplied for this value, the Cache Manager will
3213revert its cache limit to its value at startup time. Neither the a pathP nor
3214output buffer parameters is referenced by this operation. The Cache Manager
3215recomputes its other cache parameters based on this new value, including the
3216number of cache files allowed to be dirty at once and the total amount of space
3217filled with dirty chunks. Should the new setting be smaller than the number of
3218blocks currently being used, the Cache Manager will throw things out of the
3219cache until it obeys the new limit.
3221The caller is required to be effectively running as root, or this call will
3222fail, returning EACCES. If the Cache Manager is configured to run with a memory
3223cache instead of a disk cache, this operation will also fail, returning EROF.
3225 \subsubsection sec6-4-8-3 Section 6.4.8.3: VIOCGETCACHEPARAMS: Get
3226current cache parameter values
3229[Opcode 40] Fetch the current values being used for the cache parameters. The
3230output buffer is filled with MAXGCSTATS (16) longwords, describing these
3231parameters. Only the first two longwords in this array are currently set. The
3232first contains the value of afs cacheBlocks, or the maximum number of 1 Kbyte
3233blocks which may be used in the cache (see Section 6.4.8.2 for how this value
3234may be set). The second longword contains the value of the Cache Manager's
3235internal afs blocksUsed variable, or the number of these cache blocks currently
3236in use. All other longwords in the array are set to zero. Neither the a pathP
3237nor input buffer arguments are referenced by this call.
3239This routine always returns successfully.
3241 \subsection sec6-4-9 Section 6.4.9: Miscellaneous Operations
3244There are several other AFS-specific operations accessible via the pioctl()
3245interface that don't fit cleanly into the above categories. They are described
3246in this section, and include manipulation of the socket-based Mariner file
3247trace interface (VIOC AFS MARINER HOST), enabling and disabling of the
3248file-based AFSLog output interface for debugging (VIOC VENUSLOG), getting and
3249setting the value of the special @sys pathname component mapping (VIOC AFS
3250SYSNAME), and turning the NFS-AFS translator service on and off (VIOC
3253 \subsubsection sec6-4-9-1 Section 6.4.9.1: VIOC AFS MARINER HOST:
3254Get/set file transfer monitoring output
3257[Opcode 32] This operation is used to get or set the IP address of the host
3258destined to receive Mariner output. A detailed description of the Cache Manager
3259Mariner interface may be found in Section 6.7.
3261The input buffer located at in is used to pass a single longword containing the
3262IP address of the machine to receive output regarding file transfers between
3263the Cache Manager and any File Server. If the chosen host IP address is
32640xffffffff, the Cache Manager is prompted to turn off generation of Mariner
3265output entirely. If the chosen host IP address is zero, then the Cache Manager
3266will not set the Mariner host, but rather return the current Mariner host as a
3267single longword written to the out output buffer. Any other value chosen for
3268the host IP address enables Mariner output (if it was not already enabled) and
3269causes all further traffic to be directed to the given machine.
3271This function always returns successfully.
3273 \subsubsection sec6-4-9-2 Section 6.4.9.2: VIOC VENUSLOG:
3274Enable/disable Cache Manager logging
3277[Opcode 34] Tell the Cache Manager whether to generate debugging information,
3278and what kind of debugging output to enable. The input buffer located at in is
3279used to transmit a single longword to the Cache Manager, expressing the
3280caller's wishes. Of the four bytes making up the longword, the highest byte
3281indicates the desired value for the internal afsDebug variable, enabling or
3282disabling general trace output. The next highest byte indicates the desired
3283value for the internal netDebug variable, enabling or disabling network-level
3284debugging traces. The third byte is unused, and the low-order byte represents
3285an overall on/off value for the functionality. There is a special value for the
3286low-order byte, 99, which instructs the Cache Manager to return the current
3287debugging setting as a single longword placed into the output buffer pointed to
3288by out. The a pathP parameter is not referenced by this routine.
3290Trace output is delivered to the AFSLog file, typically located in the
3291/usr/vice/etc directory. When this form of debugging output is enabled, the
3292existing AFSLog file is truncated, and its file descriptor is stored for future
3293use. When this debugging is disabled, a close() is done on the file, forcing
3294all its data to disk. For additional information on the AFSLog file for
3295collecting Cache Manager traces, please see the description in Section 6.6.2.1.
3297This call will only succeed if the caller is effectively running as root. If
3298this is not the case, an error code of EACCES is returned.
3300 \subsubsection sec6-4-9-3 Section 6.4.9.3: VIOC AFS SYSNAME: Get/set
3304[Opcode 38] Get or set the value of the special @sys pathname component
3305understood by the Cache Manager. The input buffer pointed to by in is used to
3306house a longword whose value determines whether the @sys value is being set (1)
3307or whether the current value is being fetched (0). If it is being set, then a
3308null-terminated string is expected to follow in the input buffer, specifying
3309the new value of @sys. Otherwise, if we are asking the Cache Manager for the
3310current @sys setting, a null-terminated string bearing that value will be
3311placed in the out output buffer. The a pathP parameter is not used by this
3312call, and thus should be set to a null pointer.
3314There are no special privileges required of the caller to fetch the value of
3315the current @sys mapping. However, a native caller must be running effectively
3316as root in order to successfully alter the mapping. An unauthorized attempt to
3317change the @sys setting will be ignored, and cause this routine to return
3318EACCES. This requirement is relaxed for VIOC AFS SYSNAME pioctl() calls
3319emanating from foreign file systems such as NFS and accessing AFS files through
3320the NFS-AFS translator. Each such remote caller may set its own notion of what
3321the @sys mapping is without affecting native AFS clients. Since the uid values
3322received in calls from NFS machines are inherently insecure, it is impossible
3323to enforce the fact that the caller is truly root on the NFS machine. This,
3324while any principal running on an NFS machine may change that foreign machine's
3325perception of @sys, it does not impact native AFS users in any way.
3327 \subsubsection sec6-4-9-4 Section 6.4.9.4: VIOC EXPORTAFS:
3328Enable/disable NFS/AFS translation
3331[Opcode 39] Enable or disable the ability of an AFS-capable machine to export
3332AFS access to NFS clients. Actually, this is a general facility allowing
3333exportation of AFS service to any number of other file systems, but the only
3334support currently in place is for NFS client machines. A single longword is
3335expected in the input buffer in. This input longword is partitioned into
3336individual bytes, organized as follows. The high-order byte communicates the
3337type of foreign client to receive AFS file services. There are currently two
3338legal values for this field, namely 0 for the null foreign file system and 1
3339for NFS. The next byte determines whether the Cache Manager is being asked to
3340get or set this information. A non-zero value here is interpreted as a command
3341to set the export information according to what's in the input longword, and a
3342zero-valued byte in this position instructs the Cache Manager to place a
3343longword in the output buffer out, which contains the current export settings
3344for the foreign system type specified in the high-order byte. The third input
3345byte is not used, and the lowest-order input buffer byte determines whether
3346export services for the specified system are being enabled or disabled. A
3347non-zero value will turn on the services, and a zero value will shut them down.
3348The a pathP pathname parameter is not used by this call, and the routine
3349generates output only if the export information is being requested instead of
3352The caller must be effectively running as root in order for this operation to
3353succeed. The call returns EACCES if the caller is not so authorized. If the
3354caller specifies an illegal foreign system type in the high-order byte of the
3355input longword, then ENODEV is returned. Again, NFS is the only foreign file
3356system currently supported.
3358Practically speaking, the machine providing NFS-AFS translation services must
3359enable this service with this pioctl() before any NFS client machines may begin
3360accessing AFS files. Conversely, if an administrator turns off this export
3361facility, the export code on the translator machine will immediately stop
3362responding to traffic from its active NFS clients.
3364 \section sec6-5 Section 6.5: RPC Interface
3366 \subsection sec6-5-1 Section 6.5.1: Introduction
3369This section covers the structure and workings of the Cache Manager's RPC
3370interface. Typically, these calls are made by File Server processes. However,
3371some of the calls are designed specifically for debugging programs (e.g., the
3372cmdebug facility) and for collection of statistical and performance information
3373from the Cache Manager. Any client application that makes direct calls on the
3374File Server RPC interface must be prepared to export a subset of the Cache
3375Manager RPC interface, as discussed in Section 5.1.6.
3377This section will first examine the Cache Manager's use of locks, whose
3378settings may be observed via one of the RPC interface calls. Next, it will
3379present some definitions and data structures used in the RPC interface, and
3380finally document the individual calls available through this interface.
3382 \subsection sec6-5-2 Section 6.5.2: Locks
3385The Cache Manager makes use of locking to insure its internal integrity in the
3386face of its multi-threaded design. A total of 11 locks are maintained for this
3387purpose, one of which is now obsolete and no longer used (see below). These
3388locks are strictly internal, and the Cache Manager itself is the only one able
3389to manipulate them. The current settings for these system locks are externally
3390accessible for debugging purposes via the AFSRXCB GetLock() RPC interface call,
3391as described in Section 6.5.5.4. For each lock, its index in the locking table
3392is given in the following text.
3393\li afs xvcache [Index 0]: This lock controls access to the status cache
3394entries maintained by the Cache Manager. This stat cache keeps stat()-related
3395information for AFS files it has dealt with. The stat information is kept
3396separate from actual data contents of the related file, since this information
3397may change independently (say, as a result of a unix chown() call.
3398\li afs xdcache [Index 1]: This lock moderates access to the Cache Manager's
3399data cache, namely the contents of the file system objects it has cached
3400locally. As stated above, this data cache is separate from the associated
3402\li afs xserver [Index 2]: This lock controls access to the File Server machine
3403description table, which keeps tabs on all File Servers contacted in recent
3404history. This lock thus indirectly controls access to the set of per-server RPC
3405connection descriptors the File Server table makes visible.
3406\li afs xvcb [Index 3]: This lock supervises access to the volume callback
3407information kept by the Cache Manager. This table is referenced, for example,
3408when a client decides to remove one or more callbacks on files from a given
3409volume (see the RXAFS GiveUpCallBacks() description on Section 5.1.3.13).
3410\li afs xbrs [Index 4]: This lock serializes the actions of the Cache Manager's
3411background daemons, which perform prefetching and background file storage
3413\li afs xcell [Index 5]: This lock controls the addition, deletion, and update
3414of items on the linked list housing information on cells known to the Cache
3416\li afs xconn [Index 6]: This lock supervises operations concerning the set of
3417RPC connection structures kept by the system. This lock is used in combination
3419\li afs xserver lock described above. In some internal Cache Manager code
3420paths, the File Server description records are first locked, and then the afs
3421xconn lock is used to access the associated Rx connection records. afs xuser
3422[Index 7]: This lock serializes access to the per-user structures maintained by
3424\li afs xvolume [Index 8]: This lock is used to control access to the Cache
3425Manager's volume information cache, namely the set of entries currently in
3426memory, a subset of those stably housed in the VolumeItems disk file (see
3428\li afs puttofileLock [Index 9]: This lock is obsolete, and while still defined
3429by the system is no longer used. It formerly serialized writes to a debugging
3430output interface buffer, but the internal mechanism has since been updated and
3432\li afs ftf [Index 10]: This lock is used when flushing cache text pages from
3433the machine's virtual memory tables. For each specific machine architecture on
3434which the Cache Manager runs, there is a set of virtual memory operations which
3435must be invoked to perform this operation. The result of such activities is to
3436make sure that the latest contents of new incarnations of binaries are used,
3437instead of outdated copies of previous versions still resident in the virtual
3440 \subsection sec6-5-3 Section 6.5.3: Definitions and Typedefs
3443This section documents some macro definitions and typedefs referenced by the
3444Cache Manager's RPC interface. Specifically, these definitions and typedefs are
3445used in the RXAFSCB GetXStats() and RXAFSCB XStatsVersion calls as described in
3446Sections 6.5.5.6 and 6.5.5.7.
3453const AFSCB_XSTAT_VERSION = 1;
3459const AFSCB_MAX_XSTAT_LONGS = 2048;
3460typedef long AFSCB_CollData<AFSCB_MAX_XSTAT_LONGS>;
3466const AFSCB_XSTATSCOLL_CALL_INFO = 0;
3467const AFSCB_XSTATSCOLL_PERF_INFO = 1;
3470 \subsection sec6-5-4 Section 6.5.4: Structures
3473This section documents some structures used in the Cache Manager RPC interface.
3474As with the constants and typedefs in the previous section, these items are
3475used in the RXAFSCB GetXStats() and RXAFSCB XStatsVersion calls as described in
3476Sections 6.5.5.6 and 6.5.5.7.
3478 \subsubsection sec6-5-4-1 Section 6.5.4.1: struct afs MeanStats
3481This structure may be used to collect a running average figure. It is included
3482in some of the statistics structures described below.
3484\li long average - The computed average.
3485\li long elements - The number of elements sampled for the above aveage.
3487 \subsubsection sec6-5-4-2 Section 6.5.4.2: struct afs CMCallStats
3490This structure maintains profiling information, communicating the number of
3491times internal Cache Manager functions are invoked. Each field name has a "C "
3492prefix, followed by the name of the function being watched. As this structure
3493has entries for over 500 functions, it will not be described further here.
3494Those readers who wish to see the full layout of this structure are referred to
3497The AFSCB XSTATSCOLL CALL INFO data collection includes the information in this
3500 \subsubsection sec6-5-4-3 Section 6.5.4.3: struct afs CMMeanStats
3503This is the other part of the information (along with the struct afs
3504CMCallStats construct described above) returned by the AFSCB XSTATSCOLL CALL
3505INFO data collection defined by the Cache Manager (see Section 6.5.3). It is
3506accessible via the RXAFSCB GetXStats() interface routine, as defined in Section
3509This structure represents the beginning of work to compute average values for
3510some of the extended statistics collected by the Cache Manager.
3512\li struct afs MeanStats something - Intended to collect averages for some of
3513the Cache Manager extended statistics; not yet implemented.
3515 \subsubsection sec6-5-4-4 Section 6.5.4.4: struct afs CMStats
3518This structure defines the information returned by the AFSCB XSTATSCOLL CALL
3519INFO data collection defined by the Cache Manager (see Section 6.5.3). It is
3520accessible via the RXAFSCB GetXStats() interface routine, as defined in Section
3523\li struct afs CallStats callInfo - Contains the counts on the number of times
3524each internal Cache Manager function has been called.
3525\li struct afs MeanStats something - Intended to collect averages for some of
3526the Cache Manager extended statistics; not yet implemented.
3528 \subsubsection sec6-5-4-5 Section 6.5.4.5: struct afs CMPerfStats
3531This is the information returned by the AFSCB XSTATSCOLL PERF INFO data
3532collection defined by the Cache Manager (see Section 6.5.3). It is accessible
3533via the RXAFSCB GetXStats() interface routine, as defined in Section 6.5.5.7.
3535\li long numPerfCalls - Number of performance calls received.
3536\li long epoch - Cache Manager epoch time.
3537\li long numCellsContacted - Number of cells contacted.
3538\li long dlocalAccesses - Number of data accesses to files within the local
3540\li long vlocalAccesses - Number of stat accesses to files within the local
3542\li long dremoteAccesses - Number of data accesses to files outside of the
3544\li long vremoteAccesses - Number of stat accesses to files outside of the
3546\li long cacheNumEntries - Number of cache entries.
3547\li long cacheBlocksTotal - Number of (1K) blocks configured for the AFS cache.
3548\li long cacheBlocksInUse - Number of cache blocks actively in use.
3549\li long cacheBlocksOrig - Number of cache blocks configured at bootup.
3550\li long cacheMaxDirtyChunks - Maximum number of dirty cache chunks tolerated.
3551\li long cacheCurrDirtyChunks - Current count of dirty cache chunks.
3552\li long dcacheHits - Number of data file requests satisfied by the local
3554\li long vcacheHits - Number of stat entry requests satisfied by the local
3556\li long dcacheMisses - Number of data file requests not satisfied by the local
3558\li long vcacheMisses - Number of stat entry requests not satisfied by the
3560\li long cacheFlushes - Number of files flushed from the cache.
3561\li long cacheFilesReused - Number of cache files reused.
3562\li long numServerRecords - Number of records used for storing information
3563concerning File Servers.
3564\li long ProtServerAddr - IP addres of the Protection Server used (not
3566\li long spare[32] - A set of longword spares reserved for future use.
3568 \subsection sec6-5-5 Section 6.5.5: Function Calls
3571This section discusses the Cache Manager interface calls. No special
3572permissions are required of the caller for any of these operations. A summary
3573of the calls making up the interface appears below:
3574\li RXAFSCB Probe() "Are-you-alive" call.
3575\li RXAFSCB CallBack() Report callbacks dropped by a File Server.
3576\li RXAFSCB InitCallBackState() Purge callback state from a File Server.
3577\li RXAFSCB GetLock() Get contents of Cache Manager lock table.
3578\li RXAFSCB GetCE() Get cache file description.
3579\li RXAFSCB XStatsVersion() Get version of extended statistics package.
3580\li RXAFSCB GetXStats() Get contents of extended statistics data collection.
3582 \subsubsection sec6-5-5-1 Section 6.5.5.1: RXAFSCB Probe - Acknowledge
3583that the underlying callback service is still operational
3586int RXAFSCB Probe(IN struct rx call *a rxCallP)
3589[Opcode 206] This call simply implements an "are-you-alive" operation, used to
3590determine if the given Cache Manager is still running. Any File Server will
3591probe each of the Cache Managers with which it has interacted on a regular
3592basis, keeping track of their health. This information serves an important
3593purpose for a File Server. In particular, it is used to trigger purging of
3594deceased Cache Managers from the File Server's callback records, and also to
3595instruct a new or "resurrected" Cache Manager to purge its own callback state
3596for the invoking File Server.
3598Rx call information for the related Cache Manager is contained in a rxCallP.
3600---No error codes are generated.
3602 \subsubsection sec6-5-5-2 Section 6.5.5.2: RXAFSCB CallBack - Report
3603callbacks dropped by a File Server
3606int RXAFSCB CallBack(IN struct rx call *a rxCallP,
3607 IN AFSCBFids *a fidArrayP,
3608 IN AFSCBs *a callBackArrayP)
3611[Opcode 204] Provide information on dropped callbacks to the Cache Manager for
3612the calling File Server. The number of fids involved appears in a
3613fidArrayP->AFSCBFids len, with the fids themselves located at a
3614fidArrayP->AFSCBFids val. Similarly, the number of associated callbacks is
3615placed in a callBackArrayP->AFSCBs len, with the callbacks themselves located
3616at a callBackArrayP->AFSCBs val.
3618Rx call information for the related Cache Manager is contained in a rxCallP.
3620---No error codes are generated.
3622 \subsubsection sec6-5-5-3 Section 6.5.5.3: RXAFSCB InitCallBackState -
3623Purge callback state from a File Server
3626int RXAFSCB InitCallBackState(IN struct rx call *a rxCallP)
3629[Opcode 205] This routine instructs the Cache Manager to purge its callback
3630state for all files and directories that live on the calling host. This
3631function is typically called by a File Server when it gets a request from a
3632Cache Manager that does not appear in its internal records. This handles
3633situations where Cache Managers survive a File Server, or get separated from it
3634via a temporary network partition. This also happens upon bootup, or whenever
3635the File Server must throw away its record of a Cache Manager because its
3636tables have been filled.
3638Rx call information for the related Cache Manager is contained in a rxCallP.
3640---No error codes are generated.
3642 \subsubsection sec6-5-5-4 Section 6.5.5.4: RXAFSCB GetLock - Get
3643contents of Cache Manager lock table
3646int RXAFSCB GetLock(IN struct rx call *a rxCall,
3648 OUT AFSDBLock *a lockP)
3651[Opcode 207] Fetch the contents of entry a index in the Cache Manager lock
3652table. There are 11 locks in the table, as described in Section 6.5.2. The
3653contents of the desired lock, including a string name representing the lock,
3654are returned in a lockP.
3656This call is not used by File Servers, but rather by debugging tools such as
3659Rx call information for the related Cache Manager is contained in a rxCallP.
3661The index value supplied in a index is out of range; it must be between 0 and
3664 \subsubsection sec6-5-5-5 Section 6.5.5.5: RXAFSCB GetCE - Get cache
3668int RXAFSCB GetCE(IN struct rx call *a rxCall,
3670 OUT AFSDBCacheEntry *a ceP)
3673[Opcode 208] Fetch the description for entry a index in the Cache Manager file
3674cache, storing it into the buffer to which a ceP points. The structure returned
3675into this pointer variable is described in Section 4.3.2.
3677This call is not used by File Servers, but rather by debugging tools such as
3680Rx call information for the related Cache Manager is contained in a rxCallP.
3682The index value supplied in a index is out of range.
3684 \subsubsection sec6-5-5-6 Section 6.5.5.6: RXAFSCB XStatsVersion - Get
3685version of extended statistics package
3688int RXAFSCB XStatsVersion(IN struct rx call *a rxCall,
3689 OUT long *a versionNumberP)
3692[Opcode 209] This call asks the Cache Manager for the current version number of
3693the extended statistics structures it exports (see RXAFSCB GetXStats(), Section
36946.5.5.7). The version number is placed in a versionNumberP.
3696Rx call information for the related Cache Manager is contained in a rxCallP.
3698---No error codes are generated.
3700 \subsubsection sec6-5-5-7 Section 6.5.5.7: RXAFSCB GetXStats - Get
3701contents of extended statistics data collection
3704int RXAFSCB GetXStats(IN struct rx call *a rxCall,
3705 IN long a clientVersionNumber,
3706 IN long a collectionNumber,
3707 OUT long *a srvVersionNumberP,
3709 OUT AFSCB CollData *a dataP)
3712[Opcode 210] This function fetches the contents of the specified Cache Manager
3713extended statistics structure. The caller provides the version number of the
3714data it expects to receive in a clientVersionNumber. Also provided in a
3715collectionNumber is the numerical identifier for the desired data collection.
3716There are currently two of these data collections defined: AFSCB XSTATSCOLL
3717CALL INFO, which is the list of tallies of the number of invocations of
3718internal Cache Manager procedure calls, and AFSCB XSTATSCOLL PERF INFO, which
3719is a list of performance-related numbers. The precise contents of these
3720collections are described in Section 6.5.4. The current version number of the
3721Cache Manager collections is returned in a srvVersionNumberP, and is always set
3722upon return, even if the caller has asked for a different version. If the
3723correct version number has been specified, and a supported collection number
3724given, then the collection data is returned in a dataP. The time of collection
3725is also returned, being placed in a timeP.
3727Rx call information for the related Cache Manager is contained in a rxCallP.
3729The collection number supplied in a collectionNumber is out of range.
3731 \section sec6-6 Section 6.6: Files
3734The Cache Manager gets some of its start-up configuration information from
3735files located on the client machine's hard disk. Each client is required to
3736supply a /usr/vice/etc directory in which this configuration data is kept.
3737Section 6.6.1 describes the format and purpose of the three files contributing
3738this setup information: ThisCell, CellServDB, and cacheinfo.
3740 \subsection sec6-6-1 Section 6.6.1: Configuration Files
3742 \subsubsection sec6-6-1-1 Section 6.6.1.1: ThisCell
3745The Cache Manager, along with various applications, needs to be able to
3746determine the cell to which its client machine belongs. This information is
3747provided by the ThisCell file. It contains a single line stating the machine's
3748fully-qualified cell name.
3750As with the CellServDB configuration file, the Cache Manager reads the contents
3751of ThisCell exactly once, at start-up time. Thus, an incarnation of the Cache
3752Manager will maintain precisely one notion of its home cell for its entire
3753lifetime. Thus, changes to the text of the ThisCell file will be invisible to
3754the running Cache Manager. However, these changes will affect such application
3755programs as klog, which allows a user to generate new authentication tickets.
3756In this example, klog reads ThisCell every time it is invoked, and then
3757interacts with the set of Authentication Servers running in the given home
3758cell, unless the caller specifies the desired cell on the command line.
3760The ThisCell file is not expected to be changed on a regular basis. Client
3761machines are not imagined to be frequently traded between different
3762administrative organizations. The Unix mode bits are set to specify that while
3763everyone is allowed to read the file, only root is allowed to modify it.
3765 \subsubsection sec6-6-1-2 Section 6.6.1.2: CellServDB
3768To conduct business with a given AFS cell, a Cache Manager must be informed of
3769the cell's name and the set of machines running AFS database servers within
3770that cell. Such servers include the Volume Location Server, Authentication
3771Server, and Protection Server. This particular cell information is obtained
3772upon startup by reading the CellServDB file. Thus, when the Cache Manager
3773initialization is complete, it will be able to communicate with the cells
3774covered by CellServDB.
3776The following is an excerpt from a valid CellServDB file, demonstrating the
3781>transarc.com #Transarc Corporation
3782192.55.207.7 #henson.transarc.com
3783192.55.207.13 #bigbird.transarc.com
3784192.55.207.22 #ernie.transarc.com
3785>andrew.cmu.edu #Carnegie Mellon University
3786128.2.10.2 #vice2.fs.andrew.cmu.edu
3787128.2.10.7 #vice7.fs.andrew.cmu.edu
3788128.2.10.10 #vice10.fs.andrew.cmu.edu
3792There are four rules describing the legal CellServDB file format:
3793\li 1. Each cell has a separate entry. The entries may appear in any order. It
3794may be convenient, however, to have the workstation's local cell be the first
3796\li 2. No blank lines should appear in the file, even at the end of the last
3798\li 3. The first line of each cell's entry begins with the '>' character, and
3799specifies the cell's human-readable, Internet Domain-style name. Optionally,
3800some white space and a comment (preceded by a '#') may follow, briefly
3801describing the specified cell.
3802\li 4. Each subsequent line in a cell's entry names one of the cell's database
3803server machines. The following must appear on the line, in the order given:
3804\li The Internet address of the server, in the standard 4-component dot
3806\li Some amount of whitespace.
3807\li A '#', followed by the machine's complete Internet host name. In this
3808instance, the '#' sign and the text beyond it specifying the machine name are
3809NOT treated as a comment. This is required information.
3811The Cache Manager will use the given host name to determine its current address
3812via an Internet Domain lookup. If and only if this lookup fails does the Cache
3813Manager fall back to using the dotted Internet address on the first part of the
3814line. This dotted address thus appears simply as a hint in case of Domain
3817The CellServDB file is only parsed once, when the Cache Manager first starts.
3818It is possible, however, to amend existing cell information records or add
3819completely new ones at any time after Cache Manager initialization completes.
3820This is accomplished via the VIOCNEWCELL pioctl() (see Section 6.4.5.1.
3822 \subsubsection sec6-6-1-3 Section 6.6.1.3: cacheinfo
3825This one-line file contains three fields separated by colons:
3826\li AFS Root Directory: This is the directory where the Cache Manager mounts
3827the AFS root volume. Typically, this is specified to be /afs.
3828\li Cache Directory: This field names the directory where the Cache Manager is
3829to create its local cache files. This is typically set to /usr/vice/cache.
3830\li Cache Blocks: The final field states the upper limit on the number of
38311,024-byte blocks that the Cache Manager is allowed to use in the partition
3832hosting the named cache directory.
3834Thus, the following cacheinfo file would instruct the Cache Manager to mount
3835the AFS filespace at /afs, and inform it that it may expect to be able to use
3836up to 25,000 blocks for the files in its cache directory, /usr/vice/cache.
3838/afs:/usr/vice/cache:25000
3841 \subsection sec6-6-2 Section 6.6.2: Cache Information Files
3843 \subsubsection sec6-6-2-1 Section 6.6.2.1: AFSLog
3846This is the AFS log file used to hold Cache Manager debugging output. The file
3847is set up when the Cache Manager first starts. If it already exists, it is
3848truncated. If it doesn't, it is created. Output to this file is enabled and
3849disabled via the the VIOC VENUSLOG pioctl() (see Section 6.4.9.2). Normal text
3850messages are written to this file by the Cache Manager when output is enabled.
3851Each time logging to this file is enabled, the AFSLog file is truncated. Only
3852root can read and write this file.
3854 \subsubsection sec6-6-2-2 Section 6.6.2.2: CacheItems
3857The Cache Manager only keeps a subset of its data cache entry descriptors in
3858memory at once. The number of these in-memory descriptors is determined by
3859afsd. All of the data cache entry descriptors are kept on disk, in the
3860CacheItems file. The file begins with a header region, taking up four
3863struct fheader { long magic AFS_FHMAGIC 0x7635fab8 long firstCSize: First chunk
3864size long otherCSize: Next chunk sizes long spare }
3867The header is followed by one entry for each cache file. Each is:
3870 short hvNextp; /* Next in vnode hash table, or freeDCList */
3871 short hcNextp; /* Next index in [fid, chunk] hash table */
3872 short chunkNextp; /* File queue of all chunks for a single vnode */
3873 struct VenusFid fid; /* Fid for this file */
3874 long modTime; /* last time this entry was modified */
3875 long versionNo; /* Associated data version number */
3876 long chunk; /* Relative chunk number */
3877 long inode; /* Unix inode for this chunk */
3878 long chunkBytes; /* Num bytes in this chunk */
3879 char states; /* Has this chunk been modified? */
3883 \subsubsection sec6-6-2-3 Section 6.6.2.3: VolumeItems
3886The Cache Manager only keeps at most MAXVOLS (50) in-memory volume
3887descriptions. However, it records all volume information it has obtained in the
3888VolumeItems file in the chosen AFS cache directory. This file is truncated when
3889the Cache Manager starts. Each volume record placed into this file has the
3890following struct fvolume layout:
3893 long cell; /*Cell for this entry*/
3894 long volume; /*Numerical volume ID */
3895 long next; /*Hash index*/
3896 struct VenusFid dotdot; /*Full fid for .. dir */
3897 struct VenusFid mtpoint; /*Full fid for mount point*/
3901 \section sec6-7 Section 6.7: Mariner Interface
3904The Cache Manager Mariner interface allows interested parties to be advised in
3905real time as to which files and/or directories are being actively transferred
3906between the client machine and one or more File Servers. If enabled, this
3907service delivers messages of two different types, as exemplified below:
3909Fetching myDataDirectory
3910Fetching myDataFile.c
3914In the first message, the myDataDirectory directory is shown to have just been
3915fetched from a File Server. Similarly, the second message indicates that the C
3916program myDataFile.c had just been fetched from its File Server of residence.
3917Finally, the third message reveals that the myDataObj.o object file has just
3918been written out over the network to its respective server.
3920In actuality, the text of the messages carries a string prefix to indicate
3921whether a Fetch or Store operation had been performed. So, the full contents of
3922the above messages are as follows:
3924fetch$Fetching myDataDirectory
3925fetch$Fetching myDataFile.c
3926store$Storing myDataObj.o
3928The Mariner service may be enabled or disabled for a particular machine by
3929using the VIOC AFS MARINER HOST pioctl() (see Section 6.4.9.1). This operation
3930allows any host to be specified as the recipient of these messages. A potential
3931recipient must have its host be declared the target of such messages, then
3932listen to a socket on port 2106.
3934Internally, the Cache Manager maintains a cache of NMAR (10) vnode structure
3935pointers and the string name (up to 19 characters) of the associated file or
3936directory. This cache is implemented as an array serving as a circular buffer.
3937Each time a file is involved in a create or lookup operation on a File Server,
3938the current slot in this circular buffer is filled with the relevant vnode and
3939string name information, and the current position is advanced. If Mariner
3940output is enabled, then an actual network fetch or store operation will trigger
3941messages of the kind shown above. Since a fetch or store operation normally
3942occurs shortly after the create or lookup, the mapping of vnode to name is
3943likely to still be in the Mariner cache when it comes time to generate the
3944appropriate message. However, since an unbounded number of other lookups or
3945creates could have been performed in the interim, there is no guarantee that
3946the mapping entry will not have been overrun. In these instances, the Mariner
3947message will be a bit vaguer. Going back to our original example,
3949Fetching myDataDirectory
3953In this case, the cached association between the vnode containing myDataFile.c
3954and its string name was thrown out of the Mariner cache before the network
3955fetch operation could be performed. Unable to find the mapping, the generic
3956phrase "a file" was used to identify the object involved.
3958Mariner messages only get generated when RPC traffic for fetching or storing a
3959file system object occurs between the Cache Manager and a File Server. Thus,
3960file accesses that are handled by the Cache Manager's on-board data cache do
3961not trigger such announcements.
3963 \page biblio Bibliography
3965\li [1] Transarc Corporation. AFS 3.0 System Administrator's Guide,
3966F-30-0-D102, Pittsburgh, PA, April 1990.
3967\li [2] Transarc Corporation. AFS 3.0 Command Reference Manual, F-30-0-D103,
3968Pittsburgh, PA, April 1990.
3969\li [3] CMU Information Technology Center. Synchronization and Caching Issues
3970in the Andrew File System, USENIX Proceedings, Dallas, TX, Winter 1988.
3971\li [4] Sun Microsystems, Inc. NFS: Network File System Protocol Specification,
3972RFC 1094, March 1989.
3973\li [5] Sun Microsystems, Inc. Design and Implementation of the Sun Network
3974File System, USENIX Summer Conference Proceedings, June 1985.
3975\li [6] S.P. Miller, B.C. Neuman, J.I. Schiller, J.H. Saltzer. Kerberos
3976Authentication and Authorization System, Project Athena Technical Plan, Section
3977E.2.1, M.I.T., December 1987.
3978\li [7] Bill Bryant. Designing an Authentication System: a Dialogue in Four
3979Scenes, Project Athena internal document, M.I.T, draft of 8 February 1988.