From 6b0ad5786d09446d6ecf723c892c11d6cce4493c Mon Sep 17 00:00:00 2001 From: Michael Meffie Date: Fri, 27 May 2011 11:29:33 -0400 Subject: [PATCH] volinfo: comments Add doxygen style comment headers. Change-Id: Id8e18a102e8aa5fbb0a0e0f3c58983d93bf2bb50 Reviewed-on: http://gerrit.openafs.org/4738 Tested-by: BuildBot Reviewed-by: Derrick Brashear --- src/vol/vol-info.c | 170 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 144 insertions(+), 26 deletions(-) diff --git a/src/vol/vol-info.c b/src/vol/vol-info.c index f381290209..85b650fd5c 100644 --- a/src/vol/vol-info.c +++ b/src/vol/vol-info.c @@ -93,6 +93,18 @@ void PrintVnode(afs_foff_t offset, VnodeDiskObject * vnode, VnodeId vnodeNumber, Inode ino, Volume * vp); void HandleVnodes(Volume * vp, VnodeClass class); +/** + * Format time as a timestamp string + * + * @param[in] date time value to format + * + * @return timestamp string in the form YYYY/MM/DD.hh:mm:ss + * + * @note A static array of 8 strings are stored by this + * function. The array slots are overwritten, so the + * caller must not reference the returned string after + * seven additional calls to this function. + */ char * date(time_t date) { @@ -108,6 +120,38 @@ date(time_t date) return results[next]; } +#ifdef AFS_NT40_ENV +/** + * Format file time as a timestamp string + * + * @param[in] ft file time + * + * @return timestamp string in the form YYYY/MM/DD.hh:mm:ss + * + * @note A static array of 8 strings are stored by this + * function. The array slots are overwritten, so the + * caller must not reference the returned string after + * seven additional calls to this function. + */ +char * +NT_date(FILETIME * ft) +{ + static char result[8][64]; + static int next = 0; + SYSTEMTIME st; + FILETIME lft; + + if (!FileTimeToLocalFileTime(ft, &lft) + || !FileTimeToSystemTime(&lft, &st)) { + fprintf(stderr, "%s: Time conversion failed.\n", progname); + exit(1); + } + sprintf(result[next = ((next + 1) & 7)], "%4d/%02d/%02d.%2d:%2d:%2d", + st.wYear, st.wMonth, st.wDay, st.wHour, st.wMinute, st.wSecond); + return result[next]; +} +#endif + /** * Print the volume size table heading line, if needed. * @@ -189,6 +233,19 @@ PrintServerTotals(void) serverTotals.vnodesize, serverTotals.size_k, diff_k); } +/** + * Read a volume header file + * + * @param[in] ih ihandle of the header file + * @param[in] to destination + * @param[in] size expected header size + * @param[in] magic expected header magic number + * @param[in] version expected header version number + * + * @return error code + * @retval 0 success + * @retval -1 failed to read file + */ int ReadHdr1(IHandle_t * ih, char *to, int size, u_int magic, u_int version) { @@ -235,7 +292,15 @@ ReadHdr1(IHandle_t * ih, char *to, int size, u_int magic, u_int version) return 0; } - +/** + * Simplified attach volume + * + * param[in] dp vice disk partition object + * param[in] volname volume header file name + * param[in] header volume header object + * + * @return volume object or null on error + */ Volume * AttachVolume(struct DiskPartition64 * dp, char *volname, struct VolumeHeader * header) @@ -283,7 +348,14 @@ AttachVolume(struct DiskPartition64 * dp, char *volname, return vp; } - +/** + * Process command line options and start scanning + * + * @param[in] as command syntax object + * @param[in] arock opaque object; not used + * + * @return error code + */ static int handleit(struct cmd_syndesc *as, void *arock) { @@ -400,6 +472,11 @@ handleit(struct cmd_syndesc *as, void *arock) return 0; } +/** + * Determine if the current directory is a vice partition + * + * @return disk partition object + */ #ifdef AFS_NT40_ENV #include struct DiskPartition64 * @@ -450,6 +527,11 @@ FindCurrentPartition(void) } #endif +/** + * Scan and handle all the partitions detected on this server + * + * @return none + */ void HandleAllPart(void) { @@ -469,7 +551,13 @@ HandleAllPart(void) } } - +/** + * Scan the partition and handle volumes + * + * @param[in] partP disk partition to scan + * + * @return none + */ void HandlePart(struct DiskPartition64 *partP) { @@ -607,6 +695,17 @@ HandleHeaderFiles(struct DiskPartition64 *dp, FD_t header_fd, } } +/** + * Attach and scan the volume and handle the header and vnodes + * + * Print the volume header and vnode information, depending on the + * current modes. + * + * @param[in] dp vice partition object for this volume + * @param[in] name volume header file name + * + * @return none + */ void HandleVolume(struct DiskPartition64 *dp, char *name) { @@ -673,6 +772,9 @@ HandleVolume(struct DiskPartition64 *dp, char *name) free(vp); } +/** + * volinfo program entry + */ int main(int argc, char **argv) { @@ -711,6 +813,13 @@ main(int argc, char **argv) #define typestring(type) (type == RWVOL? "read/write": type == ROVOL? "readonly": type == BACKVOL? "backup": "unknown") +/** + * Print the volume header information + * + * @param[in] volume object + * + * @return none + */ void PrintHeader(Volume * vp) { @@ -749,29 +858,19 @@ PrintHeader(Volume * vp) printf("volUpdateCounter = %u\n", V_volUpCounter(vp)); } -/* GetFileInfo - * OS independent file info. Die on failure. +/** + * Get the size and times of a file + * + * @param[in] fd file descriptor of file to stat + * @param[out] size size of the file + * @param[out] ctime ctime of file as a formatted string + * @param[out] mtime mtime of file as a formatted string + * @param[out] atime atime of file as a formatted string + * + * @return error code + * @retval 0 success + * @retval -1 failed to retrieve file information */ -#ifdef AFS_NT40_ENV -char * -NT_date(FILETIME * ft) -{ - static char result[8][64]; - static int next = 0; - SYSTEMTIME st; - FILETIME lft; - - if (!FileTimeToLocalFileTime(ft, &lft) - || !FileTimeToSystemTime(&lft, &st)) { - fprintf(stderr, "%s: Time conversion failed.\n", progname); - exit(1); - } - sprintf(result[next = ((next + 1) & 7)], "%4d/%02d/%02d.%2d:%2d:%2d", - st.wYear, st.wMonth, st.wDay, st.wHour, st.wMinute, st.wSecond); - return result[next]; -} -#endif - static int GetFileInfo(FD_t fd, afs_sfsize_t * size, char **ctime, char **mtime, char **atime) @@ -812,7 +911,7 @@ GetFileInfo(FD_t fd, afs_sfsize_t * size, char **ctime, char **mtime, * @param[in] vnode vnode object * @param[in] inode inode of the source file * - * @returns none + * @return none */ static void SaveInode(Volume * vp, struct VnodeDiskObject *vnode, Inode ino) @@ -884,6 +983,14 @@ SaveInode(Volume * vp, struct VnodeDiskObject *vnode, Inode ino) PrintInode(NULL, ino), nfile, (unsigned long)total); } +/** + * Scan a volume index and handle each vnode + * + * @param[in] vp volume object + * @param[in] class which index to scan + * + * @return none + */ void HandleVnodes(Volume * vp, VnodeClass class) { @@ -977,6 +1084,17 @@ HandleVnodes(Volume * vp, VnodeClass class) } } +/** + * Print vnode information + * + * @param[in] offset index offset of this vnode + * @param[in] vnode vnode object to be printed + * @param[in] vnodeNumber vnode number + * @param[in] ino fileserver inode number + * @param[in] vp parent volume of the vnode + * + * @return none + */ void PrintVnode(afs_foff_t offset, VnodeDiskObject * vnode, VnodeId vnodeNumber, Inode ino, Volume * vp)