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
1465 directory or a symbolic link. If this call succeeds, it is the Cache Manager's
1466 responsibility to either create an entry locally in the directory specified by
1467 DirFid or to invalidate this directory's cache entry.
1468 \par
1469 Rx connection information for the related File Server is contained in a
1470 rxConnP. Volume version information is returned for synchronization purposes in
1471 a volSyncP.
1472 \par Error Codes
1473 EACCES The caller is not permitted to perform this operation.
1474 \n EINVAL An internal error in looking up the client record was encountered, or
1475 an 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
1480 specified file in the given directory
1481 
1482 \code
1483 int 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
1494 origDirFidP. Its new name is to be a newNameP, and it will reside in the
1495 directory identified by a newDirFidP. Each of these names must be no more than
1496 AFSNAMEMAX (256) characters long. The status of the original and new
1497 directories after the rename operation completes are deposited in a
1498 origDirStatusP and a newDirStatusP respectively. Existing callbacks are broken
1499 for all files and directories involved in the operation.
1500 \par
1501 Rx connection information for the related File Server is contained in a
1502 rxConnP. Volume version information is returned for synchronization purposes in
1503 a volSyncP.
1504 \par Error Codes
1505 EACCES 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,
1511 or hard links exist to the file.
1512 
1513  \subsubsection sec5-1-3-8 Section 5.1.3.8: RXAFS Symlink - Create a
1514 symbolic link
1515 
1516 \code
1517 int 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
1529 by a dirFidP. The text of the symbolic link is provided in a linkContentsP, and
1530 the desired status fields for the symbolic link given by a origDirStatP. The
1531 name offered in a nameP must be less than AFSNAMEMAX (256) characters long, and
1532 the text of the link to which a linkContentsP points must be less than
1533 AFSPATHMAX (1,024) characters long. Once the symbolic link has been
1534 successfully created, its file identifier is returned in a newFidP. Existing
1535 callbacks to the a dirFidP directory are broken before the symbolic link
1536 creation completes. The status fields for the symbolic link itself and its
1537 parent's directory are returned in a newFidStatP and a newDirStatP
1538 respectively.
1539 \par
1540 Rx connection information for the related File Server is contained in a
1541 rxConnP. Volume version information is returned for synchronization purposes in
1542 a volSyncP.
1543 \par Error Codes
1544 EACCES 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
1548 link
1549 
1550 \code
1551 int 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
1561 dirFidP. The file serving as the basis for the hard link is identified by
1562 existingFidP. The name offered in a nameP must be less than AFSNAMEMAX (256)
1563 characters long. Existing callbacks to the a dirFidP directory are broken
1564 before the hard link creation completes. The status fields for the file itself
1565 and its parent's directory are returned in a newFidStatP and a newDirStatP
1566 respectively.
1567 Rx connection information for the related File Server is contained in a
1568 rxConnP. Volume version information is returned for synchronization purposes in
1569 a volSyncP.
1570 \par Error Codes
1571 EACCES 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
1576 directory
1577 
1578 \code
1579 int 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
1591 identified by a parentDirFidP. The initial status fields for the new directory
1592 are provided in a currStatP. The new directory's name must be less than
1593 AFSNAMEMAX (256) characters long. The new directory's ACL is inherited from its
1594 parent. Existing callbacks on the parent directory are broken before the
1595 creation completes. Upon successful directory creation, the new directory's
1596 file identifier is returned in a newDirFidP, and the resulting status
1597 information for the new and parent directories are stored in a dirFidStatP and
1598 a parentDirStatP respectively. In addition, a callback for the new directory is
1599 returned in a newDirCallBackP.
1600 \par
1601 Rx connection information for the related File Server is contained in a
1602 rxConnP. Volume version information is returned for synchronization purposes in
1603 a volSyncP.
1604 \par Error Codes
1605 EACCES 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
1609 directory
1610 
1611 \code
1612 int 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
1620 directory, identified by a parentDirFid. The directory being removed must be
1621 empty, and its name must be less than AFSNAMEMAX (256) characters long.
1622 Existing callbacks to the directory being removed and its parent directory are
1623 broken before the deletion completes. Upon successful deletion, the status
1624 fields for the parent directory are returned in a newParentDirStatP.
1625 \par
1626 Rx connection information for the related File Server is contained in a
1627 rxConnP. Volume version information is returned for synchronization purposes in
1628 a volSyncP.
1629 \par Error Codes
1630 EACCES The caller does not have the necessary access rights.
1631 
1632  \subsubsection sec5-1-3-12 Section 5.1.3.12: RXAFS GetStatistics - Get
1633 common File Server statistics
1634 
1635 \code
1636 int 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
1641 statistics. These numbers represent accumulated readings since the time the
1642 File Server last restarted. For a full description of the individual fields
1643 contained in this structure, please see Section 5.1.2.6.
1644 \par
1645 Rx connection information for the related File Server is contained in a
1646 rxConnP.
1647 \par Error Codes
1648 ---No error codes generated.
1649 
1650  \subsubsection sec5-1-3-13 Section 5.1.3.13: RXAFS GiveUpCallBacks -
1651 Ask the File Server to break the given set of callbacks on the corresponding
1652 set of file identifiers
1653 
1654 \code
1655 int 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
1661 and a corresponding number of callback structures in a callBackArrayP, ask the
1662 File Server to remove these callbacks from its register. Note that this routine
1663 only affects callbacks outstanding on the given set of files for the host
1664 issuing the RXAFS GiveUpCallBacks call. Callback promises made to other
1665 machines on any or all of these files are not affected.
1666 \par
1667 Rx connection information for the related File Server is contained in a
1668 rxConnP.
1669 \par Error Codes
1670 EINVAL More file identifiers were provided in the a fidArrayP than callbacks in
1671 the a callBackArray.
1672 
1673  \subsubsection sec5-1-3-14 Section 5.1.3.14: RXAFS GetVolumeInfo - Get
1674 information about a volume given its name
1675 
1676 \code
1677 int 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
1683 name is a volNameP. The volume name must be less than AFSNAMEMAX characters
1684 long, and the volume itself must reside on the File Server being probed.
1685 \par
1686 Rx connection information for the related File Server is contained in a
1687 rxConnP. Please note that definitions for the error codes with VL prefixes may
1688 be found in the vlserver.h include file
1689 \par Error Codes
1690 Could not contact any of the corresponding Volume Location Servers.
1691 VL BADNAME An improperly-formatted volume name provided.
1692 \n VL ENTDELETED An entry was found for the volume, reporting that the volume
1693 has 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 -
1697 Get basic status information for the named volume
1698 
1699 \code
1700 int 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
1709 the basic status information corresponding to that volume. This status
1710 information is stored into a volFetchStatP. A full description of this status
1711 structure is found in Section 5.1.2.8. In addition, three other facts about the
1712 volume are returned. The volume's character string name is placed into a
1713 volNameP. This name is guaranteed to be less than AFSNAMEMAX characters long.
1714 The volume's offline message, namely the string recording why the volume is
1715 off-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
1717 deposited into a offLineMsgP and a motdP is guaranteed to be less than
1718 AFSOPAQUEMAX (1,024) characters long.
1719 \par
1720 Rx connection information for the related File Server is contained in a
1721 rxConnP.
1722 \par Error Codes
1723 EACCES 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 -
1727 Set the basic status information for the named volume
1728 
1729 \code
1730 int 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
1740 that volume's basic status information to the values contained in a
1741 volStoreStatP. A full description of the fields settable by this call,
1742 including the necessary masking, is found in Section 5.1.2.9. In addition,
1743 three other items relating to the volume may be set. Non-null character strings
1744 found in a volNameP, a offLineMsgP, and a motdP will be stored in the volume's
1745 printable name, off-line message, and "Message of the Day" fields respectively.
1746 The volume name provided must be less than AFSNAMEMAX (256) characters long,
1747 and the other two strings must be less than AFSOPAQUEMAX (1,024) characters
1748 long each.
1749 \par
1750 Rx connection information for the related File Server is contained in a
1751 rxConnP.
1752 \par Error Codes
1753 EACCES 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 -
1757 Return the name of the root volume for the file system
1758 
1759 \code
1760 int 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
1765 file system and place it into a rootVolNameP. This name will always be less
1766 than AFSNAMEMAX characters long. Any File Server will respond to this call, not
1767 just the one hosting the root volume. The queried File Server first tries to
1768 discover 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,
1770 then it will return the default value, namely "root.afs".
1771 \par
1772 Rx connection information for the related File Server is contained in a
1773 rxConnP. Volume version information is returned for synchronization purposes in
1774 a volSyncP.
1775 \par Error Codes
1776 ---No error codes generated.
1777 
1778  \subsubsection sec5-1-3-18 5.1.3.18: RXAFS CheckToken - (Obsolete)
1779 Check that the given user identifier matches the one in the supplied
1780 authentication token
1781 
1782 \code
1783 int 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
1789 AFS, R. For modern systems using the Rx RPC mechanism, we always get an error
1790 return from this routine.
1791 \par
1792 Rx connection information for the related File Server is contained in a
1793 rxConnP.
1794 \par Error Codes
1795 ECONNREFUSED Always returned on Rx connections.
1796 
1797  \subsubsection sec5-1-3-19 Section 5.1.3.19: RXAFS GetTime - Get the
1798 File Server's time of day
1799 
1800 \code
1801 int 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
1807 Rx connection information contained in a rxConnP. The time is returned in
1808 elapsed seconds (a secondsP) and microseconds (a uSecondsP) since that standard
1809 unix "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
1814 information about a volume given its name
1815 
1816 \code
1817 int 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
1823 5.1.3.14), except that it returns a struct AFSVolumeInfo instead of a struct
1824 VolumeInfo. The basic difference is that struct AFSVolumeInfo also carries an
1825 accompanying 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
1828 the status information regarding a set of given file system objects
1829 
1830 \code
1831 int 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
1839 Section 5.1.3.2, except for the fact that it allows the caller to ask for the
1840 current status fields for a set of up to AFSCBMAX (50) file identifiers at
1841 once.
1842 \par
1843 Rx connection information for the related File Server is contained in a
1844 rxConnP. Volume version information is returned for synchronization purposes in
1845 a volSyncP.
1846 \par Error Codes
1847 EACCES The caller does not have the necessary access rights.
1848 \n EINVAL The number of file descriptors for which status information was
1849 requested is illegal.
1850 
1851  \subsubsection sec5-1-3-22 Section 5.1.3.22: RXAFS SetLock - Set an
1852 advisory lock on the given file identifier
1853 
1854 \code
1855 int 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
1862 are two types of locks that may be specified via a lockType: LockRead and
1863 LockWrite. An advisory lock times out after AFS LOCKWAIT (5) minutes, and must
1864 be extended in order to stay in force (see RXAFS ExtendLock(), Section
1865 5.1.3.23).
1866 \par
1867 Rx connection information for the related File Server is contained in a
1868 rxConnP. Volume version information is returned for synchronization purposes in
1869 a volSyncP.
1870 \par Error Codes
1871 EACCES 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
1876 an advisory lock on a file
1877 
1878 \code
1879 int 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
1885 caller on the file identified by a fidToBeExtendedP.
1886 \par
1887 Rx connection information for the related File Server is contained in a
1888 rxConnP. Volume version information is returned for synchronization purposes in
1889 a volSyncP.
1890 \par Error Codes
1891 EINVAL The caller does not already have the given file locked.
1892 
1893  \subsubsection sec5-1-3-24 Section 5.1.3.24: RXAFS ReleaseLock -
1894 Release the advisory lock on a file
1895 
1896 \code
1897 int 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
1903 fidToUnlockP. If this was the last lock on this file, the File Server will
1904 break all existing callbacks to this file.
1905 \par
1906 Rx connection information for the related File Server is contained in a
1907 rxConnP. Volume version information is returned for synchronization purposes in
1908 a volSyncP.
1909 \par Error Codes
1910 EACCES The caller does not have the necessary access rights.
1911 
1912  \subsubsection sec5-1-3-25 Section 5.1.3.25: RXAFS XStatsVersion - Get
1913 the version number associated with the File Server's extended statistics
1914 structure
1915 
1916 \code
1917 int 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
1922 the extended statistics structures it exports (see RXAFS GetXStats(), Section
1923 5.1.3.26). The version number is placed into a versionNumberP.
1924 \par
1925 Rx connection information for the related File Server is contained in a
1926 rxConnP.
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
1931 current contents of the specified extended statistics structure
1932 
1933 \code
1934 int 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
1943 extended statistics structure. The caller provides the version number of the
1944 data it expects to receive in a clientVersionNumber. Also provided in a
1945 collectionNumber is the numerical identifier for the desired data collection.
1946 There are currently two of these data collections defined: AFS XSTATSCOLL CALL
1947 INFO, which is the list of tallies of the number of invocations of internal
1948 File Server procedure calls, and AFS XSTATSCOLL PERF INFO, which is a list of
1949 performance-related numbers. The precise contents of these collections are
1950 described in Sections 5.1.2.7. The current version number of the File Server
1951 collections is returned in a srvVersionNumberP, and is always set upon return,
1952 even if the caller has asked for a difierent version. If the correct version
1953 number has been specified, and a supported collection number given, then the
1954 collection data is returned in a dataP. The time of collection is also
1955 returned, being placed in a timeP.
1956 \par
1957 Rx connection information for the related File Server is contained in a
1958 rxConnP.
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
1965 There are two streamed functions in the File Server RPC interface, used to
1966 fetch and store arbitrary amounts of data from a file. While some non-streamed
1967 calls pass such variable-length objects as struct AFSCBFids, these objects have
1968 a pre-determined maximum size.
1969 \par
1970 The two streamed RPC functions are also distinctive in that their single Rxgen
1971 declarations generate not one but two client-side stub routines. The first is
1972 used to ship the IN parameters off to the designated File Server, and the
1973 second to gather the OUT parameters and the error code. If a streamed
1974 definition declares a routine named X YZ(), the two resulting stubs will be
1975 named StartX YZ() and EndX YZ(). It is the application programmer's job to
1976 first invoke StartX YZ(), then manage the unbounded data transfer, then finish
1977 up by calling EndX YZ(). The first longword in the unbounded data stream being
1978 fetched from a File Server contains the number of data bytes to follow. The
1979 application then reads the specified number of bytes from the stream.
1980 \par
1981 The following sections describe the four client-side functions resulting from
1982 the Fetch-Data() and StoreData() declarations in the Rxgen interface definition
1983 file. These are the actual routines the application programmer will include in
1984 the client code. For reference, here are the interface definitions that
1985 generate these functions. Note that the split keyword is what causes Rxgen to
1986 generate the separate start and end routines. In each case, the number after
1987 the equal sign specifies the function's identifying opcode number. The opcode
1988 is passed to the File Server by the StartRXAFS FetchData() and StartRXAFS
1989 StoreData() stub routines.
1990 
1991 \code
1992 FetchData(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 
1999 StoreData(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
2009 a request to fetch file data
2010 
2011 \code
2012 int 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
2019 Begin a request for a lenInBytes bytes of data starting at byte offset a offset
2020 from the file identified by a fidToFetchP. After successful completion of this
2021 call, the data stream will make the desired bytes accessible. The first
2022 longword in the stream contains the number of bytes to actually follow.
2023 \par
2024 Rx 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 -
2029 Conclude a request to fetch file data
2030 
2031 \code
2032 int 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
2038 Conclude a request to fetch file data, as commenced by an StartRXAFS
2039 FetchData() invocation. By the time this routine has been called, all of the
2040 desired data has been read off the data stream. The status fields for the file
2041 from which the data was read are stored in a fidStatP. If the file was from a
2042 read/write volume, its callback information is placed in a callBackP.
2043 \par
2044 Rx call information to the related File Server is contained in a rxCallP.
2045 Volume version information is returned for synchronization purposes in a
2046 volSyncP.
2047 \par Error Codes
2048 EACCES The caller does not have the necessary access rights. EIO Given file
2049 could not be opened or statted on the File Server, or there was an error
2050 reading 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
2054 a request to store file data
2055 
2056 \code
2057 int 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
2065 Begin a request to write a lenInBytes of data starting at byte offset a offset
2066 to the file identified by a fidToStoreP, causing that file's length to become a
2067 fileLenInBytes bytes. After successful completion of this call, the data stream
2068 will be ready to begin accepting the actual data being written.
2069 \par
2070 Rx 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 -
2075 Conclude a request to store file data
2076 
2077 \code
2078 int 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
2084 Conclude a request to store file data, as commenced by a StartRXAFS StoreData()
2085 invocation. By the time this routine has been called, all of the file data has
2086 been inserted into the data stream. The status fields for the file to which the
2087 data was written are stored in a fidStatP. All existing callbacks to the given
2088 file are broken before the store concludes.
2089 \par
2090 Rx call information to the related File Server is contained in a rxCallP.
2091 Volume version information is returned for synchronization purposes in a
2092 volSyncP.
2093 \par Error Codes
2094 EACCES 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
2100 Usage
2101 
2102  \subsubsection sec5-1-5-1 Section 5.1.5.1: Preface
2103 
2104 \par
2105 The following code fragment is offered as an example of how to use the streamed
2106 File Server RPC calls. In this case, a client fetches some amount of data from
2107 the given File Server and writes it to a local file it uses to cache the
2108 information. For simplicity, many issues faced by a true application programmer
2109 are not addressed here. These issues include locking, managing file chunking,
2110 data version number mismatches, volume location, Rx connection management,
2111 defensive programming (e.g., checking parameters before using them),
2112 client-side cache management algorithms, callback management, and full error
2113 detection and recovery. Pseudocode is incorporated when appropriate to keep the
2114 level of detail reasonable. For further descriptions of some of these details
2115 and issues, the reader is referred to such companion documents as AFS-3
2116 Programmer's Reference: Specification for the Rx Remote Procedure Call
2117 Facility, AFS-3 Programmer's Reference:Volume Server/Volume Location Server
2118 Interface, and AFS-3 Programmer's Reference: Architectural Overview.
2119 \par
2120 A discussion of the methods used within the example code fragment follows
2121 immediately afterwards in Section 5.1.5.3.
2122 
2123  \subsubsection sec5-1-5-2 Section 5.1.5.2: Code Fragment Illustrating
2124 Fetch Operation
2125 
2126 \code
2127 int code; /*Return code*/
2128 long bytesRead; /*Num bytes read from Rx*/
2129 struct myConnInfo *connP; /*Includes Rx conn info*/
2130 struct rx_call *rxCallP; /*Rx call ptr*/
2131 struct AFSFid *afsFidP; /*Fid for file to fetch*/
2132 int lclFid; /*Fid for local cache file*/
2133 long offsetBytes; /*Starting fetch offset*/
2134 long bytesToFetch; /*Num bytes to fetch*/
2135 long bytesFromFS; /*Num bytes FileServer returns*/
2136 char *fetchBuffP; /*Buffer to hold stream data*/
2137 int 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 */ . . .
2142 rxCallP = rx_NewCall(connP->rxConnP);
2143 code = StartRXAFS_FetchData( rxCallP, /*Rx call to use*/
2144  afsFidP, /*Fid being fetched from*/
2145  offsetBytes, /*Offset in bytes*/
2146  bytesToFetch); /*Num bytes wanted*/
2147 if (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);
2166 code = 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);
2171 return(code); . . .
2172 \endcode
2173 
2174  \subsubsection sec5-1-5-3 Section 5.1.5.3: Discussion and Analysis
2175 
2176 \par
2177 The opening assumption in this discussion is that all the information required
2178 to do the fetch has already been set up. These mandatory variables are the
2179 client-side connection information for the File Server hosting the desired
2180 file, the corresponding AFS file identifier, the byte offset into the file, the
2181 number of bytes to fetch, and the identifier for the local file serving as a
2182 cached copy.
2183 \par
2184 Given the Rx connection information stored in the client's connP record, rx
2185 NewCall() is used to create a new Rx call to handle this fetch operation. The
2186 structure containing this call handle is placed into rxCallP. This call handle
2187 is used immediately in the invocation of StartRXAFS FetchData(). If this setup
2188 call fails, the fragment exits. Upon success, though, the File Server will
2189 commence writing the desired data into the Rx data stream. The File Server
2190 first writes a single longword onto the stream announcing to the client how
2191 many bytes of data will actually follow. The fragment reads this number with
2192 its first rx Read() call. Since all Rx stream data is written in network byte
2193 order, the fragment translates the byte count to its own host byte order first
2194 to properly interpret it. Once the number of bytes to appear on the stream is
2195 known, the client code proceeds to open the appropriate cache file on its own
2196 local disk and seeks to the appropriate spot within it. A buffer into which the
2197 stream data will be placed is also created at this time.
2198 \par
2199 The example code then falls into a loop where it reads all of the data from the
2200 File Server and stores it in the corresponding place in the local cache file.
2201 For each iteration, the code decides whether to read a full buffer's worth or
2202 the remaining number of bytes, whichever is smaller. After all the data is
2203 pulled off the Rx stream, the local cache file is closed. At this point, the
2204 example finishes off the RPC by calling EndRXAFS FetchData(). This gathers in
2205 the required set of OUT parameters, namely the status fields for the file just
2206 fetched, callback and volume synchronization information, and the overall error
2207 code for the streamed routine. The Rx call created to perform the fetch is then
2208 terminated and cleaned up by invoking rx EndCall().
2209 
2210  \subsection sec5-1-6 Section 5.1.6: Required Caller Functionality
2211 
2212 \par
2213 The AFS File Server RPC interface was originally designed to interact only with
2214 Cache Manager agents, and thus made some assumptions about its callers. In
2215 particular, the File Server expected that the agents calling it would
2216 potentially have stored callback state on file system objects, and would have
2217 to be periodically pinged in order to garbage-collect its records, removing
2218 information on dead client machines. Thus, any entity making direct calls to
2219 this interface must mimic certain Cache Manager actions, and respond to certain
2220 Cache Manager RPC interface calls.
2221 \par
2222 To be safe, any application calling the File Server RPC interface directly
2223 should export the entire Cache Manager RPC interface. Realistically, though, it
2224 will only need to provide stubs for the three calls from this interface that
2225 File Servers know how to make: RXAFSCB InitCallBackState(), RXAFSCB Probe() and
2226 RXAFSCB CallBack(). The very first File Server call made by this application
2227 will prompt the given File Server to call RXAFSCB InitCallBackState(). This
2228 informs the application that the File Server has no record of its existence and
2229 hence this "Cache Manager" should clear all callback information for that
2230 server. Once the application responds positively to the inital RXAFSCB
2231 InitCallBackState(), the File Server will treat it as a bona fide,
2232 fully-fledged Cache Manager, and probe it every so often with RXAFSCB Probe()
2233 calls to make sure it is still alive.
2234 
2235  \section sec5-2 Section 5.2: Signal Interface
2236 
2237 \par
2238 While the majority of communication with AFS File Servers occurs over the RPC
2239 interface, some important operations are invoked by sending unix signals to the
2240 process. This section describes the set of signals recognized by the File
2241 Server 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
2246 within the File Server process.
2247 
2248  \subsection sec5-2-1 Section 5.2.1: SIGQUIT: Server Shutdown
2249 
2250 \par
2251 Upon receipt of this signal, the File Server shuts itself down in an orderly
2252 fashion. 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
2254 then flushes all modified buffers and prints out a set of internal statistics,
2255 including cache and disk numbers. Finally, each attached volume is taken
2256 offline, which means the volume header is written to disk with the appropriate
2257 bits set.
2258 \par
2259 In typical usage, human operators do not send the SIGQUIT signal directly to
2260 the File Server in order to affect an orderly shutdown. Rather, the BOS Server
2261 managing the server processes on that machine issues the signal upon receipt of
2262 a properly-authorized shutdown RPC request.
2263 
2264  \subsection sec5-2-2 Section 5.2.2: SIGTSTP: Upgrade Debugging Level
2265 
2266 \par
2267 Arrival of a SIGTSTP signal results in an increase of the debugging level used
2268 by the File Server. The routines used for writing to log files are sensitive to
2269 this debugging level, as recorded in the global LogLevel variable.
2270 Specifically, these routines will only generate output if the value of LogLevel
2271 is greater than or equal to the value of its threshold parameter. By default,
2272 the File Server sets LogLevel to zero upon startup. If a SIGTSTP signal is
2273 received when the debugging level is zero, it will be bumped to 1. If the
2274 signal arrives when the debugging level is positive, its value will be
2275 multiplied by 5. Thus, as more SIGTSTPs are received, the set of debugging
2276 messages eligible to be delivered to log files grows.
2277 \par
2278 Since the SIGTSTP signal is not supported under IBM's AIX 2.2.1 operating
2279 system, this form of debugging output manipulation is not possible on those
2280 platforms.
2281 
2282  \subsection sec5-2-3 Section 5.2.3: SIGHUP: Reset Debugging Level
2283 
2284 \par
2285 Receiving a SIGHUP signal causes a File Server to reset its debugging level to
2286 zero. This effectively reduces the set of debugging messages eligible for
2287 delivery to log files to a bare minimum. This signal is used in conjunction
2288 with SIGTSTP to manage the verbosity of log information.
2289 \par
2290 Since the SIGHUP signal is not supported under IBM's AIX 2.2.1 operating
2291 system, this form of debugging output manipulation is not possible on those
2292 platforms.
2293 
2294  \subsection sec5-2-4 Section 5.2.4: SIGTERM: File Descriptor Check
2295 
2296 \par
2297 Receipt of a SIGTERM signal triggers a routine which sweeps through the given
2298 File Server's unix file descriptors. For each possible unix fid slot, an
2299 fstat() is performed on that descriptor, and the particulars of each open file
2300 are printed out. This action is designed solely for debugging purposes.
2301 
2302  \section sec5-3 Section 5.3: Command Line Interface
2303 
2304 \par
2305 Another interface exported by the File Server is the set of command line
2306 switches it accepts. Using these switches, many server parameters and actions
2307 can be set. Under normal conditions, the File Server process is started up by
2308 the BOS Server on that machine, as described in AFS-3 Programmer's Reference:
2309 BOS Server Interface. So, in order to utilize any combination of these
2310 command-line options, the system administrator must define the File Server
2311 bnode in such a way that these parameters are properly included. Note that the
2312 switch names must be typed exactly as listed, and that abbreviations are not
2313 allowed. Thus, specifying -b 300 on the command line is unambiguous, directing
2314 that 300 buffers are to be allocated. It is not an abbreviation for the -banner
2315 switch, asking that a message is to be printed to the console periodically.
2316 \par
2317 A 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
2319 system startup. If this switch is not provided, the File Server will operate
2320 with 70 such buffers by default.
2321 \li -banner This switch instructs the File Server to print messages to the
2322 console every 10 minutes to demonstrate it is still running correctly. The text
2323 of the printed message is: File Server is running at <time>.
2324 \li -cb <# callbacks stored> Specify the maximum number of callback records
2325 stored simultaneously by the File Server. The default pool size is 20,000
2326 records.
2327 \li -d <debug level> Set the debugging output level at which File Server runs
2328 to the value provided. Specifically, the LogLevel global variable is set to the
2329 given value (See Section 5.2.2). If this switch is not provided, the default
2330 initial File Server debugging level is set to zero, producing the minimal
2331 debugging output to the log files.
2332 \li -k <stack size> Set the stack size to provide server LWPs upon creation,
2333 measured in 1,024-byte blocks. The default LWP stack size is 24 blocks, or
2334 24,576 bytes.
2335 \li -l <large (directory) vnodes> Select the number of "large" vnodes the File
2336 Server will cache. These vnodes are suitable for recording information about
2337 AFS directories. The extra space in the vnode allows ACL information to be
2338 stored along with the directory. The default allocation value is 200 directory
2339 vnodes.
2340 \li -pctspare <percent overrun blocks past quota> Similar to the -spare switch,
2341 except that the number of allowable overrun blocks is expressed as a percentage
2342 of the given volume's quota. Note: this switch cannot be used in combination
2343 with the -spare switch.
2344 \li -rxdbg Instruct the File Server to open a file named rx dbg in the current
2345 directory, into which the Rx package will write general debugging information.
2346 If the file is already open (due to the appearance of the -rxdbge switch
2347 earlier 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
2349 directory, into which the Rx package will write debugging information related
2350 to its event-scheduling activities. If the file is already open (due to the
2351 appearance of the -rxdbg switch earlier in the command line), this results in a
2352 no-op.
2353 \li -rxpck <# packets> Set the number of extra Rx packet buffers to hold in
2354 reserve. These pre-allocated buffers assist in responding to spikes in network
2355 traffic demands. By default, 100 such packet buffers are maintained.
2356 \li -s <small (file) vnodes> Select the number of "small" vnodes the File
2357 Server will cache. These vnodes are suitable for recording information about
2358 non-directory files. As with directory vnodes, the File Server will allocate
2359 200 small vnodes by default.
2360 \li -spare <# overrun blocks to allow> Tell the File Server to allow users
2361 performing a store operation to overrun the host volume's disk quota by a
2362 certain number of (1,024-byte) blocks. In other words, the first store
2363 resulting in a quota overrun will be allowed to succeed if and only if it uses
2364 no more than these many blocks beyond the quota. Further store operations will
2365 be rejected until the volume's storage is once again reduced below quota. By
2366 default, overruns of 1,024 blocks of 1,024 bytes each (1 megabyte total) are
2367 tolerated. Note: this switch cannot be used in combination with the -pctspare
2368 switch.
2369 \li -w <callback wait interval in seconds> This switch determines how often the
2370 File Server periodic daemon lightweight processes run. Among other things,
2371 these daemon LWPs check on the validity of callback records, keep disk usage
2372 statistics up to date, and check the health of the various client machines that
2373 have previously interacted with the File Server. For a full description of
2374 these daemon LWPs, consult Section 2.3. The associated argument specifies the
2375 number of seconds to sleep between daemon invocations. By default, these
2376 periodic 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
2383 There are several interfaces offered by the Cache Manager, allowing clients to
2384 access the files stored by the community of AFS File Servers, to configure the
2385 Cache Manager's behavior and resources, to store and retrieve authentication
2386 information, to specify the location of community Authentication Server and
2387 Volume Location Server services, and to observe and debug the Cache Manager's
2388 state and actions. This chapter will cover the following five interfaces to the
2389 Cache Manager:
2390 \li ioctl(): The standard unix ioctl() system call has been extended to
2391 include more operations, namely waiting until data stores to a File Server
2392 complete before returning to the caller (VIOCCLOSEWAIT) and getting the name of
2393 the cell in which an open file resides (VIOCIGETCELL).
2394 \li pioctl(): An additional system call is provided through which
2395 applications can access operations specific to AFS, which are often tied to a
2396 particular pathname. These operations include Access Control List (ACL) and
2397 mount point management, Kerberos ticket management, cache configuration, cell
2398 configuration, and status of File Servers.
2399 \li RPC: Interface by which outside servers and investigators can
2400 manipulate the Cache Manager. There are two main categories of routines:
2401 callback management, typically called by the File Server, and
2402 debugging/statistics, called by programs such as cmdebug and via the xstat
2403 user-level library for collection of extended statistics.
2404 \li Files: Much of the Cache Manager's configuration information, as well
2405 as its view of the AFS services available from the outside world, is obtained
2406 from 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
2408 usually found in /usr/vice/cache, namely CacheItems, VolumeItems, and AFSLog.
2409 \li Mariner: This is the interface by which file transfer activity between
2410 the Cache Manager and File Servers may be monitored. Specifically, it is used
2411 to monitor the names of the files and directories being fetched and/or stored
2412 over the network.
2413 \par
2414 Another important component not described in this document is the afsd program.
2415 It is afsd's job to initialize the Cache Manager on a given machine and to
2416 start up its related daemon threads. It accepts a host of configuration
2417 decisions via its command-line interface. In addition, it parses some of the
2418 information kept in the configuration files mentioned above and passes that
2419 information to the Cache Manager. The reader may find a full description of
2420 afsd in the AFS 3.0 Command Reference Manual[2].
2421 
2422  \section sec6-2 Section 6.2: Definitions
2423 
2424 \par
2425 This 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
2430 The Cache Manager is the sole active AFS agent aware of the cellular
2431 architecture of the system. Since AFS file identifiers are not guaranteed to be
2432 unique across cell boundaries, it must further qualify them for its own
2433 internal bookkeeping. The struct VenusFid provides just such additional
2434 qualification, attaching the Cache Manager's internal cell identifier to the
2435 standard 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
2443 This is the clear-text version of an AFS token of identity. Its fields are
2444 encrypted into the secret token format, and are made easily available to the
2445 Cache 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
2451 came into effect.
2452 \li long EndTimestamp - Timestamp of when this token is considered to be
2453 expired, and thus disregarded.
2454 
2455  \section sec6-3 Section 6.3: ioctl() Interface
2456 
2457 \par
2458 The standard unix ioctl() system call performs operations on file system
2459 objects referenced with an open file descriptor. AFS has augmented this system
2460 call with two additional operations, one to perform "safe stores", and one to
2461 get the name of the cell in which a file resides. A third ioctl() extension is
2462 now 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
2468 resumes once the store operation on the given file data to the host File Server
2469 has commenced but before it has completed. Thus, it is possible that the store
2470 could actually fail (say, because of network partition or server crashes)
2471 without the client's knowledge. This new ioctl opcode specifies to the Cache
2472 Manager that all future close() operations will wait until the associated store
2473 operation 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.
2479 The original intention of this call was to allow a store operation currently in
2480 progress 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
2486 is not an AFS file, then ENOTTY is returned. The output buffer specified in the
2487 data area must be large enough to hold the null-terminated string representing
2488 the file's cell, otherwise EFAULT is returned. However, an out size value of
2489 zero specifies that the cell name is not to be copied into the output buffer.
2490 In this case, the caller is simply interested in whether the file is in AFS,
2491 and 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
2498 There is a new unix system call, pioctl(), which has been defined especially to
2499 support the AFS Cache Manager. Its functional definition is as follows:
2500 \code
2501 int 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
2507 This new call is much like the standard ioctl() call, but differs in that the
2508 affected file (when applicable) is specified by its path, not by a file
2509 descriptor. Another difference is the fourth parameter, a followSymLinks,
2510 determines which file should be used should a pathP be a symbolic link. If a
2511 followSymLinks be set to 1, then the symbolic link is followed to its target,
2512 and the pioctl() is applied to that resulting file. If a followSymLinks is set
2513 to 0, then the pioctl() applies to the symbolic link itself.
2514 \par
2515 Not all pioctl() calls affect files. In those cases, the a pathP parameter
2516 should be set to a null pointer. The second parameter to pioctl(), a opcode,
2517 specifies which operation is to be performed. The opcode for each of these
2518 operations is included in the text of the description. Note that not all
2519 pioctl() opcodes are in use. These unused values correspond to obsolete
2520 operations.
2521 \par
2522 The descriptions that follow identify some of the possible error codes for each
2523 pioctl() opcode, but do not offer a comprehensive lists. All pioctl() calls
2524 return 0 upon success.
2525 \par
2526 The rest of this section proceeds to describe the individual opcodes available.
2527 First, though, one asymmetry in this opcode set is pointed out, namely that
2528 while various operations are defined on AFS mount points, there is no direct
2529 way to create a mount point.
2530 \par
2531 This 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
2541 For all pioctl()s, the fields within the a paramsP parameter will be referred
2542 to directly. Thus, the values of in, in size, out, and out size are discussed,
2543 rather than the settings for a paramsP->in, a paramsP->in size, a paramsP->out,
2544 and a paramsP->out size.
2545 \par
2546 For convenience of reference, a list of the actively-supported pioctl()s, their
2547 opcodes, 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
2584 There is an irregularity which deserves to be mentioned regarding the pioctl()
2585 interface. There are pioctl() operations for getting information about a mount
2586 point (VIOC AFS STAT MT PT) and for deleting a mount point (VIOC AFS DELETE MT
2587 PT), but no operation for creating mount points. To create a mount point, a
2588 symbolic link obeying a particular format must be created. The first character
2589 must be either a "%" or a "#", depending on the type of mount point being
2590 created (see the discussion in Section 6.4.4.4). If the mount point carries the
2591 name of the cell explicitly, the full cell name will appear next, followed by a
2592 colon. In all cases, the next portion of the mount point is the volume name. By
2593 convention, the last character of a mount point must always be a period (".").
2594 This 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
2599 There are several pioctl() opcodes dealing with AFS volumes. It is possible to
2600 get and set volume information (VIOCGETVOLSTAT, VIOCSETVOLSTAT), discover which
2601 volume hosts a particular file system object (VIOCWHEREIS), remove all objects
2602 cached from a given volume (VIOC FLUSHVOLUME), and revalidate cached volume
2603 information (VIOCCKBACK).
2604 
2605  \subsubsection sec6-4-3-1 Section 6.4.3.1: VIOCGETVOLSTAT: Get volume
2606 status for pathname
2607 
2608 \par
2609 [Opcode 4] Fetch information concerning the volume that contains the file
2610 system object named by a pathP. There is no other input for this call, so in
2611 size should be set to zero. The status information is placed into the buffer
2612 named by out, if out size is set to a value of sizeof(struct VolumeStatus) or
2613 larger. Included in the volume information are the volume's ID, quota, and
2614 number of blocks used in the volume as well as the disk partition on which it
2615 resides. Internally, the Cache Manager calls the RXAFS GetVolumeInfo() RPC (See
2616 Section 5.1.3.14) to fetch the volume status.
2617 \par
2618 Among the possible error returns, EINVAL indicates that the object named by a
2619 pathP could not be found.
2620 
2621  \subsubsection sec6-4-3-2 Section 6.4.3.2: VIOCSETVOLSTAT: Set volume
2622 status for pathname
2623 
2624 \par
2625 [Opcode 5] Set the status fields for the volume hosting the file system object
2626 named by a pathP. The first object placed into the input buffer in is the new
2627 status image. Only those fields that may change, namely MinQuota and MaxQuota
2628 fields, are interpreted upon receipt by the File Server, and are set to the
2629 desired values. Immediately after the struct VolumeStatus image, the caller
2630 must place the null-terminated string name of the volume involved in the input
2631 buffer. New settings for the offline message and MOTD (Message of the Day)
2632 strings may appear after the volume name. If there are no changes in the
2633 offline and/or MOTD messages, a null string must appear for that item. The in
2634 size parameter must be set to the total number of bytes so inserted, including
2635 the nulls after each string. Internally, the Cache Manager calls the RXAFS
2636 SetVolumeStatus() RPC (See Section 5.1.3.16) to store the new volume status.
2637 \par
2638 Among the possible error returns, EINVAL indicates that the object named by a
2639 pathP could not be found.
2640 
2641  \subsubsection sec6-4-3-3 Section 6.4.3.3: VIOCWHEREIS: Find the
2642 server(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
2646 system object named by a pathP resides. The input buffer in is not used by this
2647 call, so in size should be set to zero. The output buffer indicated by out is
2648 filled with up to 8 IP addresses, one for each File Server hosting the
2649 indicated volume. Thus, out size should be set to at least (8*sizeof(long)).
2650 This group of hosts is terminated by the first zeroed IP address that appears
2651 in the list, but under no circumstances are more than 8 host IP addresses
2652 returned.
2653 \par
2654 Among the possible error returns is EINVAL, indicating that the pathname is not
2655 in AFS, hence is not contained within a volume. If ENODEV is returned, the
2656 associated volume information could not be obtained.
2657 
2658  \subsubsection sec6-4-3-4 Section 6.4.3.4: VIOC FLUSHVOLUME: Flush all
2659 data cached from the pathname's volume
2660 
2661 \par
2662 [Opcode 37] Determine the volume in which the file system object named by a
2663 pathP resides, and then throw away all currently cached copies of files that
2664 the Cache Manager has obtained from that volume. This call is typically used
2665 should a user suspect there is some cache corruption associated with the files
2666 from a given volume.
2667 
2668  \subsubsection sec6-4-3-5 Section 6.4.3.5: VIOCCKBACK: Check validity
2669 of all cached volume information
2670 
2671 \par
2672 [Opcode 11] Ask the Cache Manager to check the validity of all cached volume
2673 information. None of the call's parameters are referenced in this call, so a
2674 pathP and in should be set to the null pointer, and in size and out size should
2675 be set to zero.
2676 \par
2677 This operation is performed in two steps:
2678 \li 1 The Cache Manager first refreshes its knowledge of the root volume,
2679 usually named root.afs. On success, it wakes up any of its own threads waiting
2680 on the arrival of this information, should it have been previously unreachable.
2681 This typically happens should the Cache Manager discover in its startup
2682 sequence that information on the root volume is unavailable. Lacking this
2683 knowledge at startup time, the Cache Manager settles into a semi-quiescent
2684 state, checking every so often to see if volume service is available and thus
2685 may complete its own initialization.
2686 \li 2 Each cached volume record is flagged as being stale. Any future attempt
2687 to access information from these volumes will result in the volume record's
2688 data first being refreshed from the Volume Location Server.
2689 
2690  \subsection sec6-4-4 Section 6.4.4: File Server Operations
2691 
2692 \par
2693 One group of pioctl() opcodes is aimed at performing operations against one or
2694 more File Servers directly. Specifically, a caller may translate a pathname
2695 into the corresponding AFS fid (VIOCGETFID), unilaterally discard a set of
2696 callback promises (VIOCFLUSHCB), get status on mount points (VIOC AFS STAT MT
2697 PT), delete unwanted mount points (VIOC AFS DELETE MT PT), and check the health
2698 of a group of File Servers(VIOCCKSERV).
2699 
2700  \subsubsection sec6-4-4-1 Section 6.4.4.1: VIOCGETFID: Get augmented
2701 fid for named file system object
2702 
2703 \par
2704 [Opcode 22] Return the augmented file identifier for the file system object
2705 named by a pathP. The desired struct VenusFid is placed in the output buffer
2706 specified by out. The output buffer size, as indicated by the out size
2707 parameter, must be set to the value of sizeof(struct VenusFid) or greater. The
2708 input buffer is not referenced in this call, so in should be set to the null
2709 pointer and in size set to zero.
2710 \par
2711 Among the possible error returns, EINVAL indicates that the object named by a
2712 pathP was not found.
2713 
2714  \subsubsection sec6-4-4-2 Section 6.4.4.2: VIOCFLUSHCB: Unilaterally
2715 drop a callback
2716 
2717 \par
2718 [Opcode 25] Remove any callback information kept by the Cache Manager on the
2719 file system object named by a pathP. Internally, the Cache Manager executes a
2720 call to the RXAFS GiveUpCallBacks() RPC (See Section 5.1.3.13) to inform the
2721 appropriate File Server that it is being released from its particular callback
2722 promise. Note that if the named file resides on a read-only volume, then the
2723 above call is not made, and success is returned immediately. This optimization
2724 is possible because AFS File Servers do not grant callbacks on files from
2725 read-only volumes.
2726 \par
2727 Among the possible error returns is EINVAL, which indicates that the object
2728 named by a pathP was not found.
2729 
2730  \subsubsection sec6-4-4-3 Section 6.4.4.3: VIOC AFS DELETE MT PT:
2731 Delete a mount point
2732 
2733 \par
2734 [Opcode 28] Remove an AFS mount point. The name of the directory in which the
2735 mount point exists is specified by a pathP, and the string name of the mount
2736 point within this directory is provided through the in parameter. The input
2737 buffer length, in size, is set to the length of the mount point name itself,
2738 including the trailing null. The output buffer is not accessed by this call, so
2739 out should be set to the null pointer and out size to zero.
2740 \par
2741 One important note is that the a followSymLinks argument must be set to zero
2742 for correct operation. This is counter-intuitive, since at first glance it
2743 seems that a symbolic link that resolves to a directory should be a valid
2744 pathname parameter. However, recall that mount points are implemented as
2745 symbolic links that do not actually point to another file system object, but
2746 rather simply contain cell and volume information (see the description in
2747 Section 6.4.2). This "special" symbolic link must not be resolved by the
2748 pioctl(), but rather presented as-is to the Cache Manager, which then properly
2749 interprets it and generates a reference to the given volume's root directory.
2750 As an unfortunate side-effect, a perfectly valid symbolic link referring to a
2751 directory will be rejected out of hand by this operation as a value for the a
2752 pathP parameter.
2753 \par
2754 Among the possible error returns, EINVAL reports that the named directory was
2755 not found, and ENOTDIR indicates that the pathname contained within a pathP is
2756 not a directory.
2757 
2758  \subsubsection sec6-4-4-4 Section 6.4.4.4: VIOC AFS STAT MT PT: Get the
2759 contents of a mount point
2760 
2761 \par
2762 [Opcode 29] Return the contents of the given mount point. The directory in
2763 which the mount point in question resides is provided via the a pathP argument,
2764 and the in buffer contains the name of the mount point object within this
2765 directory. As usual, in size is set to the length of the input buffer,
2766 including the trailing null. If the given object is truly a mount point and the
2767 out buffer is large enough (its length appears in out size), the mount point's
2768 contents are stored into out.
2769 \par
2770 The mount point string returned obeys a stylized format, as fully described in
2771 Section 5.6.2 of the AFS 3.0 System Administrator's Guide[1]. Briefly, a
2772 leading pound sign ("#") indicates a standard mount point, inheriting the
2773 read-only or read-write preferences of the mount point's containing volume. On
2774 the other hand, a leading percent sign ("%") advises the Cache Manager to cross
2775 into the read-write version of the volume, regardless of the existence of
2776 read-only clones. If a colon (":") separator occurs, the portion up to the
2777 colon itself denotes the fully-qualified cell name hosting the volume. The rest
2778 of the string is the volume name itself.
2779 \par
2780 Among the possible error codes is EINVAL, indicating that the named object is
2781 not an AFS mount point. Should the name passed in a pathP be something other
2782 than a directory, then ENOTDIR is returned.
2783 
2784  \subsubsection sec6-4-4-5 Section 6.4.4.5: VIOCCKSERV: Check the status
2785 of one or more File Servers
2786 
2787 \par
2788 [Opcode 10] Check the status of the File Servers that have been contacted over
2789 the lifetime of the Cache Manager. The a pathP parameter is ignored by this
2790 call, so it should be set to the null pointer. The input parameters as
2791 specified by in are completely optional. If something is placed in the input
2792 buffer, namely in size is not zero, then the first item stored there is a
2793 longword used as a bit array of flags. These flags carry instructions as to the
2794 domain and the "thoroughness" of this check.
2795 \par
2796 Only the settings of the least-significant two bits are recognized. Enabling
2797 the lowest bit tells the Cache Manager not to ping its list of servers, but
2798 simply report their status as contained in the internal server records.
2799 Enabling the next-higher bit limits the search to only those File Servers in a
2800 given cell. If in size is greater than sizeof(long),a null-terminated cell name
2801 string follows the initial flag array, specifying the cell to check. If this
2802 search bit is set but no cell name string follows the longword of flags, then
2803 the search is restricted to those servers contacted from the same cell as the
2804 caller.
2805 \par
2806 This call returns at least one longword into the output buffer out, specifying
2807 the number of hosts it discovered to be down. If this number is not zero, then
2808 the longword IP address for each dead (or unreachable) host follows in the
2809 output buffer. At most 16 server addresses will be returned, as this is the
2810 maximum number of servers for which the Cache Manager keeps information.
2811 \par
2812 Among the possible error returns is ENOENT, indicating that the optional cell
2813 name 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
2818 The Cache Manager is the only active AFS agent that understands the system's
2819 cellular architecture. Thus, it keeps important information concerning the
2820 identities of the cells in the community, which cell is in direct
2821 administrative control of the machine upon which it is running, status and
2822 configuration of its own cell, and what cell-specific operations may be legally
2823 executed. The following pioctl()s allow client processes to access and update
2824 this cellular information. Supported operations include adding or updating
2825 knowledge 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
2828 FILE CELL NAME), discovering the cell to which the machine belongs (VIOC GET WS
2829 CELL), finding out the caller's "primary" cell (VIOC GET PRIMARY CELL), and
2830 getting/setting certain other per-cell system parameters (VIOC GETCELLSTATUS,
2831 VIOC SETCELLSTATUS).
2832 
2833  \subsubsection sec6-4-5-1 Section 6.4.5.1: VIOCNEWCELL: Set cell
2834 service information
2835 
2836 \par
2837 [Opcode 26] Give the Cache Manager all the information it needs to access an
2838 AFS cell. Exactly eight longwords are placed at the beginning of the in input
2839 buffer. These specify the IP addresses for the machine providing AFS
2840 authentication and volume location authentication services. The first such
2841 longword set to zero will signal the end of the list of server IP addresses.
2842 After these addresses, the input buffer hosts the null-terminated name of the
2843 cell to which the above servers belong. The a pathP parameter is not used, and
2844 so should be set to the null pointer.
2845 \par
2846 Among the possible error returns is EACCES, indicating that the caller does not
2847 have the necessary rights to perform the operation. Only root is allowed to set
2848 cell server information. If either the IP address array or the server name is
2849 unacceptable, EINVAL will be returned.
2850 
2851  \subsubsection sec6-4-5-2 Section 6.4.5.2: VIOCGETCELL: Get cell
2852 configuration entry
2853 
2854 \par
2855 [Opcode 27] Get the i'th cell configuration entry known to the Cache Manager.
2856 The index of the desired entry is placed into the in input buffer as a
2857 longword, with the first legal value being zero. If there is a cell associated
2858 with the given index, the output buffer will be filled with an array of 8
2859 longwords, followed by a null-terminated string.
2860 \par
2861 The longwords correspond to the list of IP addresses of the machines providing
2862 AFS authentication and volume location services. The string reflects the name
2863 of the cell for which the given machines are operating. There is no explicit
2864 count returned of the number of valid IP addresses in the longword array.
2865 Rather, the list is terminated by the first zero value encountered, or when the
2866 eighth slot is filled.
2867 \par
2868 This routine is intended to be called repeatedly, with the index starting at
2869 zero and increasing each time. The array of cell information records is kept
2870 compactly, without holes. A return value of EDOM indicates that the given index
2871 does not map to a valid entry, and thus may be used as the terminating
2872 condition for the iteration.
2873 
2874  \subsubsection sec6-4-5-3 Section 6.4.5.3: VIOC FILE CELL NAME: Get
2875 cell hosting a given object
2876 
2877 \par
2878 [Opcode 30] Ask the Cache Manager to return the name of the cell in which the
2879 file system object named by a pathP resides. The input arguments are not used,
2880 so in should be set to the null pointer and in size should be set to zero. The
2881 null-terminated cell name string is returned in the out output buffer.
2882 \par
2883 Among the possible error values, EINVAL indicates that the pathname provided in
2884 a pathP is illegal. If there is no cell information associated with the given
2885 object, ESRCH is returned.
2886 
2887  \subsubsection sec6-4-5-4 Section 6.4.5.4: VIOC GET WS CELL: Get
2888 caller's home cell name
2889 
2890 \par
2891 [Opcode 31] Return the name of the cell to which the caller's machine belongs.
2892 This cell name is returned as a null-terminated string in the output buffer.
2893 The input arguments are not used, so in should be set to the null pointer and
2894 in size should be set to zero.
2895 \par
2896 Among the possible error returns is ESRCH, stating that the caller's home cell
2897 information was not available.
2898 
2899  \subsubsection sec6-4-5-5 Section 6.4.5.5: VIOC GET PRIMARY CELL: Get
2900 the caller's primary cell
2901 
2902 \par
2903 [Opcode 33] Ask the Cache Manager to return the name of the caller's primary
2904 cell. Internally, the Cache Manager scans its user records, and the cell
2905 information referenced by that record is used to extract the cell's string
2906 name. The input arguments are not used, so in should be set to the null pointer
2907 and in size should be set to zero. The a pathP pathname argument is not used
2908 either, and should similarly be set to the null pointer. The null-terminated
2909 cell name string is placed into the output buffer pointed to by out if it has
2910 suffcient room.
2911 \par
2912 Among the possible error returns is ESRCH, stating that the caller's primary
2913 cell information was not available.
2914 
2915  \subsubsection sec6-4-5-6 Section 6.4.5.6: VIOC GETCELLSTATUS: Get
2916 status info for a cell entry
2917 
2918 \par
2919 [Opcode 35] Given a cell name, return a single longword of status flags from
2920 the Cache Manager's entry for that cell. The null-terminated cell name string
2921 is expected to be in the in parameter, with in size set to its length plus one
2922 for the trailing null. The status flags are returned in the out buffer, which
2923 must have out size set to sizeof(long) or larger.
2924 \par
2925 The 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
2929 used. While defined, this flag should no longer be set in modern systems.
2930 
2931 \par
2932 Among the possible error returns is ENOENT, informing the caller that the Cache
2933 Manager has no knowledge of the given cell name.
2934 
2935  \subsubsection sec6-4-5-7 Section 6.4.5.7: VIOC SETCELLSTATUS: Set
2936 status 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
2940 be set, record the association in the Cache Manager. The input buffer in must
2941 be set up as follows. The first entry is the longword containing the cell
2942 status bits to be set (see the VIOC GETCELLSTATUS description above for valid
2943 flag definitions). The next entry is another longword, ignored by the Cache
2944 Manager. The third and final entry in the input buffer is a null-terminated
2945 string containing the name of the cell for which the status flags are to be
2946 applied.
2947 \par
2948 Among the possible error returns is ENOENT, reflecting the Cache Manager's
2949 inability to locate its record for the given cell. Only root is allowed to
2950 execute this operation, and an EACCES return indicates the caller was not
2951 effectively root when the call took place.
2952 
2953  \subsection sec6-4-6 Section 6.4.6: Authentication Operations
2954 
2955 \par
2956 The Cache Manager serves as the repository for authentication information for
2957 AFS clients. Each client process belongs to a single Process Authentication
2958 Group (PAG). Each process in a given PAG shares authentication information with
2959 the other members, and thus has the identical rights with respect to AFS Access
2960 Control Lists (ACLs) as all other processes in the PAG. As the Cache Manager
2961 interacts with File Servers as a client process' agent, it automatically and
2962 transparently presents the appropriate authentication information as required
2963 in order to gain the access to which the caller is entitled. Each PAG can host
2964 exactly one token per cell. These tokens are objects that unequivocally codify
2965 the principal's identity, and are encrypted for security. Token operations
2966 between a Cache Manager and File Server are also encrypted, as are the
2967 interchanges between clients and the Authentication Servers that generate these
2968 tokens.
2969 \par
2970 There are actually two different flavors of tokens, namely clear and secret.
2971 The data structure representing clear tokens is described in Section 6.2.2, and
2972 the secret token appears as an undifferentiated byte stream.
2973 \par
2974 This section describes the operations involving these tokens, namely getting
2975 and setting the caller's token for a particular cell (VIOCGETTOK, VIOCSETTOK),
2976 checking a caller's access on a specified file system object (VIOCACCESS),
2977 checking the status of caller's tokens associated with the set of File Server
2978 connections maintained on its behalf (VIOCCKCONN), and discarding tokens
2979 entirely (VIOCUNLOG, VIOCUNPAG). These abilities are used by such programs as
2980 login, klog, unlog, and tokens, which must generate, manipulate, and/or destroy
2981 AFS tokens.
2982 
2983  \subsubsection sec6-4-6-1 Section 6.4.6.1: VIOCSETTOK: Set the caller's
2984 token for a cell
2985 
2986 \par
2987 [Opcode 3] Store the caller's secret and clear tokens within the Cache Manager.
2988 The input buffer is used to hold the following quantities, laid out end to end.
2989 The first item placed in the buffer is a longword, specifying the length in
2990 bytes of the secret token, followed by the body of the secret token itself. The
2991 next field is another longword, this time describing the length in bytes of the
2992 struct ClearToken, followed by the structure. These are all required fields.
2993 The caller may optionally include two additional fields, following directly
2994 after the required ones. The first optional field is a longword which is set to
2995 a non-zero value if the cell in which these tokens were generated is to be
2996 marked as the caller's primary cell. The second optional argument is a
2997 null-terminated string specifying the cell in which these tokens apply. If
2998 these two optional arguments do not appear, the Cache Manager will default to
2999 using its home cell and marking the entry as non-primary. The a pathP pathname
3000 parameter is not used, and thus should be set to the null pointer.
3001 \par
3002 If the caller does not have any tokens registered for the cell, the Cache
3003 Manager will store them. If the caller already has tokens for the cell, the new
3004 values will overwrite their old values. Because these are stored per PAG, the
3005 new tokens will thus determine the access rights of all other processes
3006 belonging to the PAG.
3007 \par
3008 Among the possible error returns is ESRCH, indicating the named cell is not
3009 recognized, 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
3012 token for a cell
3013 
3014 \par
3015 [Opcode 8] Get the specified authentication tokens associated with the caller.
3016 The a pathP parameter is not used, so it should be set to the null pointer.
3017 Should the input parameter in be set to a null pointer, then this call will
3018 place the user's tokens for the machine's home cell in the out output buffer,
3019 if such tokens exist. In this case, the following objects are placed in the
3020 output buffer. First, a longword specifying the number of bytes in the body of
3021 the secret token is delivered, followed immediately by the secret token itself.
3022 Next is a longword indicating the length in bytes of the clear token, followed
3023 by the clear token. The input parameter may also consist of a single longword,
3024 indicating the index of the token desired. Since the Cache Manager is capable
3025 of storing multiple tokens per principal, this allows the caller to iteratively
3026 extract the full set of tokens stored for the PAG. The first valid index value
3027 is zero. The list of tokens is kept compactly, without holes. A return value of
3028 EDOM indicates that the given index does not map to a valid token entry, and
3029 thus may be used as the terminating condition for the iteration.
3030 \par
3031 Other than EDOM, another possible error return is ENOTCONN, specifying that the
3032 caller does not have any AFS tokens whatsoever.
3033 
3034  \subsubsection sec6-4-6-3 Section 6.4.6.3: VIOCACCESS: Check caller's
3035 access on object
3036 
3037 \par
3038 [Opcode 20] This operation is used to determine whether the caller has specific
3039 access rights on a particular file system object. A single longword is placed
3040 into the input buffer, in, representing the set of rights in question. The
3041 acceptable values for these access rights are listen in Section 6.4.5. The
3042 object to check is named by the a pathP parameter. The output parameters are
3043 not accessed, so out should be set to the null pointer, and out size set to
3044 zero.
3045 If the call returns successfully, the caller has at least the set of rights
3046 denoted 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
3049 caller's tokens/connections
3050 
3051 \par
3052 [Opcode 12] Check whether the suite of File Server connections maintained on
3053 behalf of the caller by the Cache Manager has valid authentication tokens. This
3054 function always returns successfully, communicating the health of said
3055 connections by writing a single longword value to the specified output buffer
3056 in out. If zero is returned to the output buffer, then two things are true.
3057 First, the caller has tokens for at least one cell. Second, all tokens
3058 encountered 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
3060 expired. If these conditions do not currently hold for the caller, then the
3061 output buffer value will be set to EACCES. Neither the a pathP nor input
3062 parameters are used by this call.
3063 
3064  \subsubsection sec6-4-6-5 Section 6.4.6.5: VIOCUNLOG: Discard
3065 authentication information
3066 
3067 \par
3068 [Opcode 9] Discard all authentication information held in trust for the caller.
3069 The Cache Manager sweeps through its user records, destroying all of the
3070 caller's associated token information. This results in reducing the rights of
3071 all processes within the caller's PAG to the level of file system access
3072 granted to the special system:anyuser group.
3073 \par
3074 This operation always returns successfully. None of the parameters are
3075 referenced, so they should all be set to null pointers and zeroes as
3076 appropriate.
3077 
3078  \subsubsection sec6-4-6-6 Section 6.4.6.6: VIOCUNPAG: Discard
3079 authentication information
3080 
3081 \par
3082 [Opcode 21] This call is essentially identical to the VIOCUNLOG operation, and
3083 is 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
3088 This set of opcodes allows manipulation of AFS Access Control Lists (ACLs).
3089 Callers are allowed to fetch the ACL on a given directory, or to set the ACL on
3090 a directory. In AFS-3, ACLs are only maintained on directories, not on
3091 individual files. Thus, a directory ACL determines the allowable accesses on
3092 all 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
3094 directory, the ACL operation will be performed on the directory in which the
3095 given file resides.
3096 \par
3097 These pioctl() opcodes deal only in external formats for ACLs, namely the
3098 actual text stored in an AFS ACL container. This external format is a character
3099 string, composed of a descriptive header followed by some number of individual
3100 principal-rights pairs. AFS ACLs actually specify two sublists, namely the
3101 positive and negative rights lists. The positive list catalogues the set of
3102 rights that certain principals (individual users or groups of users) have,
3103 while the negative list contains the set of rights specifically denied to the
3104 named parties.
3105 \par
3106 These external ACL representations differ from the internal format generated by
3107 the Cache Manager after a parsing pass. The external format may be easily
3108 generated from the internal format as follows. The header format is expressed
3109 with the following printf() statement:
3110 \code
3111 printf("%d\n%d\n", NumPositiveEntries, NumNegativeEntries);
3112 \endcode
3113 \par
3114 The header first specifies the number of entries on the positive rights list,
3115 which appear first in the ACL body. The number of entries on the negative list
3116 is the second item in the header. The negative entries appear after the last
3117 positive entry.
3118 \par
3119 Each entry in the ACL proper obeys the format imposed by the following printf()
3120 statement:
3121 \code
3122 printf("%s\t%d\n", UserOrGroupName, RightsMask);
3123 \endcode
3124 \par
3125 Note that the string name for the user or group is stored in an externalized
3126 ACL entry. The Protection Server stores the mappings between the numerical
3127 identifiers for AFS principals and their character string representations.
3128 There are cases where there is no mapping from the numerical identifier to a
3129 string name. For example, a user or group may have been deleted sometime after
3130 they were added to the ACL and before the Cache Manager externalized the ACL
3131 for storage. In this case, the Cache Manager sets UserOrGroupName to the string
3132 version of the principal's integer identifier. Should the erz principal be
3133 deleted from the Protection Server's database in the above scenario, then the
3134 string '1019' will be stored, since it corresponded to erz's former numerical
3135 identifier.
3136 \par
3137 The RightsMask parameter to the above call represents the set of rights the
3138 named principal may exercise on the objects covered by the ACL. The following
3139 flags may be OR'ed together to construct the desired access rights placed in
3140 RightsMask:
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
3152 directory
3153 
3154 \par
3155 [Opcode 1] Set the contents of the ACL associated with the file system object
3156 named by a pathP. Should this pathname indicate a file and not a directory, the
3157 Cache Manager will apply this operation to the file's parent directory. The new
3158 ACL contents, expressed in their externalized form, are made available in in,
3159 with in size set to its length in characters, including the trailing null.
3160 There is no output from this call, so out size should be set to zero.
3161 Internally, the Cache Manager will call the RXAFS StoreACL() RPC (see Section
3162 5.1.3.3 to store the new ACL on the proper File Server.
3163 \par
3164 Possible error codes include EINVAL, indicating that one of three things may be
3165 true: the named path is not in AFS, there are too many entries in the specified
3166 ACL, 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
3169 directory
3170 
3171 \par
3172 [Opcode 2] Get the contents of the ACL associated with the file system object
3173 named by a pathP. Should this pathname indicate a file and not a directory, the
3174 Cache Manager will apply this operation to the file's parent directory. The ACL
3175 contents, expressed in their externalized form, are delivered into the out
3176 buffer if out size has been set to a value which indicates that there is enough
3177 room for the specified ACL. This ACL string will be null-terminated. There is
3178 no input to this call, so in size should be set to zero. Internally, the Cache
3179 Manager will call the RXAFS FetchACL() RPC (see Section 5.1.3.1) to fetch the
3180 ACL from the proper File Server.
3181 \par
3182 Possible error codes include EINVAL, indicating that the named path is not in
3183 AFS.
3184 
3185  \subsection sec6-4-8 Section 6.4.8: Cache Operations
3186 
3187 \par
3188 It is possible to inquire about and affect various aspects of the cache
3189 maintained locally by the Cache Manager through the group of pioctl()s
3190 described below. Specifically, one may force certain file system objects to be
3191 removed from the cache (VIOCFLUSH), set the maximum number of blocks usable by
3192 the cache (VIOCSETCACHESIZE), and ask for information about the cache's current
3193 state (VIOCGETCACHEPARAMS).
3194 
3195  \subsubsection sec6-4-8-1 Section 6.4.8.1: VIOCFLUSH: Flush an object
3196 from the cache
3197 
3198 \par
3199 [Opcode 6] Flush the file system object specified by a pathP out of the local
3200 cache. The other parameters are not referenced, so they should be set to the
3201 proper combination of null pointers and zeroes.
3202 \par
3203 Among the possible error returns is EINVAL, indicating that the value supplied
3204 in the a pathP parameter is not acceptable.
3205 
3206  \subsubsection sec6-4-8-2 Section 6.4.8.2: VIOCSETCACHESIZE: Set
3207 maximum cache size in blocks
3208 
3209 \par
3210 [Opcode 24] Instructs the Cache Manager to set a new maximum size (in 1 Kbyte
3211 blocks) for its local cache. The input buffer located at in contains the new
3212 maximum block count. If zero is supplied for this value, the Cache Manager will
3213 revert its cache limit to its value at startup time. Neither the a pathP nor
3214 output buffer parameters is referenced by this operation. The Cache Manager
3215 recomputes its other cache parameters based on this new value, including the
3216 number of cache files allowed to be dirty at once and the total amount of space
3217 filled with dirty chunks. Should the new setting be smaller than the number of
3218 blocks currently being used, the Cache Manager will throw things out of the
3219 cache until it obeys the new limit.
3220 \par
3221 The caller is required to be effectively running as root, or this call will
3222 fail, returning EACCES. If the Cache Manager is configured to run with a memory
3223 cache 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
3226 current cache parameter values
3227 
3228 \par
3229 [Opcode 40] Fetch the current values being used for the cache parameters. The
3230 output buffer is filled with MAXGCSTATS (16) longwords, describing these
3231 parameters. Only the first two longwords in this array are currently set. The
3232 first contains the value of afs cacheBlocks, or the maximum number of 1 Kbyte
3233 blocks which may be used in the cache (see Section 6.4.8.2 for how this value
3234 may be set). The second longword contains the value of the Cache Manager's
3235 internal afs blocksUsed variable, or the number of these cache blocks currently
3236 in use. All other longwords in the array are set to zero. Neither the a pathP
3237 nor input buffer arguments are referenced by this call.
3238 \par
3239 This routine always returns successfully.
3240 
3241  \subsection sec6-4-9 Section 6.4.9: Miscellaneous Operations
3242 
3243 \par
3244 There are several other AFS-specific operations accessible via the pioctl()
3245 interface that don't fit cleanly into the above categories. They are described
3246 in this section, and include manipulation of the socket-based Mariner file
3247 trace interface (VIOC AFS MARINER HOST), enabling and disabling of the
3248 file-based AFSLog output interface for debugging (VIOC VENUSLOG), getting and
3249 setting the value of the special @sys pathname component mapping (VIOC AFS
3250 SYSNAME), and turning the NFS-AFS translator service on and off (VIOC
3251 EXPORTAFS).
3252 
3253  \subsubsection sec6-4-9-1 Section 6.4.9.1: VIOC AFS MARINER HOST:
3254 Get/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
3258 destined to receive Mariner output. A detailed description of the Cache Manager
3259 Mariner interface may be found in Section 6.7.
3260 \par
3261 The input buffer located at in is used to pass a single longword containing the
3262 IP address of the machine to receive output regarding file transfers between
3263 the Cache Manager and any File Server. If the chosen host IP address is
3264 0xffffffff, the Cache Manager is prompted to turn off generation of Mariner
3265 output entirely. If the chosen host IP address is zero, then the Cache Manager
3266 will not set the Mariner host, but rather return the current Mariner host as a
3267 single longword written to the out output buffer. Any other value chosen for
3268 the host IP address enables Mariner output (if it was not already enabled) and
3269 causes all further traffic to be directed to the given machine.
3270 \par
3271 This function always returns successfully.
3272 
3273  \subsubsection sec6-4-9-2 Section 6.4.9.2: VIOC VENUSLOG:
3274 Enable/disable Cache Manager logging
3275 
3276 \par
3277 [Opcode 34] Tell the Cache Manager whether to generate debugging information,
3278 and what kind of debugging output to enable. The input buffer located at in is
3279 used to transmit a single longword to the Cache Manager, expressing the
3280 caller's wishes. Of the four bytes making up the longword, the highest byte
3281 indicates the desired value for the internal afsDebug variable, enabling or
3282 disabling general trace output. The next highest byte indicates the desired
3283 value for the internal netDebug variable, enabling or disabling network-level
3284 debugging traces. The third byte is unused, and the low-order byte represents
3285 an overall on/off value for the functionality. There is a special value for the
3286 low-order byte, 99, which instructs the Cache Manager to return the current
3287 debugging setting as a single longword placed into the output buffer pointed to
3288 by out. The a pathP parameter is not referenced by this routine.
3289 \par
3290 Trace 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
3292 existing AFSLog file is truncated, and its file descriptor is stored for future
3293 use. When this debugging is disabled, a close() is done on the file, forcing
3294 all its data to disk. For additional information on the AFSLog file for
3295 collecting Cache Manager traces, please see the description in Section 6.6.2.1.
3296 \par
3297 This call will only succeed if the caller is effectively running as root. If
3298 this 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
3301 the @sys mapping
3302 
3303 \par
3304 [Opcode 38] Get or set the value of the special @sys pathname component
3305 understood by the Cache Manager. The input buffer pointed to by in is used to
3306 house a longword whose value determines whether the @sys value is being set (1)
3307 or whether the current value is being fetched (0). If it is being set, then a
3308 null-terminated string is expected to follow in the input buffer, specifying
3309 the new value of @sys. Otherwise, if we are asking the Cache Manager for the
3310 current @sys setting, a null-terminated string bearing that value will be
3311 placed in the out output buffer. The a pathP parameter is not used by this
3312 call, and thus should be set to a null pointer.
3313 \par
3314 There are no special privileges required of the caller to fetch the value of
3315 the current @sys mapping. However, a native caller must be running effectively
3316 as root in order to successfully alter the mapping. An unauthorized attempt to
3317 change the @sys setting will be ignored, and cause this routine to return
3318 EACCES. This requirement is relaxed for VIOC AFS SYSNAME pioctl() calls
3319 emanating from foreign file systems such as NFS and accessing AFS files through
3320 the NFS-AFS translator. Each such remote caller may set its own notion of what
3321 the @sys mapping is without affecting native AFS clients. Since the uid values
3322 received in calls from NFS machines are inherently insecure, it is impossible
3323 to enforce the fact that the caller is truly root on the NFS machine. This,
3324 while any principal running on an NFS machine may change that foreign machine's
3325 perception 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:
3328 Enable/disable NFS/AFS translation
3329 
3330 \par
3331 [Opcode 39] Enable or disable the ability of an AFS-capable machine to export
3332 AFS access to NFS clients. Actually, this is a general facility allowing
3333 exportation of AFS service to any number of other file systems, but the only
3334 support currently in place is for NFS client machines. A single longword is
3335 expected in the input buffer in. This input longword is partitioned into
3336 individual bytes, organized as follows. The high-order byte communicates the
3337 type of foreign client to receive AFS file services. There are currently two
3338 legal values for this field, namely 0 for the null foreign file system and 1
3339 for NFS. The next byte determines whether the Cache Manager is being asked to
3340 get or set this information. A non-zero value here is interpreted as a command
3341 to set the export information according to what's in the input longword, and a
3342 zero-valued byte in this position instructs the Cache Manager to place a
3343 longword in the output buffer out, which contains the current export settings
3344 for the foreign system type specified in the high-order byte. The third input
3345 byte is not used, and the lowest-order input buffer byte determines whether
3346 export services for the specified system are being enabled or disabled. A
3347 non-zero value will turn on the services, and a zero value will shut them down.
3348 The a pathP pathname parameter is not used by this call, and the routine
3349 generates output only if the export information is being requested instead of
3350 being set.
3351 \par
3352 The caller must be effectively running as root in order for this operation to
3353 succeed. The call returns EACCES if the caller is not so authorized. If the
3354 caller specifies an illegal foreign system type in the high-order byte of the
3355 input longword, then ENODEV is returned. Again, NFS is the only foreign file
3356 system currently supported.
3357 \par
3358 Practically speaking, the machine providing NFS-AFS translation services must
3359 enable this service with this pioctl() before any NFS client machines may begin
3360 accessing AFS files. Conversely, if an administrator turns off this export
3361 facility, the export code on the translator machine will immediately stop
3362 responding 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
3369 This section covers the structure and workings of the Cache Manager's RPC
3370 interface. Typically, these calls are made by File Server processes. However,
3371 some of the calls are designed specifically for debugging programs (e.g., the
3372 cmdebug facility) and for collection of statistical and performance information
3373 from the Cache Manager. Any client application that makes direct calls on the
3374 File Server RPC interface must be prepared to export a subset of the Cache
3375 Manager RPC interface, as discussed in Section 5.1.6.
3376 \par
3377 This section will first examine the Cache Manager's use of locks, whose
3378 settings may be observed via one of the RPC interface calls. Next, it will
3379 present some definitions and data structures used in the RPC interface, and
3380 finally document the individual calls available through this interface.
3381 
3382  \subsection sec6-5-2 Section 6.5.2: Locks
3383 
3384 \par
3385 The Cache Manager makes use of locking to insure its internal integrity in the
3386 face of its multi-threaded design. A total of 11 locks are maintained for this
3387 purpose, one of which is now obsolete and no longer used (see below). These
3388 locks are strictly internal, and the Cache Manager itself is the only one able
3389 to manipulate them. The current settings for these system locks are externally
3390 accessible for debugging purposes via the AFSRXCB GetLock() RPC interface call,
3391 as described in Section 6.5.5.4. For each lock, its index in the locking table
3392 is given in the following text.
3393 \li afs xvcache [Index 0]: This lock controls access to the status cache
3394 entries maintained by the Cache Manager. This stat cache keeps stat()-related
3395 information for AFS files it has dealt with. The stat information is kept
3396 separate from actual data contents of the related file, since this information
3397 may 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
3399 data cache, namely the contents of the file system objects it has cached
3400 locally. As stated above, this data cache is separate from the associated
3401 stat() information.
3402 \li afs xserver [Index 2]: This lock controls access to the File Server machine
3403 description table, which keeps tabs on all File Servers contacted in recent
3404 history. This lock thus indirectly controls access to the set of per-server RPC
3405 connection descriptors the File Server table makes visible.
3406 \li afs xvcb [Index 3]: This lock supervises access to the volume callback
3407 information kept by the Cache Manager. This table is referenced, for example,
3408 when a client decides to remove one or more callbacks on files from a given
3409 volume (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
3411 background daemons, which perform prefetching and background file storage
3412 duties.
3413 \li afs xcell [Index 5]: This lock controls the addition, deletion, and update
3414 of items on the linked list housing information on cells known to the Cache
3415 Manager.
3416 \li afs xconn [Index 6]: This lock supervises operations concerning the set of
3417 RPC connection structures kept by the system. This lock is used in combination
3418 with the
3419 \li afs xserver lock described above. In some internal Cache Manager code
3420 paths, the File Server description records are first locked, and then the afs
3421 xconn 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
3423 the Cache Manager.
3424 \li afs xvolume [Index 8]: This lock is used to control access to the Cache
3425 Manager's volume information cache, namely the set of entries currently in
3426 memory, a subset of those stably housed in the VolumeItems disk file (see
3427 Section 6.6.2.3).
3428 \li afs puttofileLock [Index 9]: This lock is obsolete, and while still defined
3429 by the system is no longer used. It formerly serialized writes to a debugging
3430 output interface buffer, but the internal mechanism has since been updated and
3431 improved.
3432 \li afs ftf [Index 10]: This lock is used when flushing cache text pages from
3433 the machine's virtual memory tables. For each specific machine architecture on
3434 which the Cache Manager runs, there is a set of virtual memory operations which
3435 must be invoked to perform this operation. The result of such activities is to
3436 make sure that the latest contents of new incarnations of binaries are used,
3437 instead of outdated copies of previous versions still resident in the virtual
3438 memory system.
3439 
3440  \subsection sec6-5-3 Section 6.5.3: Definitions and Typedefs
3441 
3442 \par
3443 This section documents some macro definitions and typedefs referenced by the
3444 Cache Manager's RPC interface. Specifically, these definitions and typedefs are
3445 used in the RXAFSCB GetXStats() and RXAFSCB XStatsVersion calls as described in
3446 Sections 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 */
3453 const 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 */
3459 const AFSCB_MAX_XSTAT_LONGS = 2048;
3460 typedef long AFSCB_CollData<AFSCB_MAX_XSTAT_LONGS>;
3461 
3462 /*
3463 * Define the identifiers for the accessible extended stats data
3464 * collections.
3465 */
3466 const AFSCB_XSTATSCOLL_CALL_INFO = 0; /*CM call counting & info*/
3467 const AFSCB_XSTATSCOLL_PERF_INFO = 1; /*CM performance info*/
3468 \endcode
3469 
3470  \subsection sec6-5-4 Section 6.5.4: Structures
3471 
3472 \par
3473 This section documents some structures used in the Cache Manager RPC interface.
3474 As with the constants and typedefs in the previous section, these items are
3475 used in the RXAFSCB GetXStats() and RXAFSCB XStatsVersion calls as described in
3476 Sections 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
3481 This structure may be used to collect a running average figure. It is included
3482 in 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
3490 This structure maintains profiling information, communicating the number of
3491 times internal Cache Manager functions are invoked. Each field name has a "C "
3492 prefix, followed by the name of the function being watched. As this structure
3493 has entries for over 500 functions, it will not be described further here.
3494 Those readers who wish to see the full layout of this structure are referred to
3495 Appendix A.
3496 \par
3497 The AFSCB XSTATSCOLL CALL INFO data collection includes the information in this
3498 structure.
3499 
3500  \subsubsection sec6-5-4-3 Section 6.5.4.3: struct afs CMMeanStats
3501 
3502 \par
3503 This is the other part of the information (along with the struct afs
3504 CMCallStats construct described above) returned by the AFSCB XSTATSCOLL CALL
3505 INFO data collection defined by the Cache Manager (see Section 6.5.3). It is
3506 accessible via the RXAFSCB GetXStats() interface routine, as defined in Section
3507 6.5.5.7.
3508 \par
3509 This structure represents the beginning of work to compute average values for
3510 some 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
3513 the 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
3518 This structure defines the information returned by the AFSCB XSTATSCOLL CALL
3519 INFO data collection defined by the Cache Manager (see Section 6.5.3). It is
3520 accessible via the RXAFSCB GetXStats() interface routine, as defined in Section
3521 6.5.5.7.
3522 \n \b Fields
3523 \li struct afs CallStats callInfo - Contains the counts on the number of times
3524 each internal Cache Manager function has been called.
3525 \li struct afs MeanStats something - Intended to collect averages for some of
3526 the 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
3531 This is the information returned by the AFSCB XSTATSCOLL PERF INFO data
3532 collection defined by the Cache Manager (see Section 6.5.3). It is accessible
3533 via 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
3539 cell.
3540 \li long vlocalAccesses - Number of stat accesses to files within the local
3541 cell.
3542 \li long dremoteAccesses - Number of data accesses to files outside of the
3543 local cell.
3544 \li long vremoteAccesses - Number of stat accesses to files outside of the
3545 local 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
3553 cache.
3554 \li long vcacheHits - Number of stat entry requests satisfied by the local
3555 cache.
3556 \li long dcacheMisses - Number of data file requests not satisfied by the local
3557 cache.
3558 \li long vcacheMisses - Number of stat entry requests not satisfied by the
3559 local 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
3563 concerning File Servers.
3564 \li long ProtServerAddr - IP addres of the Protection Server used (not
3565 implemented).
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
3571 This section discusses the Cache Manager interface calls. No special
3572 permissions are required of the caller for any of these operations. A summary
3573 of 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
3583 that the underlying callback service is still operational
3584 
3585 \code
3586 int 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
3590 determine if the given Cache Manager is still running. Any File Server will
3591 probe each of the Cache Managers with which it has interacted on a regular
3592 basis, keeping track of their health. This information serves an important
3593 purpose for a File Server. In particular, it is used to trigger purging of
3594 deceased Cache Managers from the File Server's callback records, and also to
3595 instruct a new or "resurrected" Cache Manager to purge its own callback state
3596 for the invoking File Server.
3597 \par
3598 Rx 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
3603 callbacks dropped by a File Server
3604 
3605 \code
3606 int 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
3612 the calling File Server. The number of fids involved appears in a
3613 fidArrayP->AFSCBFids len, with the fids themselves located at a
3614 fidArrayP->AFSCBFids val. Similarly, the number of associated callbacks is
3615 placed in a callBackArrayP->AFSCBs len, with the callbacks themselves located
3616 at a callBackArrayP->AFSCBs val.
3617 \par
3618 Rx 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 -
3623 Purge callback state from a File Server
3624 
3625 \code
3626 int 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
3630 state for all files and directories that live on the calling host. This
3631 function is typically called by a File Server when it gets a request from a
3632 Cache Manager that does not appear in its internal records. This handles
3633 situations where Cache Managers survive a File Server, or get separated from it
3634 via a temporary network partition. This also happens upon bootup, or whenever
3635 the File Server must throw away its record of a Cache Manager because its
3636 tables have been filled.
3637 \par
3638 Rx 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
3643 contents of Cache Manager lock table
3644 
3645 \code
3646 int 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
3652 table. There are 11 locks in the table, as described in Section 6.5.2. The
3653 contents of the desired lock, including a string name representing the lock,
3654 are returned in a lockP.
3655 \par
3656 This call is not used by File Servers, but rather by debugging tools such as
3657 cmdebug.
3658 \par
3659 Rx call information for the related Cache Manager is contained in a rxCallP.
3660 \par Error Codes
3661 The index value supplied in a index is out of range; it must be between 0 and
3662 10.
3663 
3664  \subsubsection sec6-5-5-5 Section 6.5.5.5: RXAFSCB GetCE - Get cache
3665 file description
3666 
3667 \code
3668 int 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
3674 cache, storing it into the buffer to which a ceP points. The structure returned
3675 into this pointer variable is described in Section 4.3.2.
3676 \par
3677 This call is not used by File Servers, but rather by debugging tools such as
3678 cmdebug.
3679 \par
3680 Rx call information for the related Cache Manager is contained in a rxCallP.
3681 \par Error Codes
3682 The 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
3685 version of extended statistics package
3686 
3687 \code
3688 int 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
3693 the extended statistics structures it exports (see RXAFSCB GetXStats(), Section
3694 6.5.5.7). The version number is placed in a versionNumberP.
3695 \par
3696 Rx 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
3701 contents of extended statistics data collection
3702 
3703 \code
3704 int 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
3713 extended statistics structure. The caller provides the version number of the
3714 data it expects to receive in a clientVersionNumber. Also provided in a
3715 collectionNumber is the numerical identifier for the desired data collection.
3716 There are currently two of these data collections defined: AFSCB XSTATSCOLL
3717 CALL INFO, which is the list of tallies of the number of invocations of
3718 internal Cache Manager procedure calls, and AFSCB XSTATSCOLL PERF INFO, which
3719 is a list of performance-related numbers. The precise contents of these
3720 collections are described in Section 6.5.4. The current version number of the
3721 Cache Manager collections is returned in a srvVersionNumberP, and is always set
3722 upon return, even if the caller has asked for a different version. If the
3723 correct version number has been specified, and a supported collection number
3724 given, then the collection data is returned in a dataP. The time of collection
3725 is also returned, being placed in a timeP.
3726 \par
3727 Rx call information for the related Cache Manager is contained in a rxCallP.
3728 \par Error Codes
3729 The collection number supplied in a collectionNumber is out of range.
3730 
3731  \section sec6-6 Section 6.6: Files
3732 
3733 \par
3734 The Cache Manager gets some of its start-up configuration information from
3735 files located on the client machine's hard disk. Each client is required to
3736 supply a /usr/vice/etc directory in which this configuration data is kept.
3737 Section 6.6.1 describes the format and purpose of the three files contributing
3738 this 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
3745 The Cache Manager, along with various applications, needs to be able to
3746 determine the cell to which its client machine belongs. This information is
3747 provided by the ThisCell file. It contains a single line stating the machine's
3748 fully-qualified cell name.
3749 \par
3750 As with the CellServDB configuration file, the Cache Manager reads the contents
3751 of ThisCell exactly once, at start-up time. Thus, an incarnation of the Cache
3752 Manager will maintain precisely one notion of its home cell for its entire
3753 lifetime. Thus, changes to the text of the ThisCell file will be invisible to
3754 the running Cache Manager. However, these changes will affect such application
3755 programs as klog, which allows a user to generate new authentication tickets.
3756 In this example, klog reads ThisCell every time it is invoked, and then
3757 interacts with the set of Authentication Servers running in the given home
3758 cell, unless the caller specifies the desired cell on the command line.
3759 \par
3760 The ThisCell file is not expected to be changed on a regular basis. Client
3761 machines are not imagined to be frequently traded between different
3762 administrative organizations. The Unix mode bits are set to specify that while
3763 everyone 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
3768 To conduct business with a given AFS cell, a Cache Manager must be informed of
3769 the cell's name and the set of machines running AFS database servers within
3770 that cell. Such servers include the Volume Location Server, Authentication
3771 Server, and Protection Server. This particular cell information is obtained
3772 upon startup by reading the CellServDB file. Thus, when the Cache Manager
3773 initialization is complete, it will be able to communicate with the cells
3774 covered by CellServDB.
3775 \par
3776 The following is an excerpt from a valid CellServDB file, demonstrating the
3777 format used.
3778 
3779 \code
3780 ...
3781 >transarc.com #Transarc Corporation
3782 192.55.207.7 #henson.transarc.com
3783 192.55.207.13 #bigbird.transarc.com
3784 192.55.207.22 #ernie.transarc.com
3785 >andrew.cmu.edu #Carnegie Mellon University
3786 128.2.10.2 #vice2.fs.andrew.cmu.edu
3787 128.2.10.7 #vice7.fs.andrew.cmu.edu
3788 128.2.10.10 #vice10.fs.andrew.cmu.edu
3789 ...
3790 \endcode
3791 \par
3792 There 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
3794 may be convenient, however, to have the workstation's local cell be the first
3795 to appear.
3796 \li 2. No blank lines should appear in the file, even at the end of the last
3797 entry.
3798 \li 3. The first line of each cell's entry begins with the '>' character, and
3799 specifies the cell's human-readable, Internet Domain-style name. Optionally,
3800 some white space and a comment (preceded by a '#') may follow, briefly
3801 describing the specified cell.
3802 \li 4. Each subsequent line in a cell's entry names one of the cell's database
3803 server 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
3805 notation.
3806 \li Some amount of whitespace.
3807 \li A '#', followed by the machine's complete Internet host name. In this
3808 instance, the '#' sign and the text beyond it specifying the machine name are
3809 NOT treated as a comment. This is required information.
3810 \par
3811 The Cache Manager will use the given host name to determine its current address
3812 via an Internet Domain lookup. If and only if this lookup fails does the Cache
3813 Manager fall back to using the dotted Internet address on the first part of the
3814 line. This dotted address thus appears simply as a hint in case of Domain
3815 database downtime.
3816 \par
3817 The CellServDB file is only parsed once, when the Cache Manager first starts.
3818 It is possible, however, to amend existing cell information records or add
3819 completely new ones at any time after Cache Manager initialization completes.
3820 This 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
3825 This one-line file contains three fields separated by colons:
3826 \li AFS Root Directory: This is the directory where the Cache Manager mounts
3827 the AFS root volume. Typically, this is specified to be /afs.
3828 \li Cache Directory: This field names the directory where the Cache Manager is
3829 to 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
3831 1,024-byte blocks that the Cache Manager is allowed to use in the partition
3832 hosting the named cache directory.
3833 \par
3834 Thus, the following cacheinfo file would instruct the Cache Manager to mount
3835 the AFS filespace at /afs, and inform it that it may expect to be able to use
3836 up 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
3846 This is the AFS log file used to hold Cache Manager debugging output. The file
3847 is set up when the Cache Manager first starts. If it already exists, it is
3848 truncated. If it doesn't, it is created. Output to this file is enabled and
3849 disabled via the the VIOC VENUSLOG pioctl() (see Section 6.4.9.2). Normal text
3850 messages are written to this file by the Cache Manager when output is enabled.
3851 Each time logging to this file is enabled, the AFSLog file is truncated. Only
3852 root can read and write this file.
3853 
3854  \subsubsection sec6-6-2-2 Section 6.6.2.2: CacheItems
3855 
3856 \par
3857 The Cache Manager only keeps a subset of its data cache entry descriptors in
3858 memory at once. The number of these in-memory descriptors is determined by
3859 afsd. All of the data cache entry descriptors are kept on disk, in the
3860 CacheItems file. The file begins with a header region, taking up four
3861 longwords:
3862 \code
3863 struct fheader { long magic AFS_FHMAGIC 0x7635fab8 long firstCSize: First chunk
3864 size long otherCSize: Next chunk sizes long spare }
3865 \endcode
3866 \par
3867 The header is followed by one entry for each cache file. Each is:
3868 \code
3869 struct 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
3886 The Cache Manager only keeps at most MAXVOLS (50) in-memory volume
3887 descriptions. However, it records all volume information it has obtained in the
3888 VolumeItems file in the chosen AFS cache directory. This file is truncated when
3889 the Cache Manager starts. Each volume record placed into this file has the
3890 following struct fvolume layout:
3891 \code
3892 struct 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
3904 The Cache Manager Mariner interface allows interested parties to be advised in
3905 real time as to which files and/or directories are being actively transferred
3906 between the client machine and one or more File Servers. If enabled, this
3907 service delivers messages of two different types, as exemplified below:
3908 \code
3909 Fetching myDataDirectory
3910 Fetching myDataFile.c
3911 Storing myDataObj.o
3912 \endcode
3913 \par
3914 In the first message, the myDataDirectory directory is shown to have just been
3915 fetched from a File Server. Similarly, the second message indicates that the C
3916 program myDataFile.c had just been fetched from its File Server of residence.
3917 Finally, the third message reveals that the myDataObj.o object file has just
3918 been written out over the network to its respective server.
3919 \par
3920 In actuality, the text of the messages carries a string prefix to indicate
3921 whether a Fetch or Store operation had been performed. So, the full contents of
3922 the above messages are as follows:
3923 \code
3924 fetch$Fetching myDataDirectory
3925 fetch$Fetching myDataFile.c
3926 store$Storing myDataObj.o
3927 \endcode
3928 The Mariner service may be enabled or disabled for a particular machine by
3929 using the VIOC AFS MARINER HOST pioctl() (see Section 6.4.9.1). This operation
3930 allows any host to be specified as the recipient of these messages. A potential
3931 recipient must have its host be declared the target of such messages, then
3932 listen to a socket on port 2106.
3933 \par
3934 Internally, the Cache Manager maintains a cache of NMAR (10) vnode structure
3935 pointers and the string name (up to 19 characters) of the associated file or
3936 directory. This cache is implemented as an array serving as a circular buffer.
3937 Each time a file is involved in a create or lookup operation on a File Server,
3938 the current slot in this circular buffer is filled with the relevant vnode and
3939 string name information, and the current position is advanced. If Mariner
3940 output is enabled, then an actual network fetch or store operation will trigger
3941 messages of the kind shown above. Since a fetch or store operation normally
3942 occurs shortly after the create or lookup, the mapping of vnode to name is
3943 likely to still be in the Mariner cache when it comes time to generate the
3944 appropriate message. However, since an unbounded number of other lookups or
3945 creates could have been performed in the interim, there is no guarantee that
3946 the mapping entry will not have been overrun. In these instances, the Mariner
3947 message will be a bit vaguer. Going back to our original example,
3948 \code
3949 Fetching myDataDirectory
3950 Fetching a file
3951 Storing myDataObj.o
3952 \endcode
3953 In this case, the cached association between the vnode containing myDataFile.c
3954 and its string name was thrown out of the Mariner cache before the network
3955 fetch operation could be performed. Unable to find the mapping, the generic
3956 phrase "a file" was used to identify the object involved.
3957 \par
3958 Mariner messages only get generated when RPC traffic for fetching or storing a
3959 file system object occurs between the Cache Manager and a File Server. Thus,
3960 file accesses that are handled by the Cache Manager's on-board data cache do
3961 not trigger such announcements.
3962 
3963  \page biblio Bibliography
3964 
3965 \li [1] Transarc Corporation. AFS 3.0 System Administrator's Guide,
3966 F-30-0-D102, Pittsburgh, PA, April 1990.
3967 \li [2] Transarc Corporation. AFS 3.0 Command Reference Manual, F-30-0-D103,
3968 Pittsburgh, PA, April 1990.
3969 \li [3] CMU Information Technology Center. Synchronization and Caching Issues
3970 in the Andrew File System, USENIX Proceedings, Dallas, TX, Winter 1988.
3971 \li [4] Sun Microsystems, Inc. NFS: Network File System Protocol Specification,
3972 RFC 1094, March 1989.
3973 \li [5] Sun Microsystems, Inc. Design and Implementation of the Sun Network
3974 File System, USENIX Summer Conference Proceedings, June 1985.
3975 \li [6] S.P. Miller, B.C. Neuman, J.I. Schiller, J.H. Saltzer. Kerberos
3976 Authentication and Authorization System, Project Athena Technical Plan, Section
3977 E.2.1, M.I.T., December 1987.
3978 \li [7] Bill Bryant. Designing an Authentication System: a Dialogue in Four
3979 Scenes, Project Athena internal document, M.I.T, draft of 8 February 1988.
3980 
3981 */