return AFS_BUFFER_PAGESIZE * bp->page + (int)(((char *)ap) - bp->data);
}
-/* 1/1/91 - I've modified the hash function to take the page as well
+/*!
+ * Zap one dcache entry: destroy one FID's buffers.
+ *
+ * 1/1/91 - I've modified the hash function to take the page as well
* as the *fid, so that lookup will be a bit faster. That presents some
* difficulties for Zap, which now has to have some knowledge of the nature
* of the hash function. Oh well. This should use the list traversal
* method of DRead...
+ *
+ * \param adc The dcache entry to be zapped.
*/
void
DZap(struct dcache *adc)
char *cellname;
} afsdb_req;
+/*!
+ * Terminate the AFSDB handler, used on shutdown.
+ */
void
afs_StopAFSDB()
{
}
}
+/*!
+ * \brief Entry point for user-space AFSDB request handler.
+ * Reads cell data from kerlenMsg and add new cell, or alias.
+ * \param acellName Cell name. If a cell is found, it's name will be filled in here.
+ * \param acellNameLen Cell name length.
+ * \param kernelMsg Buffer containing data about host count, time out, and cell hosts ids.
+ * \return 0 for success, < 0 for error.
+ */
int
afs_AFSDBHandler(char *acellName, int acellNameLen, afs_int32 * kernelMsg)
{
return 0;
}
+/*!
+ * \brief Query the AFSDB handler and wait for response.
+ * \param acellName
+ * \return 0 for success. < 0 is error.
+ */
static int
afs_GetCellHostsAFSDB(char *acellName)
{
}
#endif
+
+/*!
+ * Look up AFSDB for given cell name and create locally.
+ * \param acellName Cell name.
+ */
void
afs_LookupAFSDB(char *acellName)
{
static int afs_cellname_dirty;
static afs_int32 afs_cellnum_next;
+/*!
+ * Create a new cell name, optional cell number.
+ * \param name Name of cell.
+ * \param cellnum Cellname number.
+ * \return Initialized structure.
+ */
static struct cell_name *
afs_cellname_new(char *name, afs_int32 cellnum)
{
return cn;
}
+/*!
+ * Look up a cell name by id.
+ * \param cellnum
+ * \return
+ */
static struct cell_name *
afs_cellname_lookup_id(afs_int32 cellnum)
{
return NULL;
}
+/*!
+ * Look up a cell name.
+ * \param name Cell name.
+ * \return
+ */
static struct cell_name *
afs_cellname_lookup_name(char *name)
{
return NULL;
}
+/*!
+ * Note that this cell name was referenced somewhere.
+ * \param cn
+ */
static void
afs_cellname_ref(struct cell_name *cn)
{
}
}
+/*!
+ * \brief Load the list of cells from given inode.
+ * \param inode Source inode.
+ * \param lookupcode
+ * \return 0 for success. < 0 for error.
+ */
int
afs_cellname_init(ino_t inode, int lookupcode)
{
return 0;
}
+/*!
+ * Write in-kernel list of cells to disk.
+ */
int
afs_cellname_write(void)
{
static afs_int32 afs_cellalias_index;
static int afs_CellOrAliasExists_nl(char *aname); /* Forward declaration */
+/*!
+ * Look up cell alias by alias name.
+ * \param alias
+ * \return Found struct or NULL.
+ */
static struct cell_alias *
afs_FindCellAlias(char *alias)
{
return tc;
}
+/*!
+ * Get cell alias by index (starting at 0).
+ * \param index Cell index.
+ * \return Found struct or null.
+ */
struct cell_alias *
afs_GetCellAlias(int index)
{
return tc;
}
+
+ /*!
+ * Put back a cell alias returned by Find or Get.
+ * \param a Alias.
+ * \return
+ */
void
afs_PutCellAlias(struct cell_alias *a)
{
return;
}
+/*!
+ * Create new cell alias entry and update dynroot vnode.
+ * \param alias
+ * \param cell
+ * \return
+ */
afs_int32
afs_NewCellAlias(char *alias, char *cell)
{
static char *afs_thiscell;
afs_int32 afs_cellindex; /* Export for kdump */
+/*!
+ * Bump given cell up to the front of the LRU queue.
+ * \param c Cell to set.
+ */
static void
afs_UpdateCellLRU(struct cell *c)
{
ReleaseWriteLock(&afs_xcell);
}
+/*!
+ * Look up cell information in AFSDB if timeout expired
+ * \param ac Cell to be refreshed.
+ * \return
+ */
static void
afs_RefreshCell(struct cell *ac)
{
afs_LookupAFSDB(ac->cellName);
}
+/*!
+ * Execute a callback for each existing cell, without a lock on afs_xcell.
+ * Iterate on CellLRU, and execute a callback for each cell until given arguments are met.
+ * \see afs_TraverseCells
+ * \param cb Traversal callback for each cell.
+ * \param arg Callback arguments.
+ * \return Found data or NULL.
+ */
static void *
afs_TraverseCells_nl(void *(*cb) (struct cell *, void *), void *arg)
{
return ret;
}
+/*!
+ * Execute a callback for each existing cell, with a lock on afs_xcell.
+ * \see afs_TraverseCells_nl
+ * \param cb Traversal callback for each cell.
+ * \param arg
+ * \return Found data or NULL.
+ */
void *
afs_TraverseCells(void *(*cb) (struct cell *, void *), void *arg)
{
return ret;
}
+/*!
+ * Useful traversal callback: Match by name.
+ * \param cell
+ * \param arg Cell name (compared with cell->cellName).
+ * \return Returns found cell or NULL.
+ */
static void *
afs_choose_cell_by_name(struct cell *cell, void *arg)
{
}
}
+/*!
+ * Useful traversal callback: Match by handle.
+ * \param cell
+ * \param arg Cell handle (compared with cell->cellHandle).
+ * \return Returns found cell or NULL.
+ */
static void *
afs_choose_cell_by_handle(struct cell *cell, void *arg)
{
}
}
+/*!
+ * Useful traversal callback: Match by cell number.
+ * \param cell
+ * \param arg Cell number (compared with cell->cellNum).
+ * \return Returns found cell or NULL.
+ */
static void *
afs_choose_cell_by_num(struct cell *cell, void *arg)
{
return (cell->cellNum == *((afs_int32 *) arg)) ? cell : NULL;
}
+/*!
+ * Useful traversal callback: Match by index.
+ * \param cell
+ * \param arg Cell index (compared with cell->cellIndex).
+ * \return Returns found cell or NULL.
+ */
static void *
afs_choose_cell_by_index(struct cell *cell, void *arg)
{
return (cell->cellIndex == *((afs_int32 *) arg)) ? cell : NULL;
}
+/*!
+ * Return a cell with a given name, if it exists. No lock version.
+ * Does not check AFSDB.
+ * \param acellName Cell name.
+ * \param locktype Type of lock to be used (not used).
+ * \return
+ */
static struct cell *
afs_FindCellByName_nl(char *acellName, afs_int32 locktype)
{
return afs_TraverseCells_nl(&afs_choose_cell_by_name, acellName);
}
+/*!
+ * Return a cell with a given name, if it exists.It uses locks.
+ * Does not check AFSDB.
+ * \param acellName Cell name.
+ * \param locktype Type of lock to be used.
+ * \return
+ */
static struct cell *
afs_FindCellByName(char *acellName, afs_int32 locktype)
{
return afs_TraverseCells(&afs_choose_cell_by_name, acellName);
}
+/*!
+ * Same as FindCellByName but tries AFSDB if not found.
+ * \param acellName Cell name.
+ * \param locktype Type of lock to be used.
+ * \return
+ */
struct cell *
afs_GetCellByName(char *acellName, afs_int32 locktype)
{
return tc;
}
+/*!
+ * Return a cell with a given cell number.
+ * \param cellnum Cell number.
+ * \param locktype Lock to be used.
+ * \return
+ */
struct cell *
afs_GetCell(afs_int32 cellnum, afs_int32 locktype)
{
return tc;
}
+/*!
+ * Same as GetCell, but does not try to refresh the data.
+ * \param cellnum Cell number.
+ * \param locktype What lock should be used.
+ * \return
+ */
struct cell *
afs_GetCellStale(afs_int32 cellnum, afs_int32 locktype)
{
return tc;
}
+/*!
+ * Return a cell with a given index number (starting at 0). Update CellLRU as well.
+ * \param index
+ * \param locktype Type of lock used.
+ * \return
+ */
struct cell *
afs_GetCellByIndex(afs_int32 index, afs_int32 locktype)
{
return tc;
}
+/*!
+ * Return a cell with a given handle..
+ * \param index
+ * \param locktype Type of lock used.
+ * \return
+ */
struct cell *
afs_GetCellByHandle(void *handle, afs_int32 locktype)
{
return tc;
}
+/*!
+ * Return primary cell, if any.
+ * \param locktype Type of lock used.
+ * \return
+ */
struct cell *
afs_GetPrimaryCell(afs_int32 locktype)
{
return afs_GetCellByName(afs_thiscell, locktype);
}
+/*!
+ * Returns true if the given cell is the primary cell.
+ * \param cell
+ * \return
+ */
int
afs_IsPrimaryCell(struct cell *cell)
{
}
}
+/*!
+ * Returns afs_IsPrimaryCell(afs_GetCell(cellnum)).
+ * \param cellnum
+ * \return
+ */
int
afs_IsPrimaryCellNum(afs_int32 cellnum)
{
return primary;
}
+/*!
+ * Set the primary cell name to the given cell name.
+ * \param acellName Cell name.
+ * \return 0 for success, < 0 for error.
+ */
afs_int32
afs_SetPrimaryCell(char *acellName)
{
return 0;
}
+/*!
+ * Create or update a cell entry.
+ * \param acellName Name of cell.
+ * \param acellHosts Array of hosts that this cell has.
+ * \param aflags Cell flags.
+ * \param linkedcname
+ * \param fsport File server port.
+ * \param vlport Volume server port.
+ * \param timeout Cell timeout value, 0 means static AFSDB entry.
+ * \return
+ */
afs_int32
afs_NewCell(char *acellName, afs_int32 * acellHosts, int aflags,
char *linkedcname, u_short fsport, u_short vlport, int timeout)
}
tc->states |= aflags;
tc->timeout = timeout;
-
+
memset((char *)tc->cellHosts, 0, sizeof(tc->cellHosts));
for (i = 0; i < MAXCELLHOSTS; i++) {
+ /* Get server for each host and link this cell in.*/
struct server *ts;
afs_uint32 temp = acellHosts[i];
if (!temp)
ts = afs_GetServer(&temp, 1, 0, tc->vlport, WRITE_LOCK, NULL, 0);
ts->cell = tc;
ts->flags &= ~SRVR_ISGONE;
+ /* Set the server as a host of the new cell. */
tc->cellHosts[i] = ts;
afs_PutServer(ts, WRITE_LOCK);
}
afs_SortServers(tc->cellHosts, MAXCELLHOSTS); /* randomize servers */
-
+
+ /* New cell: Build and add to LRU cell queue. */
if (newc) {
struct cell_name *cn;
* afs_CellNumValid: check if a cell number is valid (also set the used flag)
*/
+/*!
+ * Perform whatever initialization is necessary.
+ */
void
afs_CellInit()
{
afs_cellalias_index = 0;
}
+/*!
+ * Called on shutdown, should deallocate memory, etc.
+ */
void
shutdown_cell()
{
}
}
+/*!
+ * Remove a server from a cell's server list.
+ * \param srvp Server to be removed.
+ * \return
+ */
void
afs_RemoveCellEntry(struct server *srvp)
{
ReleaseWriteLock(&tc->lock);
}
+/*!
+ * Check if the given name exists as a cell or alias. Does not lock afs_xcell.
+ * \param aname
+ * \return
+ */
static int
afs_CellOrAliasExists_nl(char *aname)
{
return 0;
}
+/*!
+ * Check if the given name exists as a cell or alias. Locks afs_xcell.
+ * \param aname
+ * \return
+ */
int
afs_CellOrAliasExists(char *aname)
{
return ret;
}
+/*!
+ * Check if a cell number is valid (also set the used flag).
+ * \param cellnum
+ * \return 1 - true, 0 - false
+ */
int
afs_CellNumValid(afs_int32 cellnum)
{
unsigned int VNOSERVERS = 0;
+
+/**
+ * Try setting up a connection to the server containing the specified fid.
+ * Gets the volume, checks if it's up and does the connection by server address.
+ *
+ * @param afid
+ * @param areq Request filled in by the caller.
+ * @param locktype Type of lock that will be used.
+ *
+ * @return The conn struct, or NULL.
+ */
struct conn *
afs_Conn(register struct VenusFid *afid, register struct vrequest *areq,
afs_int32 locktype)
struct srvAddr *sa1p;
AFS_STATCNT(afs_Conn);
+ /* Get fid's volume. */
tv = afs_GetVolume(afid, areq, READ_LOCK);
if (!tv) {
if (areq) {
} /*afs_Conn */
+/**
+ * Connects to a server by it's server address.
+ *
+ * @param sap Server address.
+ * @param aport Server port.
+ * @param acell
+ * @param tu Connect as this user.
+ * @param force_if_down
+ * @param create
+ * @param locktype Specifies type of lock to be used for this function.
+ *
+ * @return The new connection.
+ */
struct conn *
afs_ConnBySA(struct srvAddr *sap, unsigned short aport, afs_int32 acell,
struct unixuser *tu, int force_if_down, afs_int32 create,
}
ObtainSharedLock(&afs_xconn, 15);
+ /* Get conn by port and user. */
for (tc = sap->conns; tc; tc = tc->next) {
if (tc->user == tu && tc->port == aport) {
break;
}
if (!tc && !create) {
+ /* Not found and can't create a new one. */
ReleaseSharedLock(&afs_xconn);
return NULL;
}
afs_ActivateServer(sap);
ConvertWToSLock(&afs_xconn);
- }
+ } /* end of if (!tc) */
tc->refCount++;
if (tu->states & UTokensBad) {
if (csec)
rxs_Release(csec);
ConvertWToSLock(&afs_xconn);
- }
+ } /* end of if (tc->forceConnectFS)*/
ReleaseSharedLock(&afs_xconn);
return tc;
}
-/*
- * afs_ConnByHost
- *
+/**
* forceConnectFS is set whenever we must recompute the connection. UTokensBad
* is true only if we know that the tokens are bad. We thus clear this flag
* when we get a new set of tokens..
* Having force... true and UTokensBad true simultaneously means that the tokens
* went bad and we're supposed to create a new, unauthenticated, connection.
+ *
+ * @param aserver Server to connect to.
+ * @param aport Connection port.
+ * @param acell The cell where all of this happens.
+ * @param areq The request.
+ * @param aforce Force connection?
+ * @param locktype Type of lock to be used.
+ *
+ * @return The established connection.
*/
struct conn *
afs_ConnByHost(struct server *aserver, unsigned short aport, afs_int32 acell,
} /*afs_ConnByHost */
+/**
+ * Connect by multiple hosts.
+ * Try to connect to one of the hosts from the ahosts array.
+ *
+ * @param ahosts Multiple hosts to connect to.
+ * @param aport Connection port.
+ * @param acell The cell where all of this happens.
+ * @param areq The request.
+ * @param locktype Type of lock to be used.
+ *
+ * @return The established connection or NULL.
+ */
struct conn *
afs_ConnByMHosts(struct server *ahosts[], unsigned short aport,
afs_int32 acell, register struct vrequest *areq,
} /*afs_ConnByMHosts */
+/**
+ * Decrement reference count to this connection.
+ * @param ac
+ * @param locktype
+ */
void
afs_PutConn(register struct conn *ac, afs_int32 locktype)
{
} /*afs_PutConn */
-/* for multi homed clients, an RPC may timeout because of a
-client network interface going down. We need to reopen new
-connections in this case
-*/
+/**
+ * For multi homed clients, a RPC may timeout because of a
+ * client network interface going down. We need to reopen new
+ * connections in this case.
+ *
+ * @param sap Server address.
+ */
void
ForceNewConnections(struct srvAddr *sap)
{
* --------------------- Exported definitions ---------------------
*/
/* For split cache */
-afs_int32 afs_blocksUsed_0; /*1K blocks in cache - in theory is zero */
-afs_int32 afs_blocksUsed_1; /*1K blocks in cache */
-afs_int32 afs_blocksUsed_2; /*1K blocks in cache */
+afs_int32 afs_blocksUsed_0; /*!< 1K blocks in cache - in theory is zero */
+afs_int32 afs_blocksUsed_1; /*!< 1K blocks in cache */
+afs_int32 afs_blocksUsed_2; /*!< 1K blocks in cache */
afs_int32 afs_pct1 = -1;
afs_int32 afs_pct2 = -1;
afs_uint32 afs_tpct1 = 0;
afs_uint32 afs_tpct2 = 0;
afs_uint32 splitdcache = 0;
-afs_lock_t afs_xdcache; /*Lock: alloc new disk cache entries */
-afs_int32 afs_freeDCList; /*Free list for disk cache entries */
-afs_int32 afs_freeDCCount; /*Count of elts in freeDCList */
-afs_int32 afs_discardDCList; /*Discarded disk cache entries */
-afs_int32 afs_discardDCCount; /*Count of elts in discardDCList */
-struct dcache *afs_freeDSList; /*Free list for disk slots */
-struct dcache *afs_Initial_freeDSList; /*Initial list for above */
-ino_t cacheInode; /*Inode for CacheItems file */
-struct osi_file *afs_cacheInodep = 0; /* file for CacheItems inode */
-struct afs_q afs_DLRU; /*dcache LRU */
+afs_lock_t afs_xdcache; /*!< Lock: alloc new disk cache entries */
+afs_int32 afs_freeDCList; /*!< Free list for disk cache entries */
+afs_int32 afs_freeDCCount; /*!< Count of elts in freeDCList */
+afs_int32 afs_discardDCList; /*!< Discarded disk cache entries */
+afs_int32 afs_discardDCCount; /*!< Count of elts in discardDCList */
+struct dcache *afs_freeDSList; /*!< Free list for disk slots */
+struct dcache *afs_Initial_freeDSList; /*!< Initial list for above */
+ino_t cacheInode; /*!< Inode for CacheItems file */
+struct osi_file *afs_cacheInodep = 0; /*!< file for CacheItems inode */
+struct afs_q afs_DLRU; /*!< dcache LRU */
afs_int32 afs_dhashsize = 1024;
-afs_int32 *afs_dvhashTbl; /*Data cache hash table */
-afs_int32 *afs_dchashTbl; /*Data cache hash table */
-afs_int32 *afs_dvnextTbl; /*Dcache hash table links */
-afs_int32 *afs_dcnextTbl; /*Dcache hash table links */
-struct dcache **afs_indexTable; /*Pointers to dcache entries */
-afs_hyper_t *afs_indexTimes; /*Dcache entry Access times */
-afs_int32 *afs_indexUnique; /*dcache entry Fid.Unique */
-unsigned char *afs_indexFlags; /*(only one) Is there data there? */
-afs_hyper_t afs_indexCounter; /*Fake time for marking index
+afs_int32 *afs_dvhashTbl; /*!< Data cache hash table: hashed by FID + chunk number. */
+afs_int32 *afs_dchashTbl; /*!< Data cache hash table: hashed by FID. */
+afs_int32 *afs_dvnextTbl; /*!< Dcache hash table links */
+afs_int32 *afs_dcnextTbl; /*!< Dcache hash table links */
+struct dcache **afs_indexTable; /*!< Pointers to dcache entries */
+afs_hyper_t *afs_indexTimes; /*!< Dcache entry Access times */
+afs_int32 *afs_indexUnique; /*!< dcache entry Fid.Unique */
+unsigned char *afs_indexFlags; /*!< (only one) Is there data there? */
+afs_hyper_t afs_indexCounter; /*!< Fake time for marking index
* entries */
-afs_int32 afs_cacheFiles = 0; /*Size of afs_indexTable */
-afs_int32 afs_cacheBlocks; /*1K blocks in cache */
-afs_int32 afs_cacheStats; /*Stat entries in cache */
-afs_int32 afs_blocksUsed; /*Number of blocks in use */
-afs_int32 afs_blocksDiscarded; /*Blocks freed but not truncated */
-afs_int32 afs_fsfragsize = 1023; /*Underlying Filesystem minimum unit
+afs_int32 afs_cacheFiles = 0; /*!< Size of afs_indexTable */
+afs_int32 afs_cacheBlocks; /*!< 1K blocks in cache */
+afs_int32 afs_cacheStats; /*!< Stat entries in cache */
+afs_int32 afs_blocksUsed; /*!< Number of blocks in use */
+afs_int32 afs_blocksDiscarded; /*!<Blocks freed but not truncated */
+afs_int32 afs_fsfragsize = 1023; /*!< Underlying Filesystem minimum unit
*of disk allocation usually 1K
*this value is (truefrag -1 ) to
*save a bunch of subtracts... */
#ifdef AFS_64BIT_CLIENT
#ifdef AFS_VM_RDWR_ENV
-afs_size_t afs_vmMappingEnd; /* for large files (>= 2GB) the VM
+afs_size_t afs_vmMappingEnd; /* !< For large files (>= 2GB) the VM
* mapping an 32bit addressing machines
* can only be used below the 2 GB
* line. From this point upwards we
int afs_TruncateDaemonRunning = 0;
int afs_CacheTooFull = 0;
-afs_int32 afs_dcentries; /* In-memory dcache entries */
+afs_int32 afs_dcentries; /*!< In-memory dcache entries */
int dcacheDisabled = 0;
int cacheDiskType; /*Type of backing disk for cache */
struct afs_cacheOps *afs_cacheType;
+/*!
+ * Where is this vcache's entry associated dcache located/
+ * \param avc The vcache entry.
+ * \return Bucket index:
+ * 1 : main
+ * 2 : RO
+ */
static afs_int32
afs_DCGetBucket(struct vcache *avc)
{
return 1;
}
+/*!
+ * Readjust a dcache's size.
+ *
+ * \param adc The dcache to be adjusted.
+ * \param oldSize Old size for the dcache.
+ * \param newSize The new size to be adjusted to.
+ *
+ */
static void
afs_DCAdjustSize(struct dcache *adc, afs_int32 oldSize, afs_int32 newSize)
{
return;
}
+/*!
+ * Move a dcache from one bucket to another.
+ *
+ * \param adc Operate on this dcache.
+ * \param size Size in bucket (?).
+ * \param newBucket Destination bucket.
+ *
+ */
static void
afs_DCMoveBucket(struct dcache *adc, afs_int32 size, afs_int32 newBucket)
{
if (!splitdcache)
return;
+ /* Substract size from old bucket. */
switch (adc->bucket)
{
case 0:
break;
}
+ /* Set new bucket and increase destination bucket size. */
adc->bucket = newBucket;
switch (adc->bucket)
return;
}
+/*!
+ * Init split caches size.
+ */
static void
afs_DCSizeInit(void)
{
afs_blocksUsed_0 = afs_blocksUsed_1 = afs_blocksUsed_2 = 0;
}
+
+/*!
+ * \param phase
+ * \param bucket
+ */
static afs_int32
afs_DCWhichBucket(afs_int32 phase, afs_int32 bucket)
{
}
-/*
- * afs_StoreWarn
- *
- * Description:
- * Warn about failing to store a file.
+/*!
+ * Warn about failing to store a file.
*
- * Parameters:
- * acode : Associated error code.
- * avolume : Volume involved.
- * aflags : How to handle the output:
- * aflags & 1: Print out on console
- * aflags & 2: Print out on controlling tty
+ * \param acode Associated error code.
+ * \param avolume Volume involved.
+ * \param aflags How to handle the output:
+ * aflags & 1: Print out on console
+ * aflags & 2: Print out on controlling tty
*
- * Environment:
- * Call this from close call when vnodeops is RCS unlocked.
+ * \note Environment: Call this from close call when vnodeops is RCS unlocked.
*/
void
}
} /*afs_StoreWarn */
+/*!
+ * Try waking up truncation daemon, if it's worth it.
+ */
void
afs_MaybeWakeupTruncateDaemon(void)
{
}
}
-/* Keep statistics on run time for afs_CacheTruncateDaemon. This is a
+/*!
+ * /struct CTD_stats
+ *
+ * Keep statistics on run time for afs_CacheTruncateDaemon. This is a
* struct so we need only export one symbol for AIX.
*/
static struct CTD_stats {
} CTD_stats;
u_int afs_min_cache = 0;
+
+/*!
+ * Keeps the cache clean and free by truncating uneeded files, when used.
+ * \param
+ * \return
+ */
void
afs_CacheTruncateDaemon(void)
{
}
if (!afs_CacheIsTooFull())
afs_CacheTooFull = 0;
- }
+ } /* end of cache cleanup */
MReleaseWriteLock(&afs_xdcache);
/*
}
-/*
- * afs_AdjustSize
- *
- * Description:
- * Make adjustment for the new size in the disk cache entry
+/*!
+ * Make adjustment for the new size in the disk cache entry
*
- * Major Assumptions Here:
+ * \note Major Assumptions Here:
* Assumes that frag size is an integral power of two, less one,
* and that this is a two's complement machine. I don't
* know of any filesystems which violate this assumption...
*
- * Parameters:
- * adc : Ptr to dcache entry.
- * anewsize : New size desired.
+ * \param adc Ptr to dcache entry.
+ * \param anewsize New size desired.
+ *
*/
void
}
-/*
- * afs_GetDownD
- *
- * Description:
- * This routine is responsible for moving at least one entry (but up
- * to some number of them) from the LRU queue to the free queue.
+/*!
+ * This routine is responsible for moving at least one entry (but up
+ * to some number of them) from the LRU queue to the free queue.
*
- * Parameters:
- * anumber : Number of entries that should ideally be moved.
- * aneedSpace : How much space we need (1K blocks);
+ * \param anumber Number of entries that should ideally be moved.
+ * \param aneedSpace How much space we need (1K blocks);
*
- * Environment:
+ * \note Environment:
* The anumber parameter is just a hint; at least one entry MUST be
* moved, or we'll panic. We must be called with afs_xdcache
* write-locked. We should try to satisfy both anumber and aneedspace,
* the whole set of MAXATONCE.
* 2. dynamically choose MAXATONCE to reflect severity of
* demand: something like (*aneedSpace >> (logChunk - 9))
- * N.B. if we're called with aneedSpace <= 0 and anumber > 0, that
+ *
+ * \note N.B. if we're called with aneedSpace <= 0 and anumber > 0, that
* indicates that the cache is not properly configured/tuned or
* something. We should be able to automatically correct that problem.
*/
}
}
afs_PutDCache(tdc);
- }
+ } /* end of for victims loop */
if (phase < 5) {
/* Phase is 0 and no one was found, so try phase 1 (ignore
} /*afs_GetDownD */
-/*
- * Description: remove adc from any hash tables that would allow it to be located
+/*!
+ * Remove adc from any hash tables that would allow it to be located
* again by afs_FindDCache or afs_GetDCache.
*
- * Parameters: adc -- pointer to dcache entry to remove from hash tables.
- * zap -- zap the given dcache ?
+ * \param adc Pointer to dcache entry to remove from hash tables.
+ *
+ * \note Locks: Must have the afs_xdcache lock write-locked to call this function.
*
- * Locks: Must have the afs_xdcache lock write-locked to call this function.
*/
int
afs_HashOutDCache(struct dcache *adc, int zap)
return 0;
} /*afs_HashOutDCache */
-/*
- * afs_FlushDCache
- *
- * Description:
- * Flush the given dcache entry, pulling it from hash chains
- * and truncating the associated cache file.
+/*!
+ * Flush the given dcache entry, pulling it from hash chains
+ * and truncating the associated cache file.
*
- * Arguments:
- * adc: Ptr to dcache entry to flush.
+ * \param adc Ptr to dcache entry to flush.
*
- * Environment:
+ * \note Environment:
* This routine must be called with the afs_xdcache lock held
- * (in write mode)
+ * (in write mode).
*/
-
void
afs_FlushDCache(register struct dcache *adc)
{
} /*afs_FlushDCache */
-/*
- * afs_FreeDCache
- *
- * Description: put a dcache entry on the free dcache entry list.
+/*!
+ * Put a dcache entry on the free dcache entry list.
*
- * Parameters: adc -- dcache entry to free
+ * \param adc dcache entry to free.
*
- * Environment: called with afs_xdcache lock write-locked.
+ * \note Environment: called with afs_xdcache lock write-locked.
*/
static void
afs_FreeDCache(register struct dcache *adc)
afs_osi_Wakeup(&afs_WaitForCacheDrain);
}
}
-}
+} /* afs_FreeDCache */
-/*
- * afs_DiscardDCache
- *
- * Description:
- * Discard the cache element by moving it to the discardDCList.
- * This puts the cache element into a quasi-freed state, where
- * the space may be reused, but the file has not been truncated.
+/*!
+ * Discard the cache element by moving it to the discardDCList.
+ * This puts the cache element into a quasi-freed state, where
+ * the space may be reused, but the file has not been truncated.
*
- * Major Assumptions Here:
+ * \note Major Assumptions Here:
* Assumes that frag size is an integral power of two, less one,
* and that this is a two's complement machine. I don't
* know of any filesystems which violate this assumption...
*
- * Parameters:
- * adc : Ptr to dcache entry.
+ * \param adr Ptr to dcache entry.
*
- * Environment:
+ * \note Environment:
* Must be called with afs_xdcache write-locked.
*/
} /*afs_DiscardDCache */
-/*
- * afs_FreeDiscardedDCache
- *
- * Description:
- * Free the next element on the list of discarded cache elements.
+/*!
+ * Free the next element on the list of discarded cache elements.
*/
static void
afs_FreeDiscardedDCache(void)
MReleaseWriteLock(&afs_xdcache);
}
-/*
- * afs_MaybeFreeDiscardedDCache
- *
- * Description:
- * Free as many entries from the list of discarded cache elements
- * as we need to get the free space down below CM_WAITFORDRAINPCT (98%).
+/*!
+ * Free as many entries from the list of discarded cache elements
+ * as we need to get the free space down below CM_WAITFORDRAINPCT (98%).
*
- * Parameters:
- * None
+ * \return 0
*/
int
afs_MaybeFreeDiscardedDCache(void)
return 0;
}
-/*
- * afs_GetDownDSlot
- *
- * Description:
- * Try to free up a certain number of disk slots.
+/*!
+ * Try to free up a certain number of disk slots.
*
- * Parameters:
- * anumber : Targeted number of disk slots to free up.
+ * \param anumber Targeted number of disk slots to free up.
*
- * Environment:
+ * \note Environment:
* Must be called with afs_xdcache write-locked.
+ *
*/
static void
afs_GetDownDSlot(int anumber)
-/*
- * afs_WriteDCache
+/*!
+ * Write a particular dcache entry back to its home in the
+ * CacheInfo file.
*
- * Description:
- * write a particular dcache entry back to its home in the
- * CacheInfo file.
+ * \param adc Pointer to the dcache entry to write.
+ * \param atime If true, set the modtime on the file to the current time.
*
- * Parameters:
- * adc : Pointer to the dcache entry to write.
- * atime : If true, set the modtime on the file to the current time.
- *
- * Environment:
+ * \note Environment:
* Must be called with the afs_xdcache lock at least read-locked,
* and dcache entry at least read-locked.
* The reference count is not changed.
-/*
- * afs_wakeup
- *
- * Description:
- * Wake up users of a particular file waiting for stores to take
- * place.
+/*!
+ * Wake up users of a particular file waiting for stores to take
+ * place.
*
- * Parameters:
- * avc : Ptr to related vcache entry.
+ * \param avc Ptr to related vcache entry.
*
- * Environment:
+ * \note Environment:
* Nothing interesting.
*/
-
int
afs_wakeup(register struct vcache *avc)
{
}
-/*
- * afs_InitCacheFile
- *
- * Description:
- * Given a file name and inode, set up that file to be an
- * active member in the AFS cache. This also involves checking
- * the usability of its data.
+/*!
+ * Given a file name and inode, set up that file to be an
+ * active member in the AFS cache. This also involves checking
+ * the usability of its data.
*
- * Parameters:
- * afile : Name of the cache file to initialize.
- * ainode : Inode of the file.
+ * \param afile Name of the cache file to initialize.
+ * \param ainode Inode of the file.
*
- * Environment:
+ * \note Environment:
* This function is called only during initialization.
*/
-
int
afs_InitCacheFile(char *afile, ino_t ainode)
{
*/
#define DDSIZE 200
-/*
- * afs_dcacheInit
+/*!
+ * Initialize dcache related variables.
+ *
+ * \param afiles
+ * \param ablocks
+ * \param aDentries
+ * \param achunk
+ * \param aflags
*
- * Description:
- * Initialize dcache related variables.
*/
void
afs_dcacheInit(int afiles, int ablocks, int aDentries, int achunk, int aflags)
QInit(&afs_DLRU);
}
-/*
- * shutdown_dcache
+/*!
+ * Shuts down the cache.
*
*/
void
* look into interactions of dnlc and readdir.
* cache larger names, perhaps by using a better,longer key (SHA) and discarding
* the actual name itself.
- * precompute a key and stuff for @sys, and combine the HandleAtName function with
+ * precompute a key and stuff for \sys, and combine the HandleAtName function with
* this, since we're looking at the name anyway.
*/
return 0;
}
-/* remove anything pertaining to this directory. I can invalidate
+/*!
+ * Remove anything pertaining to this directory. I can invalidate
* things without the lock, since I am just looking through the array,
* but to move things off the lists or into the freelist, I need the
- * write lock */
+ * write lock
+ *
+ * \param adp vcache entry for the directory to be purged.
+ * \return 0
+ */
int
osi_dnlc_purgedp(struct vcache *adp)
{
return 0;
}
-/* remove anything pertaining to this file */
+/*!
+ * Remove anything pertaining to this file
+ *
+ * \param File vcache entry.
+ * \return 0
+ */
int
osi_dnlc_purgevp(struct vcache *avc)
{
afs_int32 afs_in_sync = 0;
#endif
+/*!
+ * \defgroup pioctl Path IOCTL functions
+ *
+ * DECL_PIOCTL is a macro defined to contain the following parameters for functions:
+ *
+ * \param[in] avc the AFS vcache structure in use by pioctl
+ * \param[in] afun not in use
+ * \param[in] areq the AFS vrequest structure
+ * \param[in] ain as defined by the function
+ * \param[in] aout as defined by the function
+ * \param[in] ainSize size of ain
+ * \param[in] aoutSize size of aout
+ * \param[in] acred UNIX credentials structure underlying the operation
+ */
+
#define DECL_PIOCTL(x) static int x(struct vcache *avc, int afun, struct vrequest *areq, \
char *ain, char *aout, afs_int32 ainSize, afs_int32 *aoutSize, \
struct AFS_UCRED **acred)
return afs_CheckCode(code, &treq, 41);
}
+/*!
+ * VIOCETFID (22) - Get file ID quickly
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use
+ * \param[out] aout not in use
+ *
+ * \retval EINVAL Error if some of the initial arguments aren't set
+ *
+ * \post get the file id of some file
+ */
DECL_PIOCTL(PGetFID)
{
AFS_STATCNT(PGetFID);
return 0;
}
+/*!
+ * VIOCSETAL (1) - Set access control list
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the ACL being set
+ * \param[out] aout the ACL being set returned
+ *
+ * \retval EINVAL Error if some of the standard args aren't set
+ *
+ * \post Changed ACL, via direct writing to the wire
+ */
+int dummy_PSetAcl(char *ain, char *aout)
+{
+ return 0;
+}
+
DECL_PIOCTL(PSetAcl)
{
register afs_int32 code;
int afs_defaultAsynchrony = 0;
+/*!
+ * VIOC_STOREBEHIND (47) Adjust store asynchrony
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain sbstruct (store behind structure) input
+ * \param[out] aout resulting sbstruct
+ *
+ * \retval EPERM Error if the user doesn't have super-user credentials
+ * \retval EACCES Error if there isn't enough access to not check the mode bits
+ *
+ * \post sets asynchrony based on a file, from a struct sbstruct "I THINK"
+ */
DECL_PIOCTL(PStoreBehind)
{
afs_int32 code = 0;
return code;
}
+/*!
+ * VIOC_GCPAGS (48) - Disable automatic PAG gc'ing
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use
+ * \param[out] aout not in use
+ *
+ * \retval EACCES Error if the user doesn't have super-user credentials
+ *
+ * \post set the gcpags to GCPAGS_USERDISABLED
+ */
DECL_PIOCTL(PGCPAGs)
{
if (!afs_osi_suser(*acred)) {
return 0;
}
+/*!
+ * VIOCGETAL (2) - Get access control list
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use
+ * \param[out] aout the ACL
+ *
+ * \retval EINVAL Error if some of the standard args aren't set
+ * \retval ERANGE Error if the vnode of the file id is too large
+ * \retval -1 Error if getting the ACL failed
+ *
+ * \post Obtain the ACL, based on file ID
+ *
+ * \notes there is a hack to tell which type of ACL is being returned, checks the top 2-bytes to judge what type of ACL it is, only for dfs xlat or ACLs
+ */
DECL_PIOCTL(PGetAcl)
{
struct AFSOpaque acl;
return code;
}
+/*!
+ * PNoop returns success. Used for functions which are not implemented or are no longer in use.
+ *
+ * \ingroup pioctl
+ *
+ * \notes Functions involved in this: 17 (VIOCENGROUP) -- used to be enable group; 18 (VIOCDISGROUP) -- used to be disable group; 2 (?) -- get/set cache-bypass size threshold
+ */
DECL_PIOCTL(PNoop)
{
AFS_STATCNT(PNoop);
return 0;
}
+/*!
+ * PBogus returns fail. Used for functions which are not implemented or are no longer in use.
+ *
+ * \ingroup pioctl
+ *
+ * \retval EINVAL Error if some of the standard args aren't set
+ *
+ * \notes Functions involved in this: 0 (?); 4 (?); 6 (?); 7 (VIOCSTAT); 8 (?); 13 (VIOCGETTIME) -- used to be quick check time; 15 (VIOCPREFETCH) -- prefetch is now special-cased; see pioctl code!; 16 (VIOCNOP) -- used to be testing code; 19 (VIOCLISTGROUPS) -- used to be list group; 23 (VIOCWAITFOREVER) -- used to be waitforever; 57 (VIOC_FPRIOSTATUS) -- arla: set file prio; 58 (VIOC_FHGET) -- arla: fallback getfh; 59 (VIOC_FHOPEN) -- arla: fallback fhopen; 60 (VIOC_XFSDEBUG) -- arla: controls xfsdebug; 61 (VIOC_ARLADEBUG) -- arla: controls arla debug; 62 (VIOC_AVIATOR) -- arla: debug interface; 63 (VIOC_XFSDEBUG_PRINT) -- arla: print xfs status; 64 (VIOC_CALCULATE_CACHE) -- arla: force cache check; 65 (VIOC_BREAKCELLBACK) -- arla: break callback; 68 (?) -- arla: fetch stats;
+ */
DECL_PIOCTL(PBogus)
{
AFS_STATCNT(PBogus);
return EINVAL;
}
+/*!
+ * VIOC_FILE_CELL_NAME (30) - Get cell in which file lives
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use (avc used to pass in file id)
+ * \param[out] aout cell name
+ *
+ * \retval EINVAL Error if some of the standard args aren't set
+ * \retval ESRCH Error if the file isn't part of a cell
+ *
+ * \post Get a cell based on a passed in file id
+ */
DECL_PIOCTL(PGetFileCell)
{
register struct cell *tcell;
return 0;
}
+/*!
+ * VIOC_GET_WS_CELL (31) - Get cell in which workstation lives
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use
+ * \param[out] aout cell name
+ *
+ * \retval EIO Error if the afs daemon hasn't started yet
+ * \retval ESRCH Error if the machine isn't part of a cell, for whatever reason
+ *
+ * \post Get the primary cell that the machine is a part of.
+ */
DECL_PIOCTL(PGetWSCell)
{
struct cell *tcell = NULL;
return 0;
}
+/*!
+ * VIOC_GET_PRIMARY_CELL (33) - Get primary cell for caller
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use (user id found via areq)
+ * \param[out] aout cell name
+ *
+ * \retval ESRCH Error if the user id doesn't have a primary cell specified
+ *
+ * \post Get the primary cell for a certain user, based on the user's uid
+ */
DECL_PIOCTL(PGetUserCell)
{
register afs_int32 i;
return 0;
}
+/*!
+ * VIOCSETTOK (3) - Set authentication tokens
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the krb tickets from which to set the afs tokens
+ * \param[out] aout not in use
+ *
+ * \retval EINVAL Error if the ticket is either too long or too short
+ * \retval EIO Error if the AFS initState is below 101
+ * \retval ESRCH Error if the cell for which the Token is being set can't be found
+ *
+ * \post Set the Tokens for a specific cell name, unless there is none set, then default to primary
+ *
+ */
DECL_PIOCTL(PSetTokens)
{
afs_int32 i;
}
}
+/*!
+ * VIOCGETVOLSTAT (4) - Get volume status
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use
+ * \param[out] aout status of the volume
+ *
+ * \retval EINVAL Error if some of the standard args aren't set
+ *
+ * \post The status of a volume (based on the FID of the volume), or an offline message /motd
+ */
DECL_PIOCTL(PGetVolumeStatus)
{
char volName[32];
return code;
}
+/*!
+ * VIOCSETVOLSTAT (5) - Set volume status
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain values to set the status at, offline message, message of the day, volume name, minimum quota, maximum quota
+ * \param[out] aout status of a volume, offlines messages, minimum quota, maximumm quota
+ *
+ * \retval EINVAL Error if some of the standard args aren't set
+ * \retval EROFS Error if the volume is read only, or a backup volume
+ * \retval ENODEV Error if the volume can't be accessed
+ * \retval E2BIG Error if the volume name, offline message, and motd are too big
+ *
+ * \post Set the status of a volume, including any offline messages, a minimum quota, and a maximum quota
+ */
DECL_PIOCTL(PSetVolumeStatus)
{
char volName[32];
return code;
}
+/*!
+ * VIOCFLUSH (6) - Invalidate cache entry
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use
+ * \param[out] aout not in use
+ *
+ * \retval EINVAL Error if some of the standard args aren't set
+ *
+ * \post Flush any information the cache manager has on an entry
+ */
DECL_PIOCTL(PFlush)
{
AFS_STATCNT(PFlush);
return 0;
}
+/*!
+ * VIOC_AFS_STAT_MT_PT (29) - Stat mount point
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the last component in a path, related to mountpoint that we're looking for information about
+ * \param[out] aout volume, cell, link data
+ *
+ * \retval EINVAL Error if some of the standard args aren't set
+ * \retval ENOTDIR Error if the 'mount point' argument isn't a directory
+ * \retval EIO Error if the link data can't be accessed
+ *
+ * \post Get the volume, and cell, as well as the link data for a mount point
+ */
DECL_PIOCTL(PNewStatMount)
{
register afs_int32 code;
return code;
}
+/*!
+ * VIOCGETTOK (8) - Get authentication tokens
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain userid
+ * \param[out] aout token
+ *
+ * \retval EIO Error if the afs daemon hasn't started yet
+ * \retval EDOM Error if the input parameter is out of the bounds of the available tokens
+ * \retval ENOTCONN Error if there aren't tokens for this cell
+ *
+ * \post If the input paramater exists, get the token that corresponds to the parameter value, if there is no token at this value, get the token for the first cell
+ *
+ * \notes "it's a weird interface (from comments in the code)"
+ */
+
DECL_PIOCTL(PGetTokens)
{
register struct cell *tcell;
return 0;
}
+/*!
+ * VIOCUNLOG (9) - Invalidate tokens
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use
+ * \param[out] aout not in use
+ *
+ * \retval EIO Error if the afs daemon hasn't been started yet
+ *
+ * \post remove tokens from a user, specified by the user id
+ *
+ * \notes sets the token's time to 0, which then causes it to be removed
+ * \notes Unlog is the same as un-pag in OpenAFS
+ */
DECL_PIOCTL(PUnlog)
{
register afs_int32 i;
return 0;
}
+/*!
+ * VIOC_AFS_MARINER_HOST (32) - Get/set mariner (cache manager monitor) host
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain host address to be set
+ * \param[out] aout old host address
+ *
+ * \post depending on whether or not a variable is set, either get the host for the cache manager monitor, or set the old address and give it a new address
+ *
+ * \notes Errors turn off mariner
+ */
DECL_PIOCTL(PMariner)
{
afs_int32 newHostAddr;
return 0;
}
+/*!
+ * VIOCCKSERV (10) - Check that servers are up
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain name of the cell
+ * \param[out] aout current down server list
+ *
+ * \retval EIO Error if the afs daemon hasn't started yet
+ * \retval EACCES Error if the user doesn't have super-user credentials
+ * \retval ENOENT Error if we are unable to obtain the cell
+ *
+ * \post Either a fast check (where it doesn't contact servers) or a local check (checks local cell only)
+ */
DECL_PIOCTL(PCheckServers)
{
register char *cp = 0;
return 0;
}
+/*!
+ * VIOCCKBACK (11) - Check backup volume mappings
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use
+ * \param[out] aout not in use
+ *
+ * \retval EIO Error if the afs daemon hasn't started yet
+ *
+ * \post Check the root volume, and then check the names if the volume check variable is set to force, has expired, is busy, or if the mount points variable is set
+ */
DECL_PIOCTL(PCheckVolNames)
{
AFS_STATCNT(PCheckVolNames);
return 0;
}
+/*!
+ * VIOCCKCONN (12) - Check connections for a user
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use
+ * \param[out] aout not in use
+ *
+ * \retval EACCESS Error if no user is specififed, the user has no tokens set, or if the user's tokens are bad
+ *
+ * \post check to see if a user has the correct authentication. If so, allow access.
+ *
+ * \notes Check the connections to all the servers specified
+ */
DECL_PIOCTL(PCheckAuth)
{
int i;
return 0;
}
+/*!
+ * VIOCWHEREIS (14) - Find out where a volume is located
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use
+ * \param[out] aout volume location
+ *
+ * \retval EINVAL Error if some of the default arguments don't exist
+ * \retval ENODEV Error if there is no such volume
+ *
+ * \post fine a volume, based on a volume file id
+ *
+ * \notes check each of the servers specified
+ */
DECL_PIOCTL(PFindVolume)
{
register struct volume *tvp;
return ENODEV;
}
+/*!
+ * VIOCACCESS (20) - Access using PRS_FS bits
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain PRS_FS bits
+ * \param[out] aout not in use
+ *
+ * \retval EINVAL Error if some of the initial arguments aren't set
+ * \retval EACCES Error if access is denied
+ *
+ * \post check to make sure access is allowed
+ */
DECL_PIOCTL(PViceAccess)
{
register afs_int32 code;
return 0;
}
+/*!
+ * VIOCSETCACHESIZE (24) - Set venus cache size in 1000 units
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the size the venus cache should be set to
+ * \param[out] aout not in use
+ *
+ * \retval EACCES Error if the user doesn't have super-user credentials
+ * \retval EROFS Error if the cache is set to be in memory
+ *
+ * \post Set the cache size based on user input. If no size is given, set it to the default OpenAFS cache size.
+ *
+ * \notes recompute the general cache parameters for every single block allocated
+ */
DECL_PIOCTL(PSetCacheSize)
{
afs_int32 newValue;
}
#define MAXGCSTATS 16
+/*!
+ * VIOCGETCACHEPARMS (40) - Get cache stats
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain afs index flags
+ * \param[out] aout cache blocks, blocks used, blocks files (in an array)
+ *
+ * \post Get the cache blocks, and how many of the cache blocks there are
+ */
DECL_PIOCTL(PGetCacheSize)
{
afs_int32 results[MAXGCSTATS];
return 0;
}
+/*!
+ * VIOCFLUSHCB (25) - Flush callback only
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use
+ * \param[out] aout not in use
+ *
+ * \retval EINVAL Error if some of the standard args aren't set
+ * \retval 0 0 returned if the volume is set to read-only
+ *
+ * \post Flushes callbacks, by setting the length of callbacks to one, setting the next callback to be sent to the CB_DROPPED value, and then dequeues everything else.
+ */
DECL_PIOCTL(PRemoveCallBack)
{
register struct conn *tc;
return 0;
}
+/*!
+ * VIOCNEWCELL (26) - Configure new cell
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the name of the cell, the hosts that will be a part of the cell, whether or not it's linked with another cell, the other cell it's linked with, the file server port, and the volume server port
+ * \param[out] aout not in use
+ *
+ * \retval EIO Error if the afs daemon hasn't started yet
+ * \retval EACCES Error if the user doesn't have super-user cedentials
+ * \retval EINVAL Error if some 'magic' var doesn't have a certain bit set
+ *
+ * \post creates a new cell
+ */
DECL_PIOCTL(PNewCell)
{
/* create a new cell */
return code;
}
+/*!
+ * VIOCGETCELL (27) - Get cell info
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain The cell index of a specific cell
+ * \param[out] aout list of servers in the cell
+ *
+ * \retval EIO Error if the afs daemon hasn't started yet
+ * \retval EDOM Error if there is no cell asked about
+ *
+ * \post Lists the cell's server names and and addresses
+ */
DECL_PIOCTL(PListCells)
{
afs_int32 whichCell;
return EDOM;
}
+/*!
+ * VIOC_AFS_DELETE_MT_PT (28) - Delete mount point
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the name of the file in this dir to remove
+ * \param[out] aout not in use
+ *
+ * \retval EINVAL Error if some of the standard args aren't set
+ * \retval ENOTDIR Error if the argument to remove is not a directory
+ * \retval ENOENT Error if there is no cache to remove the mount point from or if a vcache doesn't exist
+ *
+ * \post Ensure that everything is OK before deleting the mountpoint. If not, don't delete. Delete a mount point based on a file id.
+ */
DECL_PIOCTL(PRemoveMount)
{
register afs_int32 code;
return code;
}
+/*!
+ * VIOC_VENUSLOG (34) - Enable/Disable venus logging
+ *
+ * \ingroup pioctl
+ *
+ * \retval EINVAL Error if some of the standard args aren't set
+ *
+ * \notes Obsoleted, perhaps should be PBogus
+ */
DECL_PIOCTL(PVenusLogging)
{
return EINVAL; /* OBSOLETE */
}
+/*!
+ * VIOC_GETCELLSTATUS (35) - Get cell status info
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain The cell you want status information on
+ * \param[out] aout cell state (as a struct)
+ *
+ * \retval EIO Error if the afs daemon hasn't started yet
+ * \retval ENOENT Error if the cell doesn't exist
+ *
+ * \post Returns the state of the cell as defined in a struct cell
+ */
DECL_PIOCTL(PGetCellStatus)
{
register struct cell *tcell;
return 0;
}
+/*!
+ * VIOC_SETCELLSTATUS (36) - Set corresponding info
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain The cell you want to set information about, and the values you want to set
+ * \param[out] aout not in use
+ *
+ * \retval EIO Error if the afs daemon hasn't started yet
+ * \retval EACCES Error if the user doesn't have super-user credentials
+ *
+ * \post Set the state of the cell in a defined struct cell, based on whether or not SetUID is allowed
+ */
DECL_PIOCTL(PSetCellStatus)
{
register struct cell *tcell;
return 0;
}
+/*!
+ * VIOC_FLUSHVOLUME (37) - Flush whole volume's data
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use (args in avc)
+ * \param[out] aout not in use
+ *
+ * \retval EINVAL Error if some of the standard args aren't set
+ * \retval EIO Error if the afs daemon hasn't started yet
+ *
+ * \post Wipe everything on the volume. This is done dependent on which platform this is for.
+ *
+ * \notes Does not flush a file that a user has open and is using, because it will be re-created on next write. Also purges the dnlc, because things are screwed up.
+ */
DECL_PIOCTL(PFlushVolumeData)
{
register afs_int32 i;
}
-
+/*!
+ * VIOCGETVCXSTATUS (41) - gets vnode x status
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use (avc used)
+ * \param[out] aout vcxstat: the file id, the data version, any lock, the parent vnode, the parent unique id, the trunc position, the callback, cbExpires, what access is being made, what files are open, any users executing/writing, the flock ount, the states, the move stat
+ *
+ * \retval EINVAL Error if some of the initial default arguments aren't set
+ * \retval EACCES Error if access to check the mode bits is denied
+ *
+ * \post gets stats for the vnode, a struct listed in vcxstat
+ */
DECL_PIOCTL(PGetVnodeXStatus)
{
register afs_int32 code;
return 0;
}
-/* We require root for local sysname changes, but not for remote */
-/* (since we don't really believe remote uids anyway) */
- /* outname[] shouldn't really be needed- this is left as an excercise */
- /* for the reader. */
+
+/*!
+ * VIOC_AFS_SYSNAME (38) - Change @sys value
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain new value for @sys
+ * \param[out] aout count, entry, list (debug values?)
+ *
+ * \retval EINVAL Error if afsd isn't running, the new sysname is too large, the new sysname causes issues (starts with a .0 or ..0), there is no PAG set in the credentials, the user of a PAG can't be found, (!(exporter = au->exporter)) "NOT SURE ON THIS"
+ * \retval ENODEV Error if there isn't already a system named that ("I THINK")
+ * \retval EACCES Error if the user doesn't have super-user credentials
+ *
+ * \post Set the value of @sys if these things work: if the input isn't too long or if input doesn't start with .0 or ..0
+ *
+ * \notes We require root for local sysname changes, but not for remote (since we don't really believe remote uids anyway) outname[] shouldn't really be needed- this is left as an exercise for the reader.
+ */
DECL_PIOCTL(PSetSysName)
{
char *cp, *cp2 = NULL, inname[MAXSYSNAME], outname[MAXSYSNAME];
return 0;
}
- /* Note that this may only be performed by the local root user.
- */
+/*!
+ * VIOC_SETPREFS (46) - Set server ranks
+ *
+ * \param[in] ain the sprefs value you want the sprefs to be set to
+ * \param[out] aout not in use
+ *
+ * \retval EIO Error if the afs daemon hasn't started yet
+ * \retval EACCES Error if the user doesn't have super-user credentials
+ * \retval EINVAL Error if the struct setsprefs is too large or if it multiplied by the number of servers is too large
+ *
+ * \post set the sprefs using the afs_setsprefs() function
+ */
DECL_PIOCTL(PSetSPrefs)
{
struct setspref *ssp;
return 0;
}
+/*
+ * VIOC_SETPREFS33 (42) - Set server ranks (deprecated)
+ *
+ * \param[in] ain the server preferences to be set
+ * \param[out] aout not in use
+ *
+ * \retval EIO Error if the afs daemon hasn't started yet
+ * \retval EACCES Error if the user doesn't have super-user credentials
+ *
+ * \post set the server preferences, calling a function
+ *
+ * \notes this may only be performed by the local root user.
+ */
DECL_PIOCTL(PSetSPrefs33)
{
struct spref *sp;
return 0;
}
-/* some notes on the following code...
- * in the hash table of server structs, all servers with the same IP address
- * will be on the same overflow chain.
- * This could be sped slightly in some circumstances by having it cache the
- * immediately previous slot in the hash table and some supporting information
- * Only reports file servers now.
+/*
+ * VIOC_GETSPREFS (43) - Get server ranks
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the server preferences to get
+ * \param[out] aout the server preferences information
+ *
+ * \retval EIO Error if the afs daemon hasn't started yet
+ * \retval ENOENT Error if the sprefrequest is too large
+ *
+ * \post Get the sprefs
+ *
+ * \notes in the hash table of server structs, all servers with the same IP address; will be on the same overflow chain; This could be sped slightly in some circumstances by having it cache the immediately previous slot in the hash table and some supporting information; Only reports file servers now.
*/
DECL_PIOCTL(PGetSPrefs)
{
/* Enable/Disable the specified exporter. Must be root to disable an exporter */
int afs_NFSRootOnly = 1;
+/*!
+ * VIOC_EXPORTAFS (39) - Export afs to nfs clients
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain a struct Vic * EIOctl containing export values needed to change between nfs and afs
+ * \param[out] aout a struct of the exporter states (exporter->exp_states)
+ *
+ * \retval ENODEV Error if the exporter doesn't exist
+ * \retval EACCES Error if the user doesn't have super-user credentials
+ *
+ * \post Changes the state of various values to reflect the change of the export values between nfs and afs.
+ *
+ * \notes Legacy code obtained from IBM.
+ */
DECL_PIOCTL(PExportAfs)
{
afs_int32 export, newint =
return 0;
}
+/*!
+ * VIOC_GAG (44) - Silence Cache Manager
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the flags to either gag or de-gag the cache manager
+ * \param[out] aout not in use
+ *
+ * \retval EACCES Error if the user doesn't have super-user credentials
+ *
+ * \post set the gag flags, then show these flags
+ */
DECL_PIOCTL(PGag)
{
struct gaginfo *gagflags;
return 0;
}
-
+/*!
+ * VIOC_TWIDDLE (45) - Adjust RX knobs
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the previous settings of the 'knobs'
+ * \param[out] aout not in use
+ *
+ * \retval EACCES Error if the user doesn't have super-user credentials
+ *
+ * \post build out the struct rxp, from a struct rx
+ */
DECL_PIOCTL(PTwiddleRx)
{
struct rxparams *rxp;
return 0;
}
+/*!
+ * VIOC_GETINITPARAMS (49) - Get initial cache manager parameters
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use
+ * \param[out] aout initial cache manager params
+ *
+ * \retval E2BIG Error if the initial parameters are bigger than some PIGGYSIZE
+ *
+ * \post return the initial cache manager parameters
+ */
DECL_PIOCTL(PGetInitParams)
{
if (sizeof(struct cm_initparams) > PIGGYSIZE)
}
#endif
+/*!
+ * VIOC_GETRXKCRYPT (55) - Get rxkad encryption flag
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain not in use
+ * \param[out] aout value of cryptall
+ *
+ * \post get the value of cryptall (presumably whether or not things should be encrypted)
+ */
DECL_PIOCTL(PGetRxkcrypt)
{
memcpy(aout, (char *)&cryptall, sizeof(afs_int32));
return 0;
}
+/*!
+ * VIOC_SETRXKCRYPT (56) - Set rxkad encryption flag
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the argument whether or not things should be encrypted
+ * \param[out] aout not in use
+ *
+ * \retval EPERM Error if the user doesn't have super-user credentials
+ * \retval EINVAL Error if the input is too big, or if the input is outside the bounds of what it can be set to
+ *
+ * \post set whether or not things should be encrypted
+ *
+ * \notes may need to be modified at a later date to take into account other values for cryptall (beyond true or false)
+ */
DECL_PIOCTL(PSetRxkcrypt)
{
afs_int32 tmpval;
}
#endif /* AFS_NEED_CLIENTCONTEXT */
-/* get all interface addresses of this client */
+/*!
+ * VIOC_GETCPREFS (50) - Get client interface
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain sprefrequest input
+ * \param[out] aout spref information
+ *
+ * \retval EIO Error if the afs daemon hasn't started yet
+ * \retval EINVAL Error if some of the standard args aren't set
+ *
+ * \post get all interface addresses and other information of the client interface
+ */
DECL_PIOCTL(PGetCPrefs)
{
struct sprefrequest *spin; /* input */
return 0;
}
+/*!
+ * VIOC_SETCPREFS (51) - Set client interface
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the interfaces you want set
+ * \param[out] aout not in use
+ *
+ * \retval EIO Error if the afs daemon hasn't started yet
+ * \retval EINVAL Error if the input is too large for the struct
+ * \retval ENOMEM Error if there are too many servers
+ *
+ * \post set the callbak interfaces addresses to those of the hosts
+ */
DECL_PIOCTL(PSetCPrefs)
{
struct setspref *sin;
return 0;
}
+/*!
+ * VIOC_AFS_FLUSHMOUNT (52) - Flush mount symlink data
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the last part of a path to a mount point, which tells us what to flush
+ * \param[out] aout not in use
+ *
+ * \retval EINVAL Error if some of the initial arguments aren't set
+ * \retval ENOTDIR Error if the initial argument for the mount point isn't a directory
+ * \retval ENOENT Error if the dcache entry isn't set
+ *
+ * \post remove all of the mount data from the dcache regarding a certain mount point
+ */
DECL_PIOCTL(PFlushMount)
{
register afs_int32 code;
return code;
}
+/*!
+ * VIOC_RXSTAT_PROC (53) - Control process RX statistics
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the flags that control which stats to use
+ * \param[out] aout not in use
+ *
+ * \retval EACCES Error if the user doesn't have super-user credentials
+ * \retval EINVAL Error if the flag input is too long
+ *
+ * \post either enable process RPCStats, disable process RPCStats, or clear the process RPCStats
+ */
DECL_PIOCTL(PRxStatProc)
{
int code = 0;
}
+/*!
+ * VIOC_RXSTAT_PEER (54) - Control peer RX statistics
+ *
+ * \ingroup pioctl
+ *
+ * \param[in] ain the flags that control which statistics to use
+ * \param[out] aout not in use
+ *
+ * \retval EACCES Error if the user doesn't have super-user credentials
+ * \retval EINVAL Error if the flag input is too long
+ *
+ * \post either enable peer RPCStatws, disable peer RPCStats, or clear the peer RPCStats
+ */
DECL_PIOCTL(PRxStatPeer)
{
int code = 0;
/* Forward declarations */
static afs_int32 afs_QueueVCB(struct vcache *avc);
-/*
- * afs_HashCBRFid
- *
+/*!
* Generate an index into the hash table for a given Fid.
+ * \param fid
+ * \return The hash value.
*/
static int
afs_HashCBRFid(struct AFSFid *fid)
return (fid->Volume + fid->Vnode + fid->Unique) % CBRSIZE;
}
-/*
- * afs_InsertHashCBR
- *
+/*!
* Insert a CBR entry into the hash table.
* Must be called with afs_xvcb held.
+ * \param cbr
+ * \return
*/
static void
afs_InsertHashCBR(struct afs_cbr *cbr)
afs_cbrHashT[slot] = cbr;
}
-/*
- * afs_FlushVCache
- *
- * Description:
- * Flush the given vcache entry.
+/*!
*
- * Parameters:
- * avc : Pointer to vcache entry to flush.
- * slept : Pointer to int to set 1 if we sleep/drop locks, 0 if we don't.
+ * Flush the given vcache entry.
*
* Environment:
* afs_xvcache lock must be held for writing upon entry to
* LOCK: afs_FlushVCache afs_xvcache W
* REFCNT: vcache ref count must be zero on entry except for osf1
* RACE: lock is dropped and reobtained, permitting race in caller
+ *
+ * \param avc Pointer to vcache entry to flush.
+ * \param slept Pointer to int to set 1 if we sleep/drop locks, 0 if we don't.
+ *
*/
-
int
afs_FlushVCache(struct vcache *avc, int *slept)
{ /*afs_FlushVCache */
} /*afs_FlushVCache */
#ifndef AFS_SGI_ENV
-/*
- * afs_InactiveVCache
+/*!
+ * The core of the inactive vnode op for all but IRIX.
*
- * The core of the inactive vnode op for all but IRIX.
+ * \param avc
+ * \param acred
*/
void
afs_InactiveVCache(struct vcache *avc, struct AFS_UCRED *acred)
}
#endif
-/*
- * afs_AllocCBR
- *
- * Description: allocate a callback return structure from the
+/*!
+ * Allocate a callback return structure from the
* free list and return it.
*
- * Env: The alloc and free routines are both called with the afs_xvcb lock
+ * Environment: The alloc and free routines are both called with the afs_xvcb lock
* held, so we don't have to worry about blocking in osi_Alloc.
+ *
+ * \return The allocated afs_cbr.
*/
static struct afs_cbr *afs_cbrSpace = 0;
struct afs_cbr *
return tsp;
}
-/*
- * afs_FreeCBR
+/*!
+ * Free a callback return structure, removing it from all lists.
*
- * Description: free a callback return structure, removing it from all lists.
+ * Environment: the xvcb lock is held over these calls.
*
- * Parameters:
- * asp -- the address of the structure to free.
+ * \param asp The address of the structure to free.
*
- * Environment: the xvcb lock is held over these calls.
+ * \rerurn 0
*/
int
afs_FreeCBR(register struct afs_cbr *asp)
return 0;
}
-/*
- * afs_FlushVCBs
- *
- * Description: flush all queued callbacks to all servers.
- *
- * Parameters: none.
+/*!
+ * Flush all queued callbacks to all servers.
*
* Environment: holds xvcb lock over RPC to guard against race conditions
* when a new callback is granted for the same file later on.
+ *
+ * \return 0 for success.
*/
afs_int32
afs_FlushVCBs(afs_int32 lockit)
return 0;
}
-/*
- * afs_QueueVCB
- *
- * Description:
- * Queue a callback on the given fid.
- *
- * Parameters:
- * avc: vcache entry
+/*!
+ * Queue a callback on the given fid.
*
* Environment:
* Locks the xvcb lock.
* Called when the xvcache lock is already held.
+ *
+ * \param avc vcache entry
+ * \return 0 for success < 0 otherwise.
*/
static afs_int32
}
-/*
- * afs_RemoveVCB
- *
- * Description:
- * Remove a queued callback for a given Fid.
- *
- * Parameters:
- * afid: The fid we want cleansed of queued callbacks.
+/*!
+ * Remove a queued callback for a given Fid.
*
* Environment:
* Locks xvcb and xserver locks.
* Typically called with xdcache, xvcache and/or individual vcache
* entries locked.
+ *
+ * \param afid The fid we want cleansed of queued callbacks.
+ *
*/
void
#endif
}
-/*
- * afs_NewVCache
+/*!
+ * This routine is responsible for allocating a new cache entry
+ * from the free list. It formats the cache entry and inserts it
+ * into the appropriate hash tables. It must be called with
+ * afs_xvcache write-locked so as to prevent several processes from
+ * trying to create a new cache entry simultaneously.
*
- * Description:
- * This routine is responsible for allocating a new cache entry
- * from the free list. It formats the cache entry and inserts it
- * into the appropriate hash tables. It must be called with
- * afs_xvcache write-locked so as to prevent several processes from
- * trying to create a new cache entry simultaneously.
+ * LOCK: afs_NewVCache afs_xvcache W
*
- * Parameters:
- * afid : The file id of the file whose cache entry is being
- * created.
+ * \param afid The file id of the file whose cache entry is being created.
+ *
+ * \return The new vcache struct.
*/
-/* LOCK: afs_NewVCache afs_xvcache W */
struct vcache *
afs_NewVCache(struct VenusFid *afid, struct server *serverp)
{
return NULL;
}
}
- }
+ } /* finished freeing up space */
+/* Alloc new vnode. */
#if defined(AFS_LINUX22_ENV)
{
struct inode *ip;
if (tq == uq)
break;
}
- }
+ } /* end of if (!freeVCList) */
+
if (!freeVCList) {
/* none free, making one is better than a panic */
afs_stats_cmperf.vcacheXAllocs++; /* count in case we have a leak */
tvc = freeVCList; /* take from free list */
freeVCList = tvc->nextfree;
tvc->nextfree = NULL;
- }
+ } /* end of if (!freeVCList) */
+
#endif /* AFS_OSF_ENV */
#if defined(AFS_XBSD_ENV) || defined(AFS_DARWIN_ENV)
} /*afs_NewVCache */
-/*
- * afs_FlushActiveVcaches
+/*!
+ * ???
*
- * Description:
- * ???
+ * LOCK: afs_FlushActiveVcaches afs_xvcache N
*
- * Parameters:
- * doflocks : Do we handle flocks?
+ * \param doflocks : Do we handle flocks?
*/
-/* LOCK: afs_FlushActiveVcaches afs_xvcache N */
void
afs_FlushActiveVcaches(register afs_int32 doflocks)
{
-/*
- * afs_VerifyVCache
- *
- * Description:
- * Make sure a cache entry is up-to-date status-wise.
+/*!
+ * Make sure a cache entry is up-to-date status-wise.
*
* NOTE: everywhere that calls this can potentially be sped up
* by checking CStatd first, and avoiding doing the InitReq
* Anymore, the only places that call this KNOW already that the
* vcache is not up-to-date, so we don't screw around.
*
- * Parameters:
- * avc : Ptr to vcache entry to verify.
- * areq : ???
+ * \param avc : Ptr to vcache entry to verify.
+ * \param areq : ???
*/
+/*!
+ *
+ * Make sure a cache entry is up-to-date status-wise.
+ *
+ * NOTE: everywhere that calls this can potentially be sped up
+ * by checking CStatd first, and avoiding doing the InitReq
+ * if this is up-to-date.
+ *
+ * Anymore, the only places that call this KNOW already that the
+ * vcache is not up-to-date, so we don't screw around.
+ *
+ * \param avc Pointer to vcache entry to verify.
+ * \param areq
+ *
+ * \return 0 for success or other error codes.
+ */
int
afs_VerifyVCache2(struct vcache *avc, struct vrequest *areq)
{
} /*afs_VerifyVCache */
-/*
- * afs_SimpleVStat
- *
- * Description:
- * Simple copy of stat info into cache.
+/*!
+ * Simple copy of stat info into cache.
*
- * Parameters:
- * avc : Ptr to vcache entry involved.
- * astat : Ptr to stat info to copy.
+ * Callers:as of 1992-04-29, only called by WriteVCache
*
- * Environment:
- * Nothing interesting.
+ * \param avc Ptr to vcache entry involved.
+ * \param astat Ptr to stat info to copy.
*
- * Callers: as of 1992-04-29, only called by WriteVCache
*/
static void
afs_SimpleVStat(register struct vcache *avc,
} /*afs_SimpleVStat */
-/*
- * afs_WriteVCache
+/*!
+ * Store the status info *only* back to the server for a
+ * fid/vrequest.
*
- * Description:
- * Store the status info *only* back to the server for a
- * fid/vrequest.
+ * Environment: Must be called with a shared lock held on the vnode.
*
- * Parameters:
- * avc : Ptr to the vcache entry.
- * astatus : Ptr to the status info to store.
- * areq : Ptr to the associated vrequest.
+ * \param avc Ptr to the vcache entry.
+ * \param astatus Ptr to the status info to store.
+ * \param areq Ptr to the associated vrequest.
*
- * Environment:
- * Must be called with a shared lock held on the vnode.
+ * \return Operation status.
*/
int
#endif
-/*
- * afs_ProcessFS
- *
- * Description:
- * Copy astat block into vcache info
+/*!
+ * Copy astat block into vcache info
*
- * Parameters:
- * avc : Ptr to vcache entry.
- * astat : Ptr to stat block to copy in.
- * areq : Ptr to associated request.
+ * \note This code may get dataversion and length out of sync if the file has
+ * been modified. This is less than ideal. I haven't thought about it sufficiently
+ * to be certain that it is adequate.
*
- * Environment:
- * Must be called under a write lock
+ * \note Environment: Must be called under a write lock
*
- * Note: this code may get dataversion and length out of sync if the file has
- * been modified. This is less than ideal. I haven't thought about
- * it sufficiently to be certain that it is adequate.
+ * \param avc Ptr to vcache entry.
+ * \param astat Ptr to stat block to copy in.
+ * \param areq Ptr to associated request.
*/
void
afs_ProcessFS(register struct vcache *avc,
} /*afs_ProcessFS */
+/*!
+ * Get fid from server.
+ *
+ * \param afid
+ * \param areq Request to be passed on.
+ * \param name Name of ?? to lookup.
+ * \param OutStatus Fetch status.
+ * \param CallBackp
+ * \param serverp
+ * \param tsyncp
+ *
+ * \return Success status of operation.
+ */
int
afs_RemoteLookup(register struct VenusFid *afid, struct vrequest *areq,
char *name, struct VenusFid *nfid,
}
-/*
+/*!
* afs_GetVCache
*
- * Description:
- * Given a file id and a vrequest structure, fetch the status
- * information associated with the file.
+ * Given a file id and a vrequest structure, fetch the status
+ * information associated with the file.
*
- * Parameters:
- * afid : File ID.
- * areq : Ptr to associated vrequest structure, specifying the
- * user whose authentication tokens will be used.
- * avc : caller may already have a vcache for this file, which is
- * already held.
+ * \param afid File ID.
+ * \param areq Ptr to associated vrequest structure, specifying the
+ * user whose authentication tokens will be used.
+ * \param avc Caller may already have a vcache for this file, which is
+ * already held.
*
- * Environment:
+ * \note Environment:
* The cache entry is returned with an increased vrefCount field.
* The entry must be discarded by calling afs_PutVCache when you
* are through using the pointer to the cache entry.
* of a parent dir cache entry, given a file (to check its access
* control list). It also allows renames to be handled easily by
* locking directories in a constant order.
- * NB. NewVCache -> FlushVCache presently (4/10/95) drops the xvcache lock.
+ *
+ * \note NB. NewVCache -> FlushVCache presently (4/10/95) drops the xvcache lock.
+ *
+ * \note Might have a vcache structure already, which must
+ * already be held by the caller
*/
- /* might have a vcache structure already, which must
- * already be held by the caller */
-
struct vcache *
afs_GetVCache(register struct VenusFid *afid, struct vrequest *areq,
afs_int32 * cached, struct vcache *avc)
+/*!
+ * Lookup a vcache by fid. Look inside the cache first, if not
+ * there, lookup the file on the server, and then get it's fresh
+ * cache entry.
+ *
+ * \param afid
+ * \param areq
+ * \param cached Is element cached? If NULL, don't answer.
+ * \param adp
+ * \param aname
+ *
+ * \return The found element or NULL.
+ */
struct vcache *
afs_LookupVCache(struct VenusFid *afid, struct vrequest *areq,
afs_int32 * cached, struct vcache *adp, char *aname)
}
-/*
- * must be called with avc write-locked
+/*!
+ * Must be called with avc write-locked
* don't absolutely have to invalidate the hint unless the dv has
* changed, but be sure to get it right else there will be consistency bugs.
*/
} /*afs_StuffVcache */
#endif
-/*
- * afs_PutVCache
- *
- * Description:
- * Decrements the reference count on a cache entry.
+/*!
+ * Decrements the reference count on a cache entry.
*
- * Parameters:
- * avc : Pointer to the cache entry to decrement.
+ * \param avc Pointer to the cache entry to decrement.
*
- * Environment:
- * Nothing interesting.
+ * \note Environment: Nothing interesting.
*/
void
afs_PutVCache(register struct vcache *avc)
} /*afs_PutVCache */
+/*!
+ * Sleepa when searching for a vcache. Releases all the pending locks,
+ * sleeps then obtains the previously released locks.
+ *
+ * \param vcache Enter sleep state.
+ * \param flag Determines what locks to use.
+ *
+ * \return
+ */
static void findvc_sleep(struct vcache *avc, int flag) {
if (flag & IS_SLOCK) {
ReleaseSharedLock(&afs_xvcache);
}
}
}
-/*
- * afs_FindVCache
- *
- * Description:
- * Find a vcache entry given a fid.
+/*!
+ * Find a vcache entry given a fid.
*
- * Parameters:
- * afid : Pointer to the fid whose cache entry we desire.
- * retry: (SGI-specific) tell the caller to drop the lock on xvcache,
- * unlock the vnode, and try again.
- * flags: bit 1 to specify whether to compute hit statistics. Not
- * set if FindVCache is called as part of internal bookkeeping.
+ * \param afid Pointer to the fid whose cache entry we desire.
+ * \param retry (SGI-specific) tell the caller to drop the lock on xvcache,
+ * unlock the vnode, and try again.
+ * \param flag Bit 1 to specify whether to compute hit statistics. Not
+ * set if FindVCache is called as part of internal bookkeeping.
*
- * Environment:
- * Must be called with the afs_xvcache lock at least held at
- * the read level. In order to do the VLRU adjustment, the xvcache lock
- * must be shared-- we upgrade it here.
+ * \note Environment: Must be called with the afs_xvcache lock at least held at
+ * the read level. In order to do the VLRU adjustment, the xvcache lock
+ * must be shared-- we upgrade it here.
*/
struct vcache *
return tvc;
} /*afs_FindVCache */
-/*
- * afs_NFSFindVCache
- *
- * Description:
- * Find a vcache entry given a fid. Does a wildcard match on what we
- * have for the fid. If more than one entry, don't return anything.
+/*!
+ * Find a vcache entry given a fid. Does a wildcard match on what we
+ * have for the fid. If more than one entry, don't return anything.
*
- * Parameters:
- * avcp : Fill in pointer if we found one and only one.
- * afid : Pointer to the fid whose cache entry we desire.
- * retry: (SGI-specific) tell the caller to drop the lock on xvcache,
+ * \param avcp Fill in pointer if we found one and only one.
+ * \param afid Pointer to the fid whose cache entry we desire.
+ * \param retry (SGI-specific) tell the caller to drop the lock on xvcache,
* unlock the vnode, and try again.
- * flags: bit 1 to specify whether to compute hit statistics. Not
+ * \param flags bit 1 to specify whether to compute hit statistics. Not
* set if FindVCache is called as part of internal bookkeeping.
*
- * Environment:
- * Must be called with the afs_xvcache lock at least held at
- * the read level. In order to do the VLRU adjustment, the xvcache lock
- * must be shared-- we upgrade it here.
+ * \note Environment: Must be called with the afs_xvcache lock at least held at
+ * the read level. In order to do the VLRU adjustment, the xvcache lock
+ * must be shared-- we upgrade it here.
*
- * Return value:
- * number of matches found.
+ * \return Number of matches found.
*/
int afs_duplicate_nfs_fids = 0;
-/*
- * afs_vcacheInit
- *
+/*!
* Initialize vcache related variables
+ *
+ * \param astatSize
*/
void
afs_vcacheInit(int astatSize)
QInit(&afs_vhashTV[i]);
}
-/*
- * shutdown_vcache
- *
+/*!
+ * Shutdown vcache.
*/
void
shutdown_vcache(void)
#endif /* vlserver error base define */
/* Exported variables */
-ino_t volumeInode; /*Inode for VolumeItems file */
-afs_rwlock_t afs_xvolume; /* allocation lock for volumes */
+ino_t volumeInode; /** Inode for VolumeItems file */
+afs_rwlock_t afs_xvolume; /** allocation lock for volumes */
struct volume *afs_freeVolList;
struct volume *afs_volumes[NVOLS];
-afs_int32 afs_volCounter = 1; /* for allocating volume indices */
+afs_int32 afs_volCounter = 1; /** for allocating volume indices */
afs_int32 fvTable[NFENTRIES];
/* Forward declarations */
afs_int32 * cID);
-/* Convert a volume name to a #; return 0 if can't parse as a number */
+
+/**
+ * Convert a volume name to a number;
+ * @param aname Volume name.
+ * @return return 0 if can't parse as a number.
+ */
static int
afs_vtoi(register char *aname)
{
} /*afs_vtoi */
-/*
+/**
* All of the vol cache routines must be called with the afs_xvolume
* lock held in exclusive mode, since they use static variables.
* In addition, we don't want two people adding the same volume
static struct fvolume staticFVolume;
afs_int32 afs_FVIndex = -1;
-/* UFS specific version of afs_GetVolSlot */
-
+/**
+ * UFS specific version of afs_GetVolSlot
+ * @return
+ */
struct volume *
afs_UFSGetVolSlot(void)
{
} /*afs_UFSGetVolSlot */
+/**
+ * Get an available volume list slot. If the list does not exist,
+ * create one containing a single element.
+ * @return
+ */
struct volume *
afs_MemGetVolSlot(void)
{
} /*afs_MemGetVolSlot */
-/* afs_ResetVolumes()
- * Reset volume inforamation for all volume structs that
+/**
+ * Reset volume information for all volume structs that
* point to a speicific server.
+ * @param srvp
*/
void
afs_ResetVolumes(struct server *srvp)
}
-/* reset volume name to volume id mapping cache */
+/**
+ * Reset volume name to volume id mapping cache.
+ * @param flags
+ */
void
afs_CheckVolumeNames(int flags)
{
continue;
}
}
+ /* ??? */
if (flags & (AFS_VOLCHECK_BUSY | AFS_VOLCHECK_FORCE)) {
for (j = 0; j < MAXHOSTS; j++)
tv->status[j] = not_busy;
} /*afs_CheckVolumeNames */
+/**
+ * Check if volume is in the specified list.
+ * @param fid File FID.
+ * @param nvols Nomber of volumes???
+ * @param vID Array of volume IDs.
+ * @param cID Array of cache IDs.
+ * @return 1 - true, 0 - false.
+ */
static int
inVolList(struct VenusFid *fid, afs_int32 nvols, afs_int32 * vID,
afs_int32 * cID)
/* afs_PutVolume is now a macro in afs.h */
-/* afs_FindVolume()
- * return volume struct if we have it cached and it's up-to-date
- *
- * Environment: Must be called with afs_xvolume unlocked.
+/**
+ * Return volume struct if we have it cached and it's up-to-date.
+ * Environment: Must be called with afs_xvolume unlocked.
+ * @param afid Volume FID.
+ * @param locktype
+ * @return Volume or NULL if no result.
*/
struct volume *
afs_FindVolume(struct VenusFid *afid, afs_int32 locktype)
-/*
- * Note that areq may be null, in which case we don't bother to set any
+/**
+ * Note that areq may be null, in which case we don't bother to set any
* request status information.
+ * @param afid Volume FID.
+ * @param areq Request type.
+ * @param locktype Lock to be used.
+ * @return Volume or NULL if no result.
*/
struct volume *
afs_GetVolume(struct VenusFid *afid, struct vrequest *areq,
tv = afs_FindVolume(afid, locktype);
if (!tv) {
+ /* Do a dynroot check and add dynroot volume if found. */
if (afs_IsDynrootAnyFid(afid)) {
tv = afs_NewDynrootVolume(afid);
} else {
+/**
+ *
+ * @param volid Volume ID. If it's 0, get it from the name.
+ * @param aname Volume name.
+ * @param ve Volume entry.
+ * @param tcell The cell containing this volume.
+ * @param agood
+ * @param type Type of volume.
+ * @param areq Request.
+ * @return Volume or NULL if failure.
+ */
static struct volume *
afs_SetupVolume(afs_int32 volid, char *aname, void *ve, struct cell *tcell,
afs_int32 agood, afs_int32 type, struct vrequest *areq)
volid = nve->volumeId[whichType];
} else {
volid = ove->volumeId[whichType];
- }
- }
- }
+ }
+ } /* end of if (volid == 0) */
+ } /* end of if (!volid) */
ObtainWriteLock(&afs_xvolume, 108);
}
+/**
+ * Seek volume by it's name and attributes.
+ * If volume not found, try to add one.
+ * @param aname Volume name.
+ * @param acell Cell
+ * @param agood
+ * @param areq
+ * @param locktype Type of lock to be used.
+ * @return
+ */
struct volume *
afs_GetVolumeByName(register char *aname, afs_int32 acell, int agood,
struct vrequest *areq, afs_int32 locktype)
return (tv);
}
+/**
+ * Init a new dynroot volume.
+ * @param Volume FID.
+ * @return Volume or NULL if not found.
+ */
static struct volume *
afs_NewDynrootVolume(struct VenusFid *fid)
{
}
int lastnvcode;
+
+/**
+ * @param aname Volume name.
+ * @param acell Cell id.
+ * @param agood
+ * @param areq Request type.
+ * @param locktype Type of lock to be used.
+ * @return Volume or NULL if failure.
+ */
static struct volume *
afs_NewVolumeByName(char *aname, afs_int32 acell, int agood,
struct vrequest *areq, afs_int32 locktype)
-/* call this with the volume structure locked; used for new-style vldb requests */
+/**
+ * Call this with the volume structure locked; used for new-style vldb requests.
+ * @param av Volume
+ * @param ve
+ * @param acell
+ */
void
InstallVolumeEntry(struct volume *av, struct vldbentry *ve, int acell)
{
} /*InstallVolumeEntry */
+/**
+ * Reset volume info for the specified volume strecture. Mark volume
+ * to be rechecked next time.
+ * @param tv
+ */
void
afs_ResetVolumeInfo(struct volume *tv)
{
git://git.openafs.org / openafs.git / commitdiff