My Project
fs-cm-spec.h
1
1462\endcode
1463\par Description
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.
1468\par
1469Rx connection information for the related File Server is contained in a
1470rxConnP. Volume version information is returned for synchronization purposes in
1471a volSyncP.
1472\par Error Codes
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.
1478
1479 \subsubsection sec5-1-3-7 Section 5.1.3.7: RXAFS Rename - Rename the
1480specified file in the given directory
1481
1482\code
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)
1491\endcode
1492\par Description
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.
1500\par
1501Rx connection information for the related File Server is contained in a
1502rxConnP. Volume version information is returned for synchronization purposes in
1503a volSyncP.
1504\par Error Codes
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.
1512
1513 \subsubsection sec5-1-3-8 Section 5.1.3.8: RXAFS Symlink - Create a
1514symbolic link
1515
1516\code
1517int RXAFS Symlink(IN struct rx connection *a rxConnP,
1518 IN AFSFid *a dirFidP,
1519 IN char *a nameP,
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)
1526\endcode
1527\par Description
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
1538respectively.
1539\par
1540Rx connection information for the related File Server is contained in a
1541rxConnP. Volume version information is returned for synchronization purposes in
1542a volSyncP.
1543\par Error Codes
1544EACCES The caller does not have the necessary access rights.
1545\n EINVAL Illegal symbolic link name provided.
1546
1547 \subsubsection sec5-1-3-9 Section 5.1.3.9: RXAFS Link - Create a hard
1548link
1549
1550\code
1551int RXAFS Link(IN struct rx connection *a rxConnP,
1552 IN AFSFid *a dirFidP,
1553 IN char *a nameP,
1554 IN AFSFid *a existingFidP,
1555 OUT AFSFetchStatus *a newFidStatP,
1556 OUT AFSFetchStatus *a newDirStatP,
1557 OUT AFSVolSync *a volSyncP)
1558\endcode
1559\par Description
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
1566respectively.
1567Rx connection information for the related File Server is contained in a
1568rxConnP. Volume version information is returned for synchronization purposes in
1569a volSyncP.
1570\par Error Codes
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.
1574
1575 \subsubsection sec5-1-3-10 Section 5.1.3.10: RXAFS MakeDir - Create a
1576directory
1577
1578\code
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)
1588\endcode
1589\par Description
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.
1600\par
1601Rx connection information for the related File Server is contained in a
1602rxConnP. Volume version information is returned for synchronization purposes in
1603a volSyncP.
1604\par Error Codes
1605EACCES The caller does not have the necessary access rights.
1606\n EINVAL The directory name provided is unacceptable.
1607
1608 \subsubsection sec5-1-3-11 Section 5.1.3.11: RXAFS RemoveDir - Remove a
1609directory
1610
1611\code
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)
1617\endcode
1618\par Description
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.
1625\par
1626Rx connection information for the related File Server is contained in a
1627rxConnP. Volume version information is returned for synchronization purposes in
1628a volSyncP.
1629\par Error Codes
1630EACCES The caller does not have the necessary access rights.
1631
1632 \subsubsection sec5-1-3-12 Section 5.1.3.12: RXAFS GetStatistics - Get
1633common File Server statistics
1634
1635\code
1636int RXAFS GetStatistics(IN struct rx connection *a rxConnP,
1637 OUT ViceStatistics *a FSInfoP)
1638\endcode
1639\par Description
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.
1644\par
1645Rx connection information for the related File Server is contained in a
1646rxConnP.
1647\par Error Codes
1648---No error codes generated.
1649
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
1653
1654\code
1655int RXAFS GiveUpCallBacks(IN struct rx connection *a rxConnP,
1656 IN AFSCBFids *a fidArrayP,
1657 IN AFSCBs *a callBackArrayP)
1658\endcode
1659\par Description
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.
1666\par
1667Rx connection information for the related File Server is contained in a
1668rxConnP.
1669\par Error Codes
1670EINVAL More file identifiers were provided in the a fidArrayP than callbacks in
1671the a callBackArray.
1672
1673 \subsubsection sec5-1-3-14 Section 5.1.3.14: RXAFS GetVolumeInfo - Get
1674information about a volume given its name
1675
1676\code
1677int RXAFS GetVolumeInfo(IN struct rx connection *a rxConnP,
1678 IN char *a volNameP,
1679 OUT VolumeInfo *a volInfoP)
1680\endcode
1681\par Description
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.
1685\par
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
1689\par Error Codes
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
1693has been deleted.
1694\n VL NOENT The given volume was not found.
1695
1696 \subsubsection sec5-1-3-15 Section 5.1.3.15: RXAFS GetVolumeStatus -
1697Get basic status information for the named volume
1698
1699\code
1700int RXAFS GetVolumeStatus(IN struct rx connection *a rxConnP,
1701 IN long a volIDP,
1702 OUT AFSFetchVolumeStatus *a volFetchStatP,
1703 OUT char *a volNameP,
1704 OUT char *a offLineMsgP,
1705 OUT char *a motdP)
1706\endcode
1707\par Description
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.
1719\par
1720Rx connection information for the related File Server is contained in a
1721rxConnP.
1722\par Error Codes
1723EACCES The caller does not have the necessary access rights.
1724\n EINVAL A volume identifier of zero was specified.
1725
1726 \subsubsection sec5-1-3-16 Section 5.1.3.16: RXAFS SetVolumeStatus -
1727Set the basic status information for the named volume
1728
1729\code
1730int RXAFS SetVolumeStatus(struct rx connection *a rxConnP,
1731 long avolIDP,
1732 AFSStoreVolumeStatus *a volStoreStatP,
1733 char *a volNameP,
1734 char *a offLineMsgP,
1735 char *a motdP)
1736/* for the named volume */
1737\endcode
1738\par Description
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
1748long each.
1749\par
1750Rx connection information for the related File Server is contained in a
1751rxConnP.
1752\par Error Codes
1753EACCES The caller does not have the necessary access rights.
1754\n EINVAL A volume identifier of zero was specified.
1755
1756 \subsubsection sec5-1-3-17 Section 5.1.3.17: RXAFS GetRootVolume -
1757Return the name of the root volume for the file system
1758
1759\code
1760int RXAFS GetRootVolume(IN struct rx connection *a rxConnP,
1761 OUT char *a rootVolNameP)
1762\endcode
1763\par Description
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".
1771\par
1772Rx connection information for the related File Server is contained in a
1773rxConnP. Volume version information is returned for synchronization purposes in
1774a volSyncP.
1775\par Error Codes
1776---No error codes generated.
1777
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
1780authentication token
1781
1782\code
1783int RXAFS CheckToken(IN struct rx connection *a rxConnP,
1784 IN long ViceId,
1785 IN AFSOpaque *token)
1786\endcode
1787\par Description
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.
1791\par
1792Rx connection information for the related File Server is contained in a
1793rxConnP.
1794\par Error Codes
1795ECONNREFUSED Always returned on Rx connections.
1796
1797 \subsubsection sec5-1-3-19 Section 5.1.3.19: RXAFS GetTime - Get the
1798File Server's time of day
1799
1800\code
1801int RXAFS GetTime(IN struct rx connection *a rxConnP,
1802 OUT unsigned long *a secondsP,
1803 OUT unsigned long *a uSecondsP)
1804\endcode
1805\par Description
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".
1810\par Error Codes
1811---No error codes generated.
1812
1813 \subsubsection sec5-1-3-20 Section 5.1.3.20: RXAFS NGetVolumeInfo - Get
1814information about a volume given its name
1815
1816\code
1817int RXAFS NGetVolumeInfo(IN struct rx connection *a rxConnP,
1818 IN char *a volNameP,
1819 OUT AFSVolumeInfo *a volInfoP)
1820\endcode
1821\par Description
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.
1826
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
1829
1830\code
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)
1836\endcode
1837\par Description
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
1841once.
1842\par
1843Rx connection information for the related File Server is contained in a
1844rxConnP. Volume version information is returned for synchronization purposes in
1845a volSyncP.
1846\par Error Codes
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.
1850
1851 \subsubsection sec5-1-3-22 Section 5.1.3.22: RXAFS SetLock - Set an
1852advisory lock on the given file identifier
1853
1854\code
1855int RXAFS SetLock(IN struct rx connection *a rxConnP,
1856 IN AFSFid *a fidToLockP,
1857 IN ViceLockType a lockType,
1858 OUT AFSVolSync *a volSyncP)
1859\endcode
1860\par Description
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
18655.1.3.23).
1866\par
1867Rx connection information for the related File Server is contained in a
1868rxConnP. Volume version information is returned for synchronization purposes in
1869a volSyncP.
1870\par Error Codes
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.
1874
1875 \subsubsection sec5-1-3-23 Section 5.1.3.23: RXAFS ExtendLock - Extend
1876an advisory lock on a file
1877
1878\code
1879int RXAFS ExtendLock(IN struct rx connection *a rxConnP,
1880 IN AFSFid *a fidToBeExtendedP,
1881 OUT AFSVolSync *a volSyncP)
1882\endcode
1883\par Description
1884[Opcode 157] Extend the advisory lock that has already been granted to the
1885caller on the file identified by a fidToBeExtendedP.
1886\par
1887Rx connection information for the related File Server is contained in a
1888rxConnP. Volume version information is returned for synchronization purposes in
1889a volSyncP.
1890\par Error Codes
1891EINVAL The caller does not already have the given file locked.
1892
1893 \subsubsection sec5-1-3-24 Section 5.1.3.24: RXAFS ReleaseLock -
1894Release the advisory lock on a file
1895
1896\code
1897int RXAFS ReleaseLock(IN struct rx connection *a rxConnP,
1898 IN AFSFid *a fidToUnlockP,
1899 OUT AFSVolSync *a volSyncP)
1900\endcode
1901\par Description
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.
1905\par
1906Rx connection information for the related File Server is contained in a
1907rxConnP. Volume version information is returned for synchronization purposes in
1908a volSyncP.
1909\par Error Codes
1910EACCES The caller does not have the necessary access rights.
1911
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
1914structure
1915
1916\code
1917int RXAFS XStatsVersion(IN struct rx connection *a rxConnP,
1918 OUT long *a versionNumberP)
1919\endcode
1920\par Description
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.
1924\par
1925Rx connection information for the related File Server is contained in a
1926rxConnP.
1927\par Error Codes
1928---No error codes generated.
1929
1930 \subsubsection sec5-1-3-26 Section 5.1.3.26: RXAFS GetXStats - Get the
1931current contents of the specified extended statistics structure
1932
1933\code
1934int RXAFS GetXStats(IN struct rx connection *a rxConnP,
1935 IN long a clientVersionNumber,
1936 IN long a collectionNumber,
1937 OUT long *a srvVersionNumberP,
1938 OUT long *a timeP,
1939 OUT AFS CollData *a dataP)
1940\endcode
1941\par Description
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.
1956\par
1957Rx connection information for the related File Server is contained in a
1958rxConnP.
1959\par Error Codes
1960---No error codes are generated.
1961
1962 \subsection sec5-1-4 Section 5.1.4: Streamed Function Calls
1963
1964\par
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.
1969\par
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.
1980\par
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.
1990
1991\code
1992FetchData(IN AFSFid *a_fidToFetchP,
1993 IN long a_offset,
1994 IN long a_lenInBytes,
1995 OUT AFSFetchStatus *a_fidStatP,
1996 OUT AFSCallBack *a_callBackP,
1997 OUT AFSVolSync *a_volSyncP) split = 130;
1998
1999StoreData(IN AFSFid *Fid,
2000 IN AFSStoreStatus *InStatus,
2001 IN long Pos,
2002 IN long Length,
2003 IN long FileLength,
2004 OUT AFSFetchStatus *OutStatus,
2005 OUT AFSVolSync *a_volSyncP) split = 133;
2006\endcode
2007
2008 \subsubsection sec5-1-4-1 Section 5.1.4.1: StartRXAFS FetchData - Begin
2009a request to fetch file data
2010
2011\code
2012int StartRXAFS FetchData(IN struct rx call *a rxCallP,
2013 IN AFSFid *a fidToFetchP,
2014 IN long a offset,
2015 IN long a lenInBytes)
2016\endcode
2017
2018\par Description
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.
2023\par
2024Rx call information to the related File Server is contained in a rxCallP.
2025\par Error Codes
2026---No error codes generated.
2027
2028 \subsubsection sec5-1-4-2 Section 5.1.4.2: EndRXAFS FetchData -
2029Conclude a request to fetch file data
2030
2031\code
2032int EndRXAFS FetchData(IN struct rx call *a rxCallP,
2033 OUT AFSFetchStatus *a fidStatP,
2034 OUT AFSCallBack *a callBackP,
2035 OUT AFSVolSync *a volSyncP)
2036\endcode
2037\par Description
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.
2043\par
2044Rx call information to the related File Server is contained in a rxCallP.
2045Volume version information is returned for synchronization purposes in a
2046volSyncP.
2047\par Error Codes
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.
2052
2053 \subsubsection sec5-1-4-3 Section 5.1.4.3: StartRXAFS StoreData - Begin
2054a request to store file data
2055
2056\code
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)
2063\endcode
2064\par Description
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.
2069\par
2070Rx call information to the related File Server is contained in a rxCallP.
2071\par Error Codes
2072---No error codes generated.
2073
2074 \subsubsection sec5-1-4-4 Section 5.1.4.4: EndRXAFS StoreData -
2075Conclude a request to store file data
2076
2077\code
2078int EndRXAFS StoreData(IN struct rx call *a rxCallP,
2079 OUT AFSFetchStatus *a fidStatP,
2080 OUT AFSCallBack *a callBackP,
2081 OUT AFSVolSync *a volSyncP)
2082\endcode
2083\par Description
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.
2089\par
2090Rx call information to the related File Server is contained in a rxCallP.
2091Volume version information is returned for synchronization purposes in a
2092volSyncP.
2093\par Error Codes
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.
2098
2099 \subsection sec5-1-5 Section 5.1.5: Example of Streamed Function Call
2100Usage
2101
2102 \subsubsection sec5-1-5-1 Section 5.1.5.1: Preface
2103
2104\par
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.
2119\par
2120A discussion of the methods used within the example code fragment follows
2121immediately afterwards in Section 5.1.5.3.
2122
2123 \subsubsection sec5-1-5-2 Section 5.1.5.2: Code Fragment Illustrating
2124Fetch Operation
2125
2126\code
2127int code; /*Return code*/
2128long bytesRead; /*Num bytes read from Rx*/
2129struct myConnInfo *connP; /*Includes Rx conn info*/
2130struct rx_call *rxCallP; /*Rx call ptr*/
2131struct AFSFid *afsFidP; /*Fid for file to fetch*/
2132int lclFid; /*Fid for local cache file*/
2133long offsetBytes; /*Starting fetch offset*/
2134long bytesToFetch; /*Num bytes to fetch*/
2135long bytesFromFS; /*Num bytes FileServer returns*/
2136char *fetchBuffP; /*Buffer to hold stream data*/
2137int currReadBytes; /*Num bytes for current read*/
2138/*
2139* Assume that connP, afsFidP, offsetBytes, lclFid,and
2140* bytesToFetch have all been given their desired values.
2141*/ . . .
2142rxCallP = rx_NewCall(connP->rxConnP);
2143code = StartRXAFS_FetchData( rxCallP, /*Rx call to use*/
2144 afsFidP, /*Fid being fetched from*/
2145 offsetBytes, /*Offset in bytes*/
2146 bytesToFetch); /*Num bytes wanted*/
2147if (code == 0)
2148{
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;
2163 } /*Read from the Rx stream*/
2164 close(lclFid);
2165} else ExitWithError(code);
2166code = EndRXAFS_FetchData( rxCallP, /*Rx call to use*/
2167 fidStatP, /*Resulting stat fields*/
2168 fidCallBackP, /*Resulting callback info*/
2169 volSynchP); /*Resulting volume sync info*/
2170 code = rx_EndCall(rxCallP, code);
2171return(code); . . .
2172\endcode
2173
2174 \subsubsection sec5-1-5-3 Section 5.1.5.3: Discussion and Analysis
2175
2176\par
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
2182cached copy.
2183\par
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.
2198\par
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().
2209
2210 \subsection sec5-1-6 Section 5.1.6: Required Caller Functionality
2211
2212\par
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.
2221\par
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.
2234
2235 \section sec5-2 Section 5.2: Signal Interface
2236
2237\par
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.
2247
2248 \subsection sec5-2-1 Section 5.2.1: SIGQUIT: Server Shutdown
2249
2250\par
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
2257bits set.
2258\par
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.
2263
2264 \subsection sec5-2-2 Section 5.2.2: SIGTSTP: Upgrade Debugging Level
2265
2266\par
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.
2277\par
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
2280platforms.
2281
2282 \subsection sec5-2-3 Section 5.2.3: SIGHUP: Reset Debugging Level
2283
2284\par
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.
2289\par
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
2292platforms.
2293
2294 \subsection sec5-2-4 Section 5.2.4: SIGTERM: File Descriptor Check
2295
2296\par
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.
2301
2302 \section sec5-3 Section 5.3: Command Line Interface
2303
2304\par
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.
2316\par
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
2326records.
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
233424,576 bytes.
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
2339vnodes.
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
2352no-op.
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
2368switch.
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).
2377
2378 \page chap6 Chapter 6: Cache Manager Interfaces
2379
2380 \section sec6-1 Section 6.1: Overview
2381
2382\par
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
2389Cache Manager:
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
2412over the network.
2413\par
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].
2421
2422 \section sec6-2 Section 6.2: Definitions
2423
2424\par
2425This section defines data structures that are used by the pioctl() calls.
2426
2427 \subsection sec6-2-1 Section 6.2.1: struct VenusFid
2428
2429\par
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
2435standard AFS fid.
2436\n \b Fields
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.
2439
2440 \subsection sec6-2-2 Section 6.2.2: struct ClearToken
2441
2442\par
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.
2446\n \b Fields
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
2451came into effect.
2452\li long EndTimestamp - Timestamp of when this token is considered to be
2453expired, and thus disregarded.
2454
2455 \section sec6-3 Section 6.3: ioctl() Interface
2456
2457\par
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.
2463
2464 \subsection sec6-3-1 Section 6.3.1: VIOCCLOSEWAIT
2465
2466\par
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.
2474
2475 \subsection sec6-3-2 Section 6.3.2: VIOCABORT
2476
2477\par
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.
2481
2482 \subsection sec6-3-3 Section 6.3.3: VIOIGETCELL
2483
2484\par
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.
2492
2493 \section sec6-4 Section 6.4: pioctl() Interface
2494
2495 \subsection sec6-4-1 Section 6.4.1: Introduction
2496
2497\par
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:
2500\code
2501int afs syscall pioctl(IN char *a pathP,
2502 IN int a opcode,
2503 IN struct ViceIoctl *a paramsP,
2504 IN int a followSymLinks)
2505\endcode
2506\par
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.
2514\par
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
2520operations.
2521\par
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.
2525\par
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.
2530\par
2531This documentation partitions the pioctl() into several groups:
2532\li Volume operations
2533\li File Server operations
2534\li Cell Operations
2535\li Authentication Operations
2536\li ACL Operations
2537\li Cache operations
2538\li Miscellaneous operations
2539
2540\par
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.
2545\par
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
2580
2581 \subsection sec6-4-2 Section 6.4.2: Mount Point Asymmetry
2582
2583\par
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.
2595
2596 \subsection sec6-4-3 Section 6.4.3: Volume Operations
2597
2598\par
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).
2604
2605 \subsubsection sec6-4-3-1 Section 6.4.3.1: VIOCGETVOLSTAT: Get volume
2606status for pathname
2607
2608\par
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.
2617\par
2618Among the possible error returns, EINVAL indicates that the object named by a
2619pathP could not be found.
2620
2621 \subsubsection sec6-4-3-2 Section 6.4.3.2: VIOCSETVOLSTAT: Set volume
2622status for pathname
2623
2624\par
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.
2637\par
2638Among the possible error returns, EINVAL indicates that the object named by a
2639pathP could not be found.
2640
2641 \subsubsection sec6-4-3-3 Section 6.4.3.3: VIOCWHEREIS: Find the
2642server(s) hosting the pathname's volume
2643
2644\par
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
2652returned.
2653\par
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.
2657
2658 \subsubsection sec6-4-3-4 Section 6.4.3.4: VIOC FLUSHVOLUME: Flush all
2659data cached from the pathname's volume
2660
2661\par
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
2666from a given volume.
2667
2668 \subsubsection sec6-4-3-5 Section 6.4.3.5: VIOCCKBACK: Check validity
2669of all cached volume information
2670
2671\par
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
2675be set to zero.
2676\par
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.
2689
2690 \subsection sec6-4-4 Section 6.4.4: File Server Operations
2691
2692\par
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).
2699
2700 \subsubsection sec6-4-4-1 Section 6.4.4.1: VIOCGETFID: Get augmented
2701fid for named file system object
2702
2703\par
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.
2710\par
2711Among the possible error returns, EINVAL indicates that the object named by a
2712pathP was not found.
2713
2714 \subsubsection sec6-4-4-2 Section 6.4.4.2: VIOCFLUSHCB: Unilaterally
2715drop a callback
2716
2717\par
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
2725read-only volumes.
2726\par
2727Among the possible error returns is EINVAL, which indicates that the object
2728named by a pathP was not found.
2729
2730 \subsubsection sec6-4-4-3 Section 6.4.4.3: VIOC AFS DELETE MT PT:
2731Delete a mount point
2732
2733\par
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.
2740\par
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
2752pathP parameter.
2753\par
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
2756not a directory.
2757
2758 \subsubsection sec6-4-4-4 Section 6.4.4.4: VIOC AFS STAT MT PT: Get the
2759contents of a mount point
2760
2761\par
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.
2769\par
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.
2779\par
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.
2783
2784 \subsubsection sec6-4-4-5 Section 6.4.4.5: VIOCCKSERV: Check the status
2785of one or more File Servers
2786
2787\par
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.
2795\par
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
2804caller.
2805\par
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.
2811\par
2812Among the possible error returns is ENOENT, indicating that the optional cell
2813name string input value is not known to the Cache Manager.
2814
2815 \subsection sec6-4-5 Section 6.4.5: Cell Operations
2816
2817\par
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,
2831VIOC SETCELLSTATUS).
2832
2833 \subsubsection sec6-4-5-1 Section 6.4.5.1: VIOCNEWCELL: Set cell
2834service information
2835
2836\par
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.
2845\par
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.
2850
2851 \subsubsection sec6-4-5-2 Section 6.4.5.2: VIOCGETCELL: Get cell
2852configuration entry
2853
2854\par
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.
2860\par
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.
2867\par
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.
2873
2874 \subsubsection sec6-4-5-3 Section 6.4.5.3: VIOC FILE CELL NAME: Get
2875cell hosting a given object
2876
2877\par
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.
2882\par
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.
2886
2887 \subsubsection sec6-4-5-4 Section 6.4.5.4: VIOC GET WS CELL: Get
2888caller's home cell name
2889
2890\par
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.
2895\par
2896Among the possible error returns is ESRCH, stating that the caller's home cell
2897information was not available.
2898
2899 \subsubsection sec6-4-5-5 Section 6.4.5.5: VIOC GET PRIMARY CELL: Get
2900the caller's primary cell
2901
2902\par
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
2910suffcient room.
2911\par
2912Among the possible error returns is ESRCH, stating that the caller's primary
2913cell information was not available.
2914
2915 \subsubsection sec6-4-5-6 Section 6.4.5.6: VIOC GETCELLSTATUS: Get
2916status info for a cell entry
2917
2918\par
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.
2924\par
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.
2930
2931\par
2932Among the possible error returns is ENOENT, informing the caller that the Cache
2933Manager has no knowledge of the given cell name.
2934
2935 \subsubsection sec6-4-5-7 Section 6.4.5.7: VIOC SETCELLSTATUS: Set
2936status info for a cell entry
2937
2938\par
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
2946applied.
2947\par
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.
2952
2953 \subsection sec6-4-6 Section 6.4.6: Authentication Operations
2954
2955\par
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
2968tokens.
2969\par
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.
2973\par
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
2981AFS tokens.
2982
2983 \subsubsection sec6-4-6-1 Section 6.4.6.1: VIOCSETTOK: Set the caller's
2984token for a cell
2985
2986\par
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.
3001\par
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.
3007\par
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.
3010
3011 \subsubsection sec6-4-6-2 Section 6.4.6.2: VIOCGETTOK: Get the caller's
3012token for a cell
3013
3014\par
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.
3030\par
3031Other than EDOM, another possible error return is ENOTCONN, specifying that the
3032caller does not have any AFS tokens whatsoever.
3033
3034 \subsubsection sec6-4-6-3 Section 6.4.6.3: VIOCACCESS: Check caller's
3035access on object
3036
3037\par
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
3044zero.
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.
3047
3048 \subsubsection sec6-4-6-4 Section 6.4.6.4: VIOCCKCONN: Check status of
3049caller's tokens/connections
3050
3051\par
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.
3063
3064 \subsubsection sec6-4-6-5 Section 6.4.6.5: VIOCUNLOG: Discard
3065authentication information
3066
3067\par
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.
3073\par
3074This operation always returns successfully. None of the parameters are
3075referenced, so they should all be set to null pointers and zeroes as
3076appropriate.
3077
3078 \subsubsection sec6-4-6-6 Section 6.4.6.6: VIOCUNPAG: Discard
3079authentication information
3080
3081\par
3082[Opcode 21] This call is essentially identical to the VIOCUNLOG operation, and
3083is in fact implemented internally by the same code for VIOCUNLOG.
3084
3085 \subsection sec6-4-7 Section 6.4.7: ACL Operations
3086
3087\par
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
3095given file resides.
3096\par
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
3104named parties.
3105\par
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:
3110\code
3111printf("%d\n%d\n", NumPositiveEntries, NumNegativeEntries);
3112\endcode
3113\par
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
3117positive entry.
3118\par
3119Each entry in the ACL proper obeys the format imposed by the following printf()
3120statement:
3121\code
3122printf("%s\t%d\n", UserOrGroupName, RightsMask);
3123\endcode
3124\par
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
3135identifier.
3136\par
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
3140RightsMask:
3141\code
3142#define PRSFS_READ 1 /*Read files*/
3143#define PRSFS_WRITE 2 /*Write & write-lock existing files*/
3144#define PRSFS_INSERT 4 /*Insert & write-lock new files*/
3145#define PRSFS_LOOKUP 8 /*Enumerate files and examine ACL*/
3146#define PRSFS_DELETE 16 /*Remove files*/
3147#define PRSFS_LOCK 32 /*Read-lock files*/
3148#define PRSFS_ADMINISTER 64 /*Set access list of directory*/
3149\endcode
3150
3151 \subsubsection sec6-4-7-1 Section 6.4.7.1: VIOCSETAL: Set the ACL on a
3152directory
3153
3154\par
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.
3163\par
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.
3167
3168 \subsubsection sec6-4-7-2 Section 6.4.7.2: VIOCGETAL: Get the ACL for a
3169directory
3170
3171\par
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.
3181\par
3182Possible error codes include EINVAL, indicating that the named path is not in
3183AFS.
3184
3185 \subsection sec6-4-8 Section 6.4.8: Cache Operations
3186
3187\par
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).
3194
3195 \subsubsection sec6-4-8-1 Section 6.4.8.1: VIOCFLUSH: Flush an object
3196from the cache
3197
3198\par
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.
3202\par
3203Among the possible error returns is EINVAL, indicating that the value supplied
3204in the a pathP parameter is not acceptable.
3205
3206 \subsubsection sec6-4-8-2 Section 6.4.8.2: VIOCSETCACHESIZE: Set
3207maximum cache size in blocks
3208
3209\par
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.
3220\par
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.
3224
3225 \subsubsection sec6-4-8-3 Section 6.4.8.3: VIOCGETCACHEPARAMS: Get
3226current cache parameter values
3227
3228\par
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.
3238\par
3239This routine always returns successfully.
3240
3241 \subsection sec6-4-9 Section 6.4.9: Miscellaneous Operations
3242
3243\par
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
3251EXPORTAFS).
3252
3253 \subsubsection sec6-4-9-1 Section 6.4.9.1: VIOC AFS MARINER HOST:
3254Get/set file transfer monitoring output
3255
3256\par
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.
3260\par
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.
3270\par
3271This function always returns successfully.
3272
3273 \subsubsection sec6-4-9-2 Section 6.4.9.2: VIOC VENUSLOG:
3274Enable/disable Cache Manager logging
3275
3276\par
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.
3289\par
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.
3296\par
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.
3299
3300 \subsubsection sec6-4-9-3 Section 6.4.9.3: VIOC AFS SYSNAME: Get/set
3301the @sys mapping
3302
3303\par
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.
3313\par
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.
3326
3327 \subsubsection sec6-4-9-4 Section 6.4.9.4: VIOC EXPORTAFS:
3328Enable/disable NFS/AFS translation
3329
3330\par
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
3350being set.
3351\par
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.
3357\par
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.
3363
3364 \section sec6-5 Section 6.5: RPC Interface
3365
3366 \subsection sec6-5-1 Section 6.5.1: Introduction
3367
3368\par
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.
3376\par
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.
3381
3382 \subsection sec6-5-2 Section 6.5.2: Locks
3383
3384\par
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
3401stat() information.
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
3412duties.
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
3415Manager.
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
3418with the
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
3423the Cache Manager.
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
3427Section 6.6.2.3).
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
3431improved.
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
3438memory system.
3439
3440 \subsection sec6-5-3 Section 6.5.3: Definitions and Typedefs
3441
3442\par
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.
3447
3448\code
3449/*
3450* Define the version of CacheManager and FileServer extended
3451* statistics being implemented.
3452*/
3453const AFSCB_XSTAT_VERSION = 1;
3454
3455/*
3456* Define the maximum arrays for passing extended statistics
3457* info for the CacheManager and FileServer back to our caller.
3458*/
3459const AFSCB_MAX_XSTAT_LONGS = 2048;
3460typedef long AFSCB_CollData<AFSCB_MAX_XSTAT_LONGS>;
3461
3462/*
3463* Define the identifiers for the accessible extended stats data
3464* collections.
3465*/
3466const AFSCB_XSTATSCOLL_CALL_INFO = 0; /*CM call counting & info*/
3467const AFSCB_XSTATSCOLL_PERF_INFO = 1; /*CM performance info*/
3468\endcode
3469
3470 \subsection sec6-5-4 Section 6.5.4: Structures
3471
3472\par
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.
3477
3478 \subsubsection sec6-5-4-1 Section 6.5.4.1: struct afs MeanStats
3479
3480\par
3481This structure may be used to collect a running average figure. It is included
3482in some of the statistics structures described below.
3483\n \b Fields
3484\li long average - The computed average.
3485\li long elements - The number of elements sampled for the above aveage.
3486
3487 \subsubsection sec6-5-4-2 Section 6.5.4.2: struct afs CMCallStats
3488
3489\par
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
3495Appendix A.
3496\par
3497The AFSCB XSTATSCOLL CALL INFO data collection includes the information in this
3498structure.
3499
3500 \subsubsection sec6-5-4-3 Section 6.5.4.3: struct afs CMMeanStats
3501
3502\par
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
35076.5.5.7.
3508\par
3509This structure represents the beginning of work to compute average values for
3510some of the extended statistics collected by the Cache Manager.
3511\n \b Fields
3512\li struct afs MeanStats something - Intended to collect averages for some of
3513the Cache Manager extended statistics; not yet implemented.
3514
3515 \subsubsection sec6-5-4-4 Section 6.5.4.4: struct afs CMStats
3516
3517\par
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
35216.5.5.7.
3522\n \b Fields
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.
3527
3528 \subsubsection sec6-5-4-5 Section 6.5.4.5: struct afs CMPerfStats
3529
3530\par
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.
3534\n \b Fields
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
3539cell.
3540\li long vlocalAccesses - Number of stat accesses to files within the local
3541cell.
3542\li long dremoteAccesses - Number of data accesses to files outside of the
3543local cell.
3544\li long vremoteAccesses - Number of stat accesses to files outside of the
3545local cell.
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
3553cache.
3554\li long vcacheHits - Number of stat entry requests satisfied by the local
3555cache.
3556\li long dcacheMisses - Number of data file requests not satisfied by the local
3557cache.
3558\li long vcacheMisses - Number of stat entry requests not satisfied by the
3559local cache.
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
3565implemented).
3566\li long spare[32] - A set of longword spares reserved for future use.
3567
3568 \subsection sec6-5-5 Section 6.5.5: Function Calls
3569
3570\par
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.
3581
3582 \subsubsection sec6-5-5-1 Section 6.5.5.1: RXAFSCB Probe - Acknowledge
3583that the underlying callback service is still operational
3584
3585\code
3586int RXAFSCB Probe(IN struct rx call *a rxCallP)
3587\endcode
3588\par Description
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.
3597\par
3598Rx call information for the related Cache Manager is contained in a rxCallP.
3599\par Error Codes
3600---No error codes are generated.
3601
3602 \subsubsection sec6-5-5-2 Section 6.5.5.2: RXAFSCB CallBack - Report
3603callbacks dropped by a File Server
3604
3605\code
3606int RXAFSCB CallBack(IN struct rx call *a rxCallP,
3607 IN AFSCBFids *a fidArrayP,
3608 IN AFSCBs *a callBackArrayP)
3609\endcode
3610\par Description
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.
3617\par
3618Rx call information for the related Cache Manager is contained in a rxCallP.
3619\par Error Codes
3620---No error codes are generated.
3621
3622 \subsubsection sec6-5-5-3 Section 6.5.5.3: RXAFSCB InitCallBackState -
3623Purge callback state from a File Server
3624
3625\code
3626int RXAFSCB InitCallBackState(IN struct rx call *a rxCallP)
3627\endcode
3628\par Description
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.
3637\par
3638Rx call information for the related Cache Manager is contained in a rxCallP.
3639\par Error Codes
3640---No error codes are generated.
3641
3642 \subsubsection sec6-5-5-4 Section 6.5.5.4: RXAFSCB GetLock - Get
3643contents of Cache Manager lock table
3644
3645\code
3646int RXAFSCB GetLock(IN struct rx call *a rxCall,
3647 IN long a index,
3648 OUT AFSDBLock *a lockP)
3649\endcode
3650\par Description
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.
3655\par
3656This call is not used by File Servers, but rather by debugging tools such as
3657cmdebug.
3658\par
3659Rx call information for the related Cache Manager is contained in a rxCallP.
3660\par Error Codes
3661The index value supplied in a index is out of range; it must be between 0 and
366210.
3663
3664 \subsubsection sec6-5-5-5 Section 6.5.5.5: RXAFSCB GetCE - Get cache
3665file description
3666
3667\code
3668int RXAFSCB GetCE(IN struct rx call *a rxCall,
3669 IN long a index,
3670 OUT AFSDBCacheEntry *a ceP)
3671\endcode
3672\par Description
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.
3676\par
3677This call is not used by File Servers, but rather by debugging tools such as
3678cmdebug.
3679\par
3680Rx call information for the related Cache Manager is contained in a rxCallP.
3681\par Error Codes
3682The index value supplied in a index is out of range.
3683
3684 \subsubsection sec6-5-5-6 Section 6.5.5.6: RXAFSCB XStatsVersion - Get
3685version of extended statistics package
3686
3687\code
3688int RXAFSCB XStatsVersion(IN struct rx call *a rxCall,
3689 OUT long *a versionNumberP)
3690\endcode
3691\par Description
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.
3695\par
3696Rx call information for the related Cache Manager is contained in a rxCallP.
3697\par Error Codes
3698---No error codes are generated.
3699
3700 \subsubsection sec6-5-5-7 Section 6.5.5.7: RXAFSCB GetXStats - Get
3701contents of extended statistics data collection
3702
3703\code
3704int RXAFSCB GetXStats(IN struct rx call *a rxCall,
3705 IN long a clientVersionNumber,
3706 IN long a collectionNumber,
3707 OUT long *a srvVersionNumberP,
3708 OUT long *a timeP,
3709 OUT AFSCB CollData *a dataP)
3710\endcode
3711\par Description
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.
3726\par
3727Rx call information for the related Cache Manager is contained in a rxCallP.
3728\par Error Codes
3729The collection number supplied in a collectionNumber is out of range.
3730
3731 \section sec6-6 Section 6.6: Files
3732
3733\par
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.
3739
3740 \subsection sec6-6-1 Section 6.6.1: Configuration Files
3741
3742 \subsubsection sec6-6-1-1 Section 6.6.1.1: ThisCell
3743
3744\par
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.
3749\par
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.
3759\par
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.
3764
3765 \subsubsection sec6-6-1-2 Section 6.6.1.2: CellServDB
3766
3767\par
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.
3775\par
3776The following is an excerpt from a valid CellServDB file, demonstrating the
3777format used.
3778
3779\code
3780...
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
3789...
3790\endcode
3791\par
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
3795to appear.
3796\li 2. No blank lines should appear in the file, even at the end of the last
3797entry.
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
3805notation.
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.
3810\par
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
3815database downtime.
3816\par
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.
3821
3822 \subsubsection sec6-6-1-3 Section 6.6.1.3: cacheinfo
3823
3824\par
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.
3833\par
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.
3837\code
3838/afs:/usr/vice/cache:25000
3839\endcode
3840
3841 \subsection sec6-6-2 Section 6.6.2: Cache Information Files
3842
3843 \subsubsection sec6-6-2-1 Section 6.6.2.1: AFSLog
3844
3845\par
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.
3853
3854 \subsubsection sec6-6-2-2 Section 6.6.2.2: CacheItems
3855
3856\par
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
3861longwords:
3862\code
3863struct fheader { long magic AFS_FHMAGIC 0x7635fab8 long firstCSize: First chunk
3864size long otherCSize: Next chunk sizes long spare }
3865\endcode
3866\par
3867The header is followed by one entry for each cache file. Each is:
3868\code
3869struct fcache {
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? */
3880};
3881\endcode
3882
3883 \subsubsection sec6-6-2-3 Section 6.6.2.3: VolumeItems
3884
3885\par
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:
3891\code
3892struct fvolume {
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*/
3898};
3899\endcode
3900
3901 \section sec6-7 Section 6.7: Mariner Interface
3902
3903\par
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:
3908\code
3909Fetching myDataDirectory
3910Fetching myDataFile.c
3911Storing myDataObj.o
3912\endcode
3913\par
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.
3919\par
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:
3923\code
3924fetch$Fetching myDataDirectory
3925fetch$Fetching myDataFile.c
3926store$Storing myDataObj.o
3927\endcode
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.
3933\par
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,
3948\code
3949Fetching myDataDirectory
3950Fetching a file
3951Storing myDataObj.o
3952\endcode
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.
3957\par
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.
3962
3963 \page biblio Bibliography
3964
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.
3980
3981*/