From d919e56b452414ed7923b901d8bfa9fa5d123e2e Mon Sep 17 00:00:00 2001 From: jbj Date: Wed, 23 Aug 2000 13:02:13 +0000 Subject: [PATCH] doxygen annotations. CVS patchset: 4105 CVS date: 2000/08/23 13:02:13 --- lib/install.c | 59 ++++++++++++++++++++++++++++-------------- lib/install.h | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----- lib/misc.c | 2 +- lib/misc.h | 57 +++++++++++++++++++++++++++++++++++++--- lib/package.c | 20 +++++++------- 5 files changed, 179 insertions(+), 42 deletions(-) diff --git a/lib/install.c b/lib/install.c index 1a66e5a..2b8092e 100644 --- a/lib/install.c +++ b/lib/install.c @@ -9,6 +9,9 @@ #include "misc.h" #include +/** + * Private data for cpio callback. + */ struct callbackInfo { unsigned long archiveSize; rpmCallbackFunction notify; @@ -38,9 +41,12 @@ struct fileInfo { } ; /* XXX add more tags */ +/** + * Macros to be defined from per-header tag values. + */ static struct tagMacro { - const char * macroname; - int tag; + const char * macroname; /*!< Macro name to define. */ + int tag; /*!< Header tag to use for value. */ } tagMacros[] = { { "name", RPMTAG_NAME }, { "version", RPMTAG_VERSION }, @@ -51,7 +57,11 @@ static struct tagMacro { { NULL, 0 } }; -/** */ +/** + * Define per-header macros. + * @param h header + * @return 0 always + */ static int rpmInstallLoadMacros(Header h) { struct tagMacro *tagm; @@ -78,7 +88,8 @@ static int rpmInstallLoadMacros(Header h) return 0; } -/** */ +/** + */ static /*@only@*/ struct fileMemory *newFileMemory(void) { struct fileMemory *fileMem = xmalloc(sizeof(*fileMem)); @@ -88,7 +99,8 @@ static /*@only@*/ struct fileMemory *newFileMemory(void) return fileMem; } -/** */ +/** + */ static void freeFileMemory( /*@only@*/ struct fileMemory *fileMem) { if (fileMem->files) free(fileMem->files); @@ -98,7 +110,10 @@ static void freeFileMemory( /*@only@*/ struct fileMemory *fileMem) } /* files should not be preallocated */ -/** */ +/** + * @param h header + * @retval 0 always + */ static int assembleFileList(Header h, /*@out@*/ struct fileMemory ** memPtr, /*@out@*/ int * fileCountPtr, /*@out@*/ struct fileInfo ** filesPtr, int stripPrefixLength, enum fileActions * actions) @@ -153,7 +168,9 @@ static int assembleFileList(Header h, /*@out@*/ struct fileMemory ** memPtr, return 0; } -/** */ +/** + * @param h header + */ static void setFileOwners(Header h, struct fileInfo * files, int fileCount) { char ** fileOwners; @@ -185,7 +202,11 @@ static void setFileOwners(Header h, struct fileInfo * files, int fileCount) free(fileGroups); } -/** */ +/** + * Truncate header changelog tag to configurable limit before installing. + * @param h header + * @return none + */ static void trimChangelog(Header h) { int * times; @@ -236,7 +257,9 @@ static void trimChangelog(Header h) free(texts); } -/** */ +/** + * @param h header + */ static int mergeFiles(Header h, Header newH, enum fileActions * actions) { int i, j, k, fileCount; @@ -493,7 +516,9 @@ static void callback(struct cpioCallbackInfo * cpioInfo, void * data) } /* NULL files means install all files */ -/** */ +/** + * @param h header + */ static int installArchive(FD_t fd, struct fileInfo * files, int fileCount, rpmCallbackFunction notify, void * notifyData, const void * pkgKey, Header h, @@ -601,10 +626,10 @@ static int installArchive(FD_t fd, struct fileInfo * files, return rc; } -/* 0 success */ -/* 1 bad magic */ -/* 2 error */ -/** */ +/** + * @param h header + * @return 0 on success, 1 on bad magic, 2 on error + */ static int installSources(Header h, const char * rootdir, FD_t fd, const char ** specFilePtr, rpmCallbackFunction notify, void * notifyData) @@ -848,9 +873,6 @@ const char *const fileActionString(enum fileActions a) return "???"; } -/* 0 success */ -/* 1 bad magic */ -/* 2 error */ int rpmInstallSourcePackage(const char * rootdir, FD_t fd, const char ** specFile, rpmCallbackFunction notify, void * notifyData, char ** cookie) @@ -884,9 +906,6 @@ int rpmInstallSourcePackage(const char * rootdir, FD_t fd, return rc; } -/* 0 success */ -/* 1 bad magic */ -/* 2 error */ int installBinaryPackage(const char * rootdir, rpmdb db, FD_t fd, Header h, int flags, rpmCallbackFunction notify, void * notifyData, const void * pkgKey, diff --git a/lib/install.h b/lib/install.h index 8f6197d..33d3132 100644 --- a/lib/install.h +++ b/lib/install.h @@ -3,12 +3,16 @@ #include +/** + */ struct sharedFile { int mainFileNumber; int secRecOffset; int secFileNumber; } ; +/** + */ struct sharedFileInfo { int pkgFileNum; int otherFileNum; @@ -16,40 +20,107 @@ struct sharedFileInfo { int isRemoved; }; +/** + */ enum fileActions { FA_UNKNOWN = 0, FA_CREATE, FA_BACKUP, FA_SAVE, FA_SKIP, FA_ALTNAME, FA_REMOVE, FA_SKIPNSTATE, FA_SKIPNETSHARED, FA_SKIPMULTILIB }; + +/** + */ enum fileTypes { XDIR, BDEV, CDEV, SOCK, PIPE, REG, LINK } ; #ifdef __cplusplus extern "C" { #endif +/** + * @param prefix path to top of install tree + * @param h header + * @param scriptTag + * @param progTag + * @param arg + * @param norunScripts + * @param err stderr file handle + */ int runInstScript(const char * prefix, Header h, int scriptTag, int progTag, int arg, int norunScripts, FD_t err); -/* this looks for triggers in the database which h would set off */ -int runTriggers(const char * root, rpmdb db, int sense, Header h, + +/** + * Run trigger scripts in the database that are fired by header. + * @param root path to top of install tree + * @param rpmdb rpm database + * @param sense + * @param h header + * @param countCorrection + * @param scriptFd + */ +int runTriggers(const char * root, rpmdb rpmdb, int sense, Header h, int countCorrection, FD_t scriptFd); + /* while this looks for triggers in h which are set off by things in the db database to calculate arguments to the trigger */ -int runImmedTriggers(const char * root, rpmdb db, int sense, Header h, +/** + * @param root path to top of install tree + * @param rpmdb rpm database + * @param sense + * @param h header + * @param countCorrection + * @param scriptFd + */ +int runImmedTriggers(const char * root, rpmdb rpmdb, int sense, Header h, int countCorrection, FD_t scriptFd); +/** + * Return formatted string representation of file disposition. + * @param a file dispostion + * @return formatted string + */ /*@observer@*/ const char *const fileActionString(enum fileActions a); -int installBinaryPackage(const char * rootdir, rpmdb db, FD_t fd, Header h, +/** + * Install binary package (from transaction set). + * @param rootdir path to top of install tree + * @param rpmdb rpm database + * @param fd package file handle + * @param h package header + * @param flags transaction flags + * @param notify progress callback + * @param notifyData progress callback private data + * @param pkgKey package private data + * @param actions array of file dispositions + * @param sharedList header instances of packages that share files + * @param scriptFd + * @return 0 on success, 1 on bad magic, 2 on error + */ +int installBinaryPackage(const char * rootdir, rpmdb rpmdb, FD_t fd, Header h, int flags, rpmCallbackFunction notify, void * notifyData, const void * pkgKey, enum fileActions * actions, struct sharedFileInfo * sharedList, FD_t scriptFd); -int removeBinaryPackage(const char * root, rpmdb db, unsigned int offset, + +/** + * Erase binary package (from transaction set). + * @param rootdir path to top of install tree + * @param rpmdb rpm database + * @param fd package file handle + * @param offset header instance in rpm database + * @param h package header + * @param flags transaction flags + * @param notify progress callback + * @param notifyData progress callback private data + * @param pkgKey package private data + * @param actions array of file dispositions + * @param scriptFd + * @return + */ +int removeBinaryPackage(const char * rootdir, rpmdb rpmdb, unsigned int offset, Header h, int flags, rpmCallbackFunction notify, void * notifyData, const void * pkgKey, enum fileActions * actions, FD_t scriptFd); - #ifdef __cplusplus } #endif diff --git a/lib/misc.c b/lib/misc.c index 278ff01..040b279 100644 --- a/lib/misc.c +++ b/lib/misc.c @@ -675,7 +675,7 @@ int rpmHeaderGetEntry(Header h, int_32 tag, int_32 *type, /* * XXX Yet Another dressed entry to unify signature/header tag retrieval. */ -int rpmPackageGetEntry(void *leadp, Header sigs, Header h, +int rpmPackageGetEntry( /*@unused@*/ void *leadp, Header sigs, Header h, int_32 tag, int_32 *type, void **p, int_32 *c) { int_32 sigtag; diff --git a/lib/misc.h b/lib/misc.h index a253e38..dda1035 100644 --- a/lib/misc.h +++ b/lib/misc.h @@ -11,31 +11,80 @@ extern "C" { #endif +/** + */ /*@only@*/ char ** splitString(const char * str, int length, char sep); + +/** + */ void freeSplitString( /*@only@*/ char ** list); -void stripTrailingSlashes(char * str); +/** + */ +void stripTrailingSlashes(char * str) /*@modifies *str @*/; + +/** + */ +int rpmfileexists(const char * filespec) /*@*/; + +/** + */ int rpmfileexists(const char * filespec); +/** + */ int rpmvercmp(const char * one, const char * two); /* these are like the normal functions, but they malloc() the space which is needed */ + +/** + */ +int rpmfileexists(const char * filespec); + +/** + */ int dosetenv(const char *name, const char *value, int overwrite); + +/** + */ int doputenv(const char * str); +/** + */ int makeTempFile(const char * prefix, /*@out@*/ const char ** fnptr, /*@out@*/ FD_t * fdptr); -char * currentDirectory(void); /* result needs to be freed */ + +/** + * @return cureent working directory (malloc'ed) + */ +/*@only@*/ char * currentDirectory(void); + +/** + */ void compressFilelist(Header h); + +/** + */ void expandFilelist(Header h); + +/** + */ void buildOrigFileList(Header h, /*@out@*/ const char *** fileListPtr, /*@out@*/ int * fileCountPtr); -int myGlobPatternP (const char *patternURL); +/** + */ +int myGlobPatternP (const char *patternURL) /*@*/; + +/** + */ int rpmGlob(const char * patterns, /*@out@*/ int * argcPtr, - /*@out@*/ const char *** argvPtr); + /*@out@*/ const char *** argvPtr) + /*@modifies *argcPtr, *argvPtr @*/; +/** + */ void providePackageNVR(Header h); #ifdef __cplusplus diff --git a/lib/package.c b/lib/package.c index 4414e48..ec2ba80 100644 --- a/lib/package.c +++ b/lib/package.c @@ -15,18 +15,22 @@ #include "rpmlead.h" #include "signature.h" -/* 0 = success */ -/* 1 = bad magic */ -/* 2 = error */ +/** + * Retrieve package components from file handle. + * @param fd file handle + * @param leadPtr address of lead (or NULL) + * @param sigs address of signatures (or NULL) + * @param hdrPtr address of header (or NULL) + * @return 0 on success, 1 on bad magic, 2 on error + */ static int readPackageHeaders(FD_t fd, /*@out@*/struct rpmlead * leadPtr, /*@out@*/Header * sigs, /*@out@*/Header * hdrPtr) + /*@modifies *leadPtr, *sigs, *hdrPtr @*/ { Header hdrBlock; struct rpmlead leadBlock; Header * hdr = NULL; struct rpmlead * lead; - int_8 arch; - int isSource; char * defaultPrefix; struct stat sb; int_32 true = 1; @@ -122,17 +126,11 @@ static int readPackageHeaders(FD_t fd, /*@out@*/struct rpmlead * leadPtr, return 0; } -/* 0 = success */ -/* 1 = bad magic */ -/* 2 = error */ int rpmReadPackageInfo(FD_t fd, Header * signatures, Header * hdr) { return readPackageHeaders(fd, NULL, signatures, hdr); } -/* 0 = success */ -/* 1 = bad magic */ -/* 2 = error */ int rpmReadPackageHeader(FD_t fd, Header * hdr, int * isSource, int * major, int * minor) { -- 2.7.4