From f8b364d7a88e346412bd2f458b25d1728abaaf5c Mon Sep 17 00:00:00 2001 From: jbj Date: Sun, 27 Aug 2000 19:27:03 +0000 Subject: [PATCH] Doxygen annotations. CVS patchset: 4132 CVS date: 2000/08/27 19:27:03 --- lib/depends.c | 4 + lib/depends.h | 4 + lib/falloc.c | 27 ++- lib/falloc.h | 30 ++- lib/fileutil.c | 4 + lib/formats.c | 4 + lib/fprint.c | 4 + lib/fs.c | 4 + lib/hash.h | 2 +- lib/header.c | 119 ++++++----- lib/header.h | 425 +++++++++++++++++++++++++++++--------- lib/install.c | 4 + lib/install.h | 4 + lib/md5.c | 3 +- lib/md5.h | 4 + lib/md5sum.c | 6 +- lib/misc.c | 4 + lib/misc.h | 4 + lib/oldrpmdb.h | 4 + lib/package.c | 4 + lib/poptBT.c | 3 +- lib/poptQV.c | 4 + lib/problems.c | 4 + lib/query.c | 4 + lib/rpmchecksig.c | 5 +- lib/rpmdb.c | 4 + lib/rpmdb.h | 73 +++---- lib/rpminstall.c | 4 + lib/rpmlead.c | 4 + lib/rpmlead.h | 4 + lib/rpmlib.h | 594 +++++++++++++++++++++++++++++++++--------------------- lib/rpmlibprov.c | 4 + lib/signature.c | 4 + lib/signature.h | 4 +- lib/stringbuf.c | 4 + lib/stringbuf.h | 4 + lib/stubs.c | 4 + lib/tagName.c | 4 + lib/tufdio.c | 4 + lib/uninstall.c | 6 +- lib/verify.c | 4 + 41 files changed, 979 insertions(+), 430 deletions(-) diff --git a/lib/depends.c b/lib/depends.c index a85af91..95e84e7 100644 --- a/lib/depends.c +++ b/lib/depends.c @@ -1,5 +1,9 @@ #include "system.h" +/** \ingroup rpmdep + * \file lib/depends.c + */ + #include #include "depends.h" diff --git a/lib/depends.h b/lib/depends.h index 9bdc0b5..3c1b9af 100644 --- a/lib/depends.h +++ b/lib/depends.h @@ -1,6 +1,10 @@ #ifndef H_DEPENDS #define H_DEPENDS +/** \file lib/depends.h + * + */ + #include /** diff --git a/lib/falloc.c b/lib/falloc.c index ea28a52..c532d86 100644 --- a/lib/falloc.c +++ b/lib/falloc.c @@ -1,21 +1,26 @@ #include "system.h" +/** \ingroup rpmio db1 + * \file lib/falloc.c + * + * The entire file space is thus divided into blocks with a "struct fablock" + * at the header of each. The size fields doubly link this block list. + * + * There is an additional free list weaved through the block list, which + * keeps new allocations fast. + * + * Much of this was inspired by Knuth vol 1. + * + */ + #include #include "falloc.h" -#define FA_MAGIC 0x02050920 - -/* - The entire file space is thus divided into blocks with a "struct fablock" - at the header of each. The size fields doubly link this block list. - - There is an additional free list weaved through the block list, which - keeps new allocations fast. - - Much of this was inspired by Knuth vol 1. +/** \ingroup db1 */ +#define FA_MAGIC 0x02050920 -struct faFileHeader{ +struct faFileHeader { unsigned int magic; unsigned int firstFree; }; diff --git a/lib/falloc.h b/lib/falloc.h index c7c89eb..8468681 100644 --- a/lib/falloc.h +++ b/lib/falloc.h @@ -1,11 +1,16 @@ #ifndef H_FALLOC #define H_FALLOC -/*@access FD_t@*/ +/** \ingroup db1 + * \file lib/falloc.h + * File space allocation routines. + * + * Best fit allocation is used, free blocks are compacted. Minimal + * fragmentation is more important then speed. This uses 32 bit + * offsets on all platforms and should be byte order independent. + */ -/* File space allocation routines. Best fit allocation is used, free blocks - are compacted. Minimal fragmentation is more important then speed. This - uses 32 bit offsets on all platforms and should be byte order independent */ +/*@access FD_t@*/ #ifdef __cplusplus extern "C" { @@ -27,11 +32,28 @@ extern "C" { fd->firstFree = firstFree; } +/** \ingroup db1 + */ /*@null@*/ FD_t fadOpen (const char * path, int flags, mode_t perms); + +/** \ingroup db1 + * @param fd file handle + */ unsigned int fadAlloc (FD_t fd, unsigned int size); /* 0 on failure */ + +/** \ingroup db1 + * @param fd file handle + */ void fadFree (FD_t fd, unsigned int offset); +/** \ingroup db1 + * @param fd file handle + */ int fadFirstOffset (FD_t fd); + +/** \ingroup db1 + * @param fd file handle + */ int fadNextOffset (FD_t fd, unsigned int lastoff); /* 0 at end */ #ifdef __cplusplus diff --git a/lib/fileutil.c b/lib/fileutil.c index b0082d2..2c3aa70 100644 --- a/lib/fileutil.c +++ b/lib/fileutil.c @@ -1,5 +1,9 @@ #include "system.h" +/** + * \file lib/fileutil.c + */ + #include #include "misc.h" diff --git a/lib/formats.c b/lib/formats.c index 5e40f49..cd80667 100644 --- a/lib/formats.c +++ b/lib/formats.c @@ -1,5 +1,9 @@ #include "system.h" +/** \ingroup header + * \file lib/formats.c + */ + #include #include /* XXX for %_i18ndomains */ #include "misc.h" diff --git a/lib/fprint.c b/lib/fprint.c index 3e593f5..65f7059 100644 --- a/lib/fprint.c +++ b/lib/fprint.c @@ -1,5 +1,9 @@ #include "system.h" +/** + * \file lib/fprint.c + */ + #include #include /* XXX for rpmCleanPath */ diff --git a/lib/fs.c b/lib/fs.c index d000e0e..371a0d3 100644 --- a/lib/fs.c +++ b/lib/fs.c @@ -1,5 +1,9 @@ #include "system.h" +/** + * \file lib/fs.c + */ + #include #include diff --git a/lib/hash.h b/lib/hash.h index eeebae7..0cd98e0 100644 --- a/lib/hash.h +++ b/lib/hash.h @@ -2,7 +2,7 @@ #define H_HASH /** \file lib/hash.h - * Hash table implemenation + * Hash table implemenation. */ typedef struct hashTable_s * hashTable; diff --git a/lib/header.c b/lib/header.c index 37a4cf8..a7cb09c 100644 --- a/lib/header.c +++ b/lib/header.c @@ -1,8 +1,9 @@ -/* RPM - Copyright (C) 1995 Red Hat Software - * - * header.c - routines for managing rpm headers +/** \ingroup header + * \file lib/header.c */ +/* RPM - Copyright (C) 1995 Red Hat Software */ + /* Data written to file descriptors is in network byte order. */ /* Data read from file descriptors is expected to be in */ /* network byte order and is converted on the fly to host order. */ @@ -40,7 +41,8 @@ static int typeSizes[] = { /* RPM_STRING_TYPE */ -1, /* RPM_BIN_TYPE */ 1, /* RPM_STRING_ARRAY_TYPE */ -1, - /* RPM_I18NSTRING_TYPE */ -1 }; + /* RPM_I18NSTRING_TYPE */ -1 +}; struct headerToken { struct indexEntry *index; @@ -48,7 +50,7 @@ struct headerToken { int indexAlloced; int sorted; - /*@refs@*/ int usageCount; +/*@refs@*/ int usageCount; }; struct entryInfo { @@ -61,7 +63,7 @@ struct entryInfo { struct indexEntry { struct entryInfo info; - /*@owned@*/ void * data; +/*@owned@*/ void * data; int length; /* Computable, but why bother? */ }; @@ -72,8 +74,8 @@ struct sprintfTag { int_32 tag; int justOne; int arrayCount; - char * format; - char * type; +/*@kept@*/ char * format; +/*@kept@*/ char * type; int pad; }; @@ -82,7 +84,7 @@ struct extensionCache { int_32 count; int avail; int freeit; - const void * data; +/*@owned@*/ const void * data; }; struct sprintfToken { @@ -155,8 +157,9 @@ static void headerProbe(Header h, const char *msg) #define HEADERPROBE(_h, _msg) #endif /* HAVE_MCHECK_H */ -static void copyEntry(struct indexEntry * entry, /*@out@*/ int_32 * type, +static void copyEntry(const struct indexEntry * entry, /*@out@*/ int_32 * type, /*@out@*/ void ** p, /*@out@*/ int_32 * c, int minimizeMemory) + /*@modifies *type, *p, *c @*/ { int i, tableSize; char ** ptrEntry; @@ -203,6 +206,7 @@ static void copyEntry(struct indexEntry * entry, /*@out@*/ int_32 * type, } static int dataLength(int_32 type, const void * p, int_32 count, int onDisk) + /*@*/ { int thisLen, length, i; char ** src, * chptr; @@ -303,7 +307,7 @@ int headerNextIterator(HeaderIterator iter, return 1; } -static int indexCmp(const void *ap, const void *bp) +static int indexCmp(const void *ap, const void *bp) /*@*/ { int_32 a = ((const struct indexEntry *)ap)->info.tag; int_32 b = ((const struct indexEntry *)bp)->info.tag; @@ -427,6 +431,7 @@ Header headerLoad(void *pv) } static void *doHeaderUnload(Header h, /*@out@*/int * lengthPtr) + /*@modifies h, *lengthPtr @*/ { int i; int type, diff; @@ -735,6 +740,7 @@ void headerDump(Header h, FILE *f, int flags, /********************************************************************/ static struct indexEntry *findEntry(Header h, int_32 tag, int_32 type) + /*@modifies h @*/ { struct indexEntry * entry, * entry2, * last; struct indexEntry key; @@ -792,6 +798,7 @@ int headerGetRawEntry(Header h, int_32 tag, int_32 *type, void **p, int_32 *c) } static int headerMatchLocale(const char *td, const char *l, const char *le) + /*@*/ { const char *fe; @@ -909,6 +916,7 @@ headerFindI18NString(Header h, struct indexEntry *entry) static int intGetEntry(Header h, int_32 tag, /*@out@*/ int_32 *type, /*@out@*/ void **p, /*@out@*/ int_32 *c, int minMem) + /*@modifies h, *type, *p, *c @*/ { struct indexEntry * entry; char * chptr; @@ -928,7 +936,7 @@ static int intGetEntry(Header h, int_32 tag, /*@out@*/ int_32 *type, if (type) *type = RPM_STRING_TYPE; if (c) *c = 1; - *p = chptr; + /*@-dependenttrans@*/ *p = chptr; /*@=dependenttrans@*/ } else { copyEntry(entry, type, p, c, minMem); } @@ -983,7 +991,7 @@ Header headerLink(Header h) { HEADERPROBE(h, "headerLink"); h->usageCount++; - return h; + /*@-refcounttrans@*/ return h; /*@=refcounttrans@*/ } int headerUsageCount(Header h) @@ -1020,8 +1028,9 @@ unsigned int headerSizeof(Header h, int magicp) return size; } -static void copyData(int_32 type, /*@out@*/void * dstPtr, const void * srcPtr, int_32 c, - int dataLength) +static void copyData(int_32 type, /*@out@*/ void * dstPtr, const void * srcPtr, + int_32 c, int dataLength) + /*@modifies *dstPtr @*/ { const char ** src; char * dst; @@ -1048,7 +1057,9 @@ static void copyData(int_32 type, /*@out@*/void * dstPtr, const void * srcPtr, i } } -static void * grabData(int_32 type, const void * p, int_32 c, int * lengthPtr) +static void * grabData(int_32 type, const void * p, int_32 c, + /*@out@*/ int * lengthPtr) + /*@modifies *lengthPtr @*/ { int length; void * data; @@ -1138,7 +1149,7 @@ int headerAddI18NString(Header h, int_32 tag, const char * string, const char * return 0; /* this shouldn't ever happen!! */ if (!table && !entry) { - const char * charArray[2]; + errmsg_t charArray[2]; int count = 0; if (!lang || (lang[0] == 'C' && lang[1] == '\0')) { charArray[count++] = "C"; @@ -1287,7 +1298,7 @@ int headerAppendEntry(Header h, int_32 tag, int_32 type, void * p, int_32 c) entry->info.count += c; - return 0; + return 1; } int headerRemoveEntry(Header h, int_32 tag) @@ -1322,7 +1333,7 @@ int headerRemoveEntry(Header h, int_32 tag) return 0; } -static char escapedChar(const char ch) +static char escapedChar(const char ch) /*@*/ { switch (ch) { case 'a': return '\a'; @@ -1365,6 +1376,7 @@ static void findTag(char * name, const struct headerTagTableEntry * tags, const struct headerSprintfExtension * extensions, /*@out@*/const struct headerTagTableEntry ** tagMatch, /*@out@*/const struct headerSprintfExtension ** extMatch) + /*@modifies *tagMatch, *extMatch @*/ { const struct headerTagTableEntry * entry; const struct headerSprintfExtension * ext; @@ -1412,12 +1424,14 @@ static void findTag(char * name, const struct headerTagTableEntry * tags, static int parseExpression(struct sprintfToken * token, char * str, const struct headerTagTableEntry * tags, const struct headerSprintfExtension * extensions, - /*@out@*/char ** endPtr, /*@out@*/const char ** error); + /*@out@*/char ** endPtr, /*@out@*/ errmsg_t * errmsg) + /*@modifies str, *str, *token, *endPtr, *errmsg @*/; static int parseFormat(char * str, const struct headerTagTableEntry * tags, const struct headerSprintfExtension * extensions, /*@out@*/struct sprintfToken ** formatPtr, /*@out@*/int * numTokensPtr, - /*@out@*/char ** endPtr, int state, /*@out@*/const char ** error) + /*@out@*/char ** endPtr, int state, /*@out@*/ errmsg_t * errmsg) + /*@modifies str, *str, *formatPtr, *numTokensPtr, *endPtr, *errmsg @*/ { char * chptr, * start, * next, * dst; struct sprintfToken * format; @@ -1439,7 +1453,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags, dst = start = str; currToken = -1; - while (*start && !done) { + while (*start) { switch (*start) { case '%': /* handle %% */ @@ -1466,7 +1480,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags, start++; if (parseExpression(format + currToken, start, tags, - extensions, &newEnd, error)) { + extensions, &newEnd, errmsg)) { freeFormat(format, numTokens); return 1; } @@ -1482,7 +1496,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags, chptr = start; while (*chptr && *chptr != '{' && *chptr != '%') chptr++; if (!*chptr || *chptr == '%') { - *error = _("missing { after %"); + *errmsg = _("missing { after %"); freeFormat(format, numTokens); return 1; } @@ -1510,7 +1524,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags, next = start; while (*next && *next != '}') next++; if (!*next) { - *error = _("missing } after %{"); + *errmsg = _("missing } after %{"); freeFormat(format, numTokens); return 1; } @@ -1522,7 +1536,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags, if (*chptr) { *chptr++ = '\0'; if (!*chptr) { - *error = _("empty tag format"); + *errmsg = _("empty tag format"); freeFormat(format, numTokens); return 1; } @@ -1532,7 +1546,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags, } if (!*start) { - *error = _("empty tag name"); + *errmsg = _("empty tag name"); freeFormat(format, numTokens); return 1; } @@ -1547,7 +1561,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags, format[currToken].u.tag.ext = ext->u.tagFunction; format[currToken].u.tag.extNum = ext - extensions; } else { - *error = _("unknown tag"); + *errmsg = _("unknown tag"); freeFormat(format, numTokens); return 1; } @@ -1566,13 +1580,13 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags, if (parseFormat(start, tags, extensions, &format[currToken].u.array.format, &format[currToken].u.array.numTokens, - &start, PARSER_IN_ARRAY, error)) { + &start, PARSER_IN_ARRAY, errmsg)) { freeFormat(format, numTokens); return 1; } if (!start) { - *error = _("] expected at end of array"); + *errmsg = _("] expected at end of array"); freeFormat(format, numTokens); return 1; } @@ -1588,9 +1602,9 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags, if ((*start == ']' && state != PARSER_IN_ARRAY) || (*start == '}' && state != PARSER_IN_EXPR)) { if (*start == ']') - *error = _("unexpected ]"); + *errmsg = _("unexpected ]"); else - *error = _("unexpected }"); + *errmsg = _("unexpected }"); freeFormat(format, numTokens); return 1; } @@ -1614,6 +1628,8 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags, } break; } + if (done) + break; } *dst = '\0'; @@ -1633,37 +1649,38 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags, static int parseExpression(struct sprintfToken * token, char * str, const struct headerTagTableEntry * tags, const struct headerSprintfExtension * extensions, - /*@out@*/ char ** endPtr, /*@out@*/ const char ** error) + /*@out@*/ char ** endPtr, /*@out@*/ errmsg_t * errmsg) + /*@modifies str, *str, *token, *endPtr, *errmsg @*/ { const struct headerTagTableEntry * tag; const struct headerSprintfExtension * ext; char * chptr; char * end; - *error = NULL; + *errmsg = NULL; chptr = str; while (*chptr && *chptr != '?') chptr++; if (*chptr != '?') { - *error = _("? expected in expression"); + *errmsg = _("? expected in expression"); return 1; } *chptr++ = '\0';; if (*chptr != '{') { - *error = _("{ expected after ? in expression"); + *errmsg = _("{ expected after ? in expression"); return 1; } chptr++; if (parseFormat(chptr, tags, extensions, &token->u.cond.ifFormat, - &token->u.cond.numIfTokens, &end, PARSER_IN_EXPR, error)) + &token->u.cond.numIfTokens, &end, PARSER_IN_EXPR, errmsg)) return 1; if (!*end) { - *error = _("} expected in expression"); + *errmsg = _("} expected in expression"); freeFormat(token->u.cond.ifFormat, token->u.cond.numIfTokens); token->u.cond.ifFormat = NULL; return 1; @@ -1671,7 +1688,7 @@ static int parseExpression(struct sprintfToken * token, char * str, chptr = end; if (*chptr != ':' && *chptr != '|') { - *error = _(": expected following ? subexpression"); + *errmsg = _(": expected following ? subexpression"); freeFormat(token->u.cond.ifFormat, token->u.cond.numIfTokens); token->u.cond.ifFormat = NULL; return 1; @@ -1680,12 +1697,12 @@ static int parseExpression(struct sprintfToken * token, char * str, if (*chptr == '|') { parseFormat(xstrdup(""), tags, extensions, &token->u.cond.elseFormat, &token->u.cond.numElseTokens, &end, PARSER_IN_EXPR, - error); + errmsg); } else { chptr++; if (*chptr != '{') { - *error = _("{ expected after : in expression"); + *errmsg = _("{ expected after : in expression"); freeFormat(token->u.cond.ifFormat, token->u.cond.numIfTokens); token->u.cond.ifFormat = NULL; return 1; @@ -1695,10 +1712,10 @@ static int parseExpression(struct sprintfToken * token, char * str, if (parseFormat(chptr, tags, extensions, &token->u.cond.elseFormat, &token->u.cond.numElseTokens, &end, PARSER_IN_EXPR, - error)) + errmsg)) return 1; if (!*end) { - *error = _("} expected in expression"); + *errmsg = _("} expected in expression"); freeFormat(token->u.cond.ifFormat, token->u.cond.numIfTokens); token->u.cond.ifFormat = NULL; return 1; @@ -1706,7 +1723,7 @@ static int parseExpression(struct sprintfToken * token, char * str, chptr = end; if (*chptr != '|') { - *error = _("| expected at end of expression"); + *errmsg = _("| expected at end of expression"); freeFormat(token->u.cond.ifFormat, token->u.cond.numIfTokens); token->u.cond.ifFormat = NULL; freeFormat(token->u.cond.elseFormat, token->u.cond.numElseTokens); @@ -1740,6 +1757,7 @@ static int parseExpression(struct sprintfToken * token, char * str, static int getExtension(Header h, headerTagTagFunction fn, /*@out@*/ int_32 * typeptr, /*@out@*/ const void ** data, /*@out@*/ int_32 * countptr, struct extensionCache * ext) + /*@modifies *typeptr, *data, *countptr, ext->avail @*/ { if (!ext->avail) { if (fn(h, &ext->type, &ext->data, &ext->count, &ext->freeit)) @@ -1757,6 +1775,7 @@ static int getExtension(Header h, headerTagTagFunction fn, static char * formatValue(struct sprintfTag * tag, Header h, const struct headerSprintfExtension * extensions, struct extensionCache * extCache, int element) + /*@modifies h, extCache->avail @*/ { int len; char buf[20]; @@ -1881,6 +1900,7 @@ static char * formatValue(struct sprintfTag * tag, Header h, static const char * singleSprintf(Header h, struct sprintfToken * token, const struct headerSprintfExtension * extensions, struct extensionCache * extCache, int element) + /*@modifies h, extCache->avail @*/ { char * val; const char * thisItem; @@ -1993,6 +2013,7 @@ static const char * singleSprintf(Header h, struct sprintfToken * token, static struct extensionCache * allocateExtensionCache( const struct headerSprintfExtension * extensions) + /*@*/ { const struct headerSprintfExtension * ext = extensions; int i = 0; @@ -2030,7 +2051,7 @@ static void freeExtensionCache(const struct headerSprintfExtension * extensions, char * headerSprintf(Header h, const char * origFmt, const struct headerTagTableEntry * tags, const struct headerSprintfExtension * extensions, - const char ** error) + errmsg_t * errmsg) { char * fmtString; struct sprintfToken * format; @@ -2045,7 +2066,7 @@ char * headerSprintf(Header h, const char * origFmt, fmtString = xstrdup(origFmt); if (parseFormat(fmtString, tags, extensions, &format, &numTokens, - NULL, PARSER_BEGIN, error)) { + NULL, PARSER_BEGIN, errmsg)) { free(fmtString); return NULL; } @@ -2085,6 +2106,7 @@ char * headerSprintf(Header h, const char * origFmt, static char * octalFormat(int_32 type, const void * data, char * formatPrefix, int padding, /*@unused@*/int element) + /*@modifies formatPrefix @*/ { char * val; @@ -2101,6 +2123,7 @@ static char * octalFormat(int_32 type, const void * data, static char * hexFormat(int_32 type, const void * data, char * formatPrefix, int padding, /*@unused@*/int element) + /*@modifies formatPrefix @*/ { char * val; @@ -2118,6 +2141,7 @@ static char * hexFormat(int_32 type, const void * data, static char * realDateFormat(int_32 type, const void * data, char * formatPrefix, int padding, /*@unused@*/int element, char * strftimeFormat) + /*@modifies formatPrefix @*/ { char * val; struct tm * tstruct; @@ -2142,12 +2166,14 @@ static char * realDateFormat(int_32 type, const void * data, static char * dateFormat(int_32 type, const void * data, char * formatPrefix, int padding, int element) + /*@modifies formatPrefix @*/ { return realDateFormat(type, data, formatPrefix, padding, element, "%c"); } static char * dayFormat(int_32 type, const void * data, char * formatPrefix, int padding, int element) + /*@modifies formatPrefix @*/ { return realDateFormat(type, data, formatPrefix, padding, element, "%a %b %d %Y"); @@ -2155,6 +2181,7 @@ static char * dayFormat(int_32 type, const void * data, static char * shescapeFormat(int_32 type, const void * data, char * formatPrefix, int padding, /*@unused@*/int element) + /*@modifies formatPrefix @*/ { char * result, * dst, * src, * buf; diff --git a/lib/header.h b/lib/header.h index 2c049ac..029e1ff 100644 --- a/lib/header.h +++ b/lib/header.h @@ -1,12 +1,14 @@ -/* RPM - Copyright (C) 1995 Red Hat Software +#ifndef H_HEADER +#define H_HEADER + +/** \file lib/header.h * - * header.h - routines for managing rpm tagged structures */ +/* RPM - Copyright (C) 1995 Red Hat Software */ + /* WARNING: 1 means success, 0 means failure (yes, this is backwards) */ -#ifndef H_HEADER -#define H_HEADER #include #include @@ -39,134 +41,377 @@ typedef unsigned short uint_16; typedef /*@abstract@*/ /*@refcounted@*/ struct headerToken *Header; typedef /*@abstract@*/ struct headerIteratorS *HeaderIterator; +/** \ingroup header + * Associate tag names with numeric values. + */ struct headerTagTableEntry { - const char * name; - int val; + const char * name; /*!< Tag name. */ + int val; /*!< Tag numeric value. */ }; -enum headerSprintfExtenstionType { HEADER_EXT_LAST = 0, HEADER_EXT_FORMAT, - HEADER_EXT_MORE, HEADER_EXT_TAG }; +/** \ingroup header + */ +enum headerSprintfExtenstionType { + HEADER_EXT_LAST = 0, /*!< End of extension chain. */ + HEADER_EXT_FORMAT, /*!< headerTagFormatFunction() extension */ + HEADER_EXT_MORE, /*!< Chain to next table. */ + HEADER_EXT_TAG /*!< headerTagTagFunction() extension */ +}; -/* This will only ever be passed RPM_TYPE_INT32 or RPM_TYPE_STRING to - help keep things simple */ -typedef char * (*headerTagFormatFunction)(int_32 type, const void * data, - char * formatPrefix, - int padding, int element); -/* This is allowed to fail, which indicates the tag doesn't exist */ +/** \ingroup header + * HEADER_EXT_TAG format function prototype. + * This will only ever be passed RPM_TYPE_INT32 or RPM_TYPE_STRING to + * help keep things simple + * + * @param type tag type + * @param data tag value + * @param formatPrefix + * @param padding + * @param element + * @return formatted string + */ +typedef /*only@*/ char * (*headerTagFormatFunction)(int_32 type, + const void * data, char * formatPrefix, + int padding, int element); +/** \ingroup header + * HEADER_EXT_FORMAT format function prototype. + * This is allowed to fail, which indicates the tag doesn't exist. + * + * @param h header + * @retval type address of tag type + * @retval data address of tag value pointer + * @retval count address of no. of data items + * @retval freedata address of data-was-malloc'ed indicator + * @return 0 on success + */ typedef int (*headerTagTagFunction)(Header h, int_32 * type, const void ** data, int_32 * count, int * freeData); +/** \ingroup header + * Define header tag output formats. + */ struct headerSprintfExtension { - enum headerSprintfExtenstionType type; - char * name; + enum headerSprintfExtenstionType type; /*!< Type of extension. */ + char * name; /*!< Name of extension. */ union { - void * generic; - headerTagFormatFunction formatFunction; - headerTagTagFunction tagFunction; - struct headerSprintfExtension * more; + void * generic; /*!< Private extension. */ + headerTagFormatFunction formatFunction; /*!< HEADER_EXT_TAG extension. */ + headerTagTagFunction tagFunction; /*!< HEADER_EXT_FORMAT extension. */ + struct headerSprintfExtension * more; /*!< Chained table extension. */ } u; }; -/* This defines some basic conversions all header users would probably like - to have */ +/** \ingroup header + * Supported default header tag output formats. + */ extern const struct headerSprintfExtension headerDefaultFormats[]; -/* read and write a header from a file */ -Header headerRead(FD_t fd, int magicp); -int headerWrite(FD_t fd, Header h, int magicp); -Header headerGzRead(FD_t fd, int magicp); -int headerGzWrite(FD_t fd, Header h, int magicp); -unsigned int headerSizeof(Header h, int magicp); +/** \ingroup header + * Read (and load) header from file handle. + * @param fd file handle + * @param magicp + * @return header + */ +Header headerRead(FD_t fd, int magicp) /*@modifies fd @*/; + +/** \ingroup header + * Write (with unload) header to file handle. + * @param fd file handle + * @param h header + * @param magicp + * @return + */ +int headerWrite(FD_t fd, Header h, int magicp) /*@modifies fd, h @*/; + +/** \ingroup header + * Return size of on-disk header representation in bytes. + */ +unsigned int headerSizeof(Header h, int magicp) + /*@modifies h @*/; #define HEADER_MAGIC_NO 0 #define HEADER_MAGIC_YES 1 -/* load and unload a header from a chunk of memory */ -Header headerLoad(void *p); -void *headerUnload(Header h); +/** \ingroup header + * Convert header to in-memory representation. + * @param p on-disk header (with offsets) + * @return header (with pointers) + */ +Header headerLoad(void *p) /*@*/; + +/** \ingroup header + * Convert header to on-disk representation. + * @param h header (with pointers) + * @return on-disk header (with offsets) + */ +void *headerUnload(Header h) + /*@modifes h @*/; + +/** \ingroup header + * Create new (empty) header instance. + * @return header + */ +Header headerNew(void) /*@*/; + +/** \ingroup header + * Reference a header instance. + * @param h header + * @return referenced header instance + */ +Header headerLink(Header h) /*@modifies h @*/; -Header headerNew(void); +/** \ingroup header + * Dereference a header instance. + * @param h header + */ void headerFree( /*@killref@*/ Header h); -/* dump a header to a file, in human readable format */ +/** \ingroup header + * Return header reference count. + * @param h header + * @return no. of references + */ +int headerUsageCount(Header h) /*@*/; + +/** \ingroup header + * Dump a header in human readable format (for debugging). + * @param h header + * @param flags 0 or HEADER_DUMP_LINLINE + * @param tags array of tag name/value pairs + */ void headerDump(Header h, FILE *f, int flags, const struct headerTagTableEntry * tags); +#define HEADER_DUMP_INLINE 1 -/* the returned string must be free()d */ -char * headerSprintf(Header h, const char * fmt, +typedef /*@observer@*/ const char * errmsg_t; + +/** \ingroup header + * Return formatted output string from header tags. + * The returned string must be free()d. + * + * @param h header + * @param fmt format to use + * @param tags array of tag name/value pairs + * @param extentions chained table of formatting extensions. + * @retval errmsg error message (if any) + * @return formatted output string (malloc'ed) + */ +/*@only@*/ char * headerSprintf(Header h, const char * fmt, const struct headerTagTableEntry * tags, const struct headerSprintfExtension * extentions, - /*@out@*/ const char ** error); + /*@out@*/ errmsg_t * errmsg) + /*@modifies h, *errmsg @*/; + +/** \ingroup header + * Add tag to header. + * Duplicate tags are okay, but only defined for iteration (with the + * exceptions noted below). While you are allowed to add i18n string + * arrays through this function, you probably don't mean to. See + * headerAddI18NString() instead. + * + * @param h header + * @param tag tag + * @param type tag value data type + * @param p pointer to tag value(s) + * @param c number of values + * @return 1 on success, 0 on failure + */ +int headerAddEntry(Header h, int_32 tag, int_32 type, const void *p, int_32 c) + /*@modifies h @*/; + +/** \ingroup header + * Modify tag in header. + * If there are multiple entries with this tag, the first one gets replaced. + * @param h header + * @param tag tag + * @param type tag value data type + * @param p pointer to tag value(s) + * @param c number of values + * @return 1 on success, 0 on failure + */ +int headerModifyEntry(Header h, int_32 tag, int_32 type, void *p, int_32 c) + /*@modifies h @*/; -#define HEADER_DUMP_INLINE 1 +/** \ingroup header + * Return array of locales found in header. + * @param h header + * @return array of locales + */ +char ** headerGetLangs(Header h) + /*@modifies h @*/; -/* Duplicate tags are okay, but only defined for iteration (with the - exceptions noted below). While you are allowed to add i18n string - arrays through this function, you probably don't mean to. See - headerAddI18NString() instead */ -int headerAddEntry(Header h, int_32 tag, int_32 type, const void *p, int_32 c); -/* if there are multiple entries with this tag, the first one gets replaced */ -int headerModifyEntry(Header h, int_32 tag, int_32 type, void *p, int_32 c); - -/* Return array of lang names */ -char **headerGetLangs(Header h); - -/* A NULL lang is interpreted as the C locale. Here are the rules: - - 1) If the tag isn't in the Header, it's added with the passed string - as a version. - 2) If the tag occurs multiple times in entry, which tag is affected - by the operation is undefined. - 2) If the tag is in the header w/ this language, the entry is - *replaced* (like headerModifyEntry()). - - This function is intended to just "do the right thing". If you need - more fine grained control use headerAddEntry() and headerModifyEntry() - but be careful! -*/ +/** \ingroup header + * Add locale specific tag to header. + * A NULL lang is interpreted as the C locale. Here are the rules: + * + * 1) If the tag isn't in the Header, it's added with the passed string + * as a version. + * 2) If the tag occurs multiple times in entry, which tag is affected + * by the operation is undefined. + * 2) If the tag is in the header w/ this language, the entry is + * *replaced* (like headerModifyEntry()). + * + * This function is intended to just "do the right thing". If you need + * more fine grained control use headerAddEntry() and headerModifyEntry(). + * + * @param h header + * @param tag tag + * @param string tag value + * @param lang locale + * @return 1 on success, 0 on failure + */ int headerAddI18NString(Header h, int_32 tag, const char * string, - const char * lang); - -/* Appends item p to entry w/ tag and type as passed. Won't work on - RPM_STRING_TYPE. Any pointers from headerGetEntry() for this entry - are invalid after this call has been made! */ -int headerAppendEntry(Header h, int_32 tag, int_32 type, void * p, int_32 c); + const char * lang) + /*@modifies h @*/; + +/** \ingroup header + * Append element to tag array in header. + * Appends item p to entry w/ tag and type as passed. Won't work on + * RPM_STRING_TYPE. Any pointers from headerGetEntry() for this entry + * are invalid after this call has been made! + * + * @param h header + * @param tag tag + * @param type tag value data type + * @param p pointer to tag value(s) + * @param c number of values + * @return 1 on success, 0 on failure + */ +int headerAppendEntry(Header h, int_32 tag, int_32 type, void * p, int_32 c) + /*@modifies h @*/; + +/** \ingroup header + * Add or append element to tag array in header. + * @param h header + * @param tag tag + * @param type tag value data type + * @param p pointer to tag value(s) + * @param c number of values + * @return 1 on success, 0 on failure + */ int headerAddOrAppendEntry(Header h, int_32 tag, int_32 type, - void * p, int_32 c); - -/* Will never return RPM_I18NSTRING_TYPE! RPM_STRING_TYPE elements w/ - RPM_I18NSTRING_TYPE equivalent enreies are translated (if HEADER_I18NTABLE - entry is present). */ + void * p, int_32 c) + /*@modifies h @*/; + +/** \ingroup header + * Retrieve tag value. + * Will never return RPM_I18NSTRING_TYPE! RPM_STRING_TYPE elements with + * RPM_I18NSTRING_TYPE equivalent entries are translated (if HEADER_I18NTABLE + * entry is present). + * + * @param h header + * @param tag tag + * @retval type address of tag value data type + * @retval p address of pointer to tag value(s) + * @retval c address of number of values + * @return 1 on success, 0 on failure + */ int headerGetEntry(Header h, int_32 tag, /*@out@*/ int_32 *type, - /*@out@*/ void **p, /*@out@*/int_32 *c); + /*@out@*/ void **p, /*@out@*/int_32 *c) + /*@modifies h, *type, *p, *c @*/; -/* This gets an entry, and uses as little extra RAM as possible to represent - it (this is only an issue for RPM_STRING_ARRAY_TYPE. */ +/** \ingroup header + * Retrieve tag value using header internal array. + * Get an entry using as little extra RAM as possible to return the tag value. + * This is only an issue for RPM_STRING_ARRAY_TYPE. + * + * @param h header + * @param tag tag + * @retval type address of tag value data type + * @retval p address of pointer to tag value(s) + * @retval c address of number of values + * @return 1 on success, 0 on failure + */ int headerGetEntryMinMemory(Header h, int_32 tag, int_32 *type, - /*@out@*/ void **p, /*@out@*/ int_32 *c); + /*@out@*/ void **p, /*@out@*/ int_32 *c) + /*@modifies h, *type, *p, *c @*/; -/* If *type is RPM_NULL_TYPE any type will match, otherwise only *type will - match. */ +/** \ingroup header + * Retrieve tag value with type match. + * If *type is RPM_NULL_TYPE any type will match, otherwise only *type will + * match. + * + * @param h header + * @param tag tag + * @retval type address of tag value data type + * @retval p address of pointer to tag value(s) + * @retval c address of number of values + * @return 1 on success, 0 on failure + */ int headerGetRawEntry(Header h, int_32 tag, /*@out@*/ int_32 *type, - /*@out@*/ void **p, /*@out@*/ int_32 *c); + /*@out@*/ void **p, /*@out@*/ int_32 *c) + /*@modifies h, *type, *p, *c @*/; + +/** \ingroup header + * Check if tag is in header. + * @param h header + * @return 1 on success, 0 on failure + */ +int headerIsEntry(Header h, int_32 tag) + /*@modifies h @*/; -int headerIsEntry(Header h, int_32 tag); -/* removes all entries of type tag from the header, returns 1 if none were - found */ -int headerRemoveEntry(Header h, int_32 tag); +/** \ingroup header + * Delete tag in header. + * Removes all entries of type tag from the header, returns 1 if none were + * found. + * + * @param h header + * @return 0 on success, 1 on failure (INCONSISTENT) + */ +int headerRemoveEntry(Header h, int_32 tag) + /*@modifies h @*/; -HeaderIterator headerInitIterator(Header h); +/** \ingroup header + * Create header tag iterator. + * @param h header + * @return header tag iterator + */ +HeaderIterator headerInitIterator(Header h) + /*@modifies h @*/; + +/** \ingroup header + * Return next tag from header. + * @param iter header tag iterator + * @retval tag address of tag + * @retval type address of tag value data type + * @retval p address of pointer to tag value(s) + * @retval c address of number of values + * @return 1 on success, 0 on failure + */ int headerNextIterator(HeaderIterator iter, /*@out@*/ int_32 *tag, /*@out@*/ int_32 *type, /*@out@*/ void **p, - /*@out@*/ int_32 *c); + /*@out@*/ int_32 *c) + /*@modifies iter, *tag, *type, *p, *c @*/; + +/** \ingroup header + * Destroy header tag iterator. + * @param iter header tag iterator + */ void headerFreeIterator( /*@only@*/ HeaderIterator iter); -Header headerCopy(Header h); -void headerSort(Header h); -Header headerLink(Header h); -int headerUsageCount(Header h); +/** \ingroup header + * Duplicate a header. + * @param h header + * @return new header instance + */ +Header headerCopy(Header h) + /*@modifies h @*/; -void headerCopyTags(Header headerFrom, Header headerTo, int_32 *tagstocopy); +/** \ingroup header + * Sort tags in header. + * @param h header + */ +void headerSort(Header h) + /*@modifies h @*/; + +/** \ingroup header + * Duplicate tag values from one header into another. + * @param headerFrom source header + * @param headerTo destination header + * @param tagstocopy array of tags that are copied + */ +void headerCopyTags(Header headerFrom, Header headerTo, int_32 *tagstocopy) + /*@modifies headerFrom, headerTo @*/; /* Entry Types */ diff --git a/lib/install.c b/lib/install.c index 2b8092e..499b55d 100644 --- a/lib/install.c +++ b/lib/install.c @@ -1,3 +1,7 @@ +/** \ingroup rpmtrans payload + * \file lib/install.c + */ + #include "system.h" #include diff --git a/lib/install.h b/lib/install.h index 33d3132..b3f61b9 100644 --- a/lib/install.h +++ b/lib/install.h @@ -1,6 +1,10 @@ #ifndef H_INSTALL #define H_INSTALL +/** \file lib/install.h + * + */ + #include /** diff --git a/lib/md5.c b/lib/md5.c index 27d2a54..92f1ff2 100644 --- a/lib/md5.c +++ b/lib/md5.c @@ -1,4 +1,5 @@ -/* +/** \ingroup signature + * \file lib/md5.c * This code implements the MD5 message-digest algorithm. * The algorithm is due to Ron Rivest. This code was * written by Colin Plumb in 1993, no copyright is claimed. diff --git a/lib/md5.h b/lib/md5.h index 45c28a2..8ef18ea 100644 --- a/lib/md5.h +++ b/lib/md5.h @@ -1,6 +1,10 @@ #ifndef MD5_H #define MD5_H +/** \file lib/md5.h + * + */ + #include typedef unsigned int uint32; diff --git a/lib/md5sum.c b/lib/md5sum.c index bdd1e06..ddddf96 100644 --- a/lib/md5sum.c +++ b/lib/md5sum.c @@ -1,6 +1,6 @@ -/* - * md5sum.c - Generate/check MD5 Message Digests - * +/** \ingroup signature.c + * \file lib/md5sum.c + * Generate/check MD5 Message Digests. * Compile and link with md5.c. If you don't have getopt() in your library * also include getopt.c. For MSDOS you can also link with the wildcard * initialization function (wildargs.obj for Turbo C and setargv.obj for MSC) diff --git a/lib/misc.c b/lib/misc.c index 040b279..7594248 100644 --- a/lib/misc.c +++ b/lib/misc.c @@ -1,3 +1,7 @@ +/** + * \file lib/misc.c + */ + #include "system.h" static int _debug = 0; diff --git a/lib/misc.h b/lib/misc.h index dda1035..56f60b4 100644 --- a/lib/misc.h +++ b/lib/misc.h @@ -1,6 +1,10 @@ #ifndef H_MISC #define H_MISC +/** \file lib/misc.h + * + */ + #include #include diff --git a/lib/oldrpmdb.h b/lib/oldrpmdb.h index ea08209..cce86cb 100644 --- a/lib/oldrpmdb.h +++ b/lib/oldrpmdb.h @@ -1,6 +1,10 @@ #ifndef _H_OLDRPMDB #define _H_OLDRPMDB +/** \file lib/oldrpmdb.h + * + */ + #include #include diff --git a/lib/package.c b/lib/package.c index ec2ba80..e4702df 100644 --- a/lib/package.c +++ b/lib/package.c @@ -1,3 +1,7 @@ +/** \ingroup header + * \file lib/package.c + */ + #include "system.h" #ifdef __LCLINT__ diff --git a/lib/poptBT.c b/lib/poptBT.c index fa69b9d..d77913b 100644 --- a/lib/poptBT.c +++ b/lib/poptBT.c @@ -1,4 +1,5 @@ -/** \file poptBT.c +/** + * \file lib/poptBT.c * Popt tables for build modes. */ diff --git a/lib/poptQV.c b/lib/poptQV.c index d8e123b..595829a 100644 --- a/lib/poptQV.c +++ b/lib/poptQV.c @@ -1,3 +1,7 @@ +/** + * \file lib/poptQV.c + * Popt tables for query/verify modes. + */ #include "system.h" #include "rpmbuild.h" diff --git a/lib/problems.c b/lib/problems.c index 55ad5b2..aeef329 100644 --- a/lib/problems.c +++ b/lib/problems.c @@ -1,3 +1,7 @@ +/** + * \file lib/problems.c + */ + #include "system.h" #include diff --git a/lib/query.c b/lib/query.c index 46ef877..5eef30e 100644 --- a/lib/query.c +++ b/lib/query.c @@ -1,3 +1,7 @@ +/** \ingroup rpmcli + * \file lib/query.c + */ + #include "system.h" #ifndef PATH_MAX diff --git a/lib/rpmchecksig.c b/lib/rpmchecksig.c index fc318b2..5743b38 100644 --- a/lib/rpmchecksig.c +++ b/lib/rpmchecksig.c @@ -1,4 +1,7 @@ -/* checksig.c: verify the signature of an RPM */ +/** \ingroup rpmcli + * \file lib/rpmchecksig.c + * Verify the signature of a package. + */ #include "system.h" diff --git a/lib/rpmdb.c b/lib/rpmdb.c index 72df798..506dff5 100644 --- a/lib/rpmdb.c +++ b/lib/rpmdb.c @@ -1,3 +1,7 @@ +/** \ingroup rpmdb dbi + * \file lib/rpmdb.c + */ + #include "system.h" static int _debug = 0; diff --git a/lib/rpmdb.h b/lib/rpmdb.h index 5426b3e..f687d40 100644 --- a/lib/rpmdb.h +++ b/lib/rpmdb.h @@ -1,7 +1,8 @@ #ifndef H_RPMDB #define H_RPMDB -/** \file lib/rpmdb.h +/** \ingroup rpmdb dbi db1 db3 + * \file lib/rpmdb.h * Access RPM indices using Berkeley db[123] interface. */ @@ -13,7 +14,7 @@ typedef /*@abstract@*/ struct _dbiIndexItem * dbiIndexItem; typedef /*@abstract@*/ struct _dbiIndex * dbiIndex; /* this will break if sizeof(int) != 4 */ -/** +/** \ingroup dbi * A single item from an index database (i.e. the "data returned"). * Note: In rpm-3.0.4 and earlier, this structure was passed by value, * and was identical to the "data saved" structure below. @@ -25,7 +26,7 @@ struct _dbiIndexItem { unsigned int dbNum; /*!< database index */ }; -/** +/** \ingroup dbi * A single item in an index database (i.e. the "data saved"). */ struct _dbiIR { @@ -34,7 +35,7 @@ struct _dbiIR { }; typedef struct _dbiIR * DBIR_t; -/** +/** \ingroup dbi * Items retrieved from the index database. */ struct _dbiIndexSet { @@ -50,7 +51,7 @@ struct _dbiIndexSet { #define DB_LSN void #endif -/** +/** \ingroup dbi * Private methods for accessing an index database. */ struct _dbiVec { @@ -58,7 +59,7 @@ struct _dbiVec { int dbv_minor; /*!< Berkeley db version minor */ int dbv_patch; /*!< Berkeley db version patch */ -/** +/** \ingroup dbi * Return handle for an index database. * @param rpmdb rpm database * @param rpmtag rpm tag @@ -66,7 +67,7 @@ struct _dbiVec { */ int (*open) (rpmdb rpmdb, int rpmtag, /*@out@*/ dbiIndex * dbip); -/** +/** \ingroup dbi * Close index database. * @param dbi index database handle * @param flags (unused) @@ -74,7 +75,7 @@ struct _dbiVec { */ int (*close) (/*@only@*/ dbiIndex dbi, unsigned int flags); -/** +/** \ingroup dbi * Flush pending operations to disk. * @param dbi index database handle * @param flags (unused) @@ -82,7 +83,7 @@ struct _dbiVec { */ int (*sync) (dbiIndex dbi, unsigned int flags); -/** +/** \ingroup dbi * Open database cursor. * @param dbi index database handle * @param dbcp address of database cursor @@ -90,7 +91,7 @@ struct _dbiVec { */ int (*copen) (dbiIndex dbi, /*@out@*/ DBC ** dbcp, unsigned int flags); -/** +/** \ingroup dbi * Close database cursor. * @param dbi index database handle * @param dbcursor database cursor @@ -98,7 +99,7 @@ struct _dbiVec { */ int (*cclose) (dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags); -/** +/** \ingroup dbi * Delete (key,data) pair(s) using db->del or dbcursor->c_del. * @param dbi index database handle * @param dbcursor database cursor @@ -109,7 +110,7 @@ struct _dbiVec { */ int (*cdel) (dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen, unsigned int flags); -/** +/** \ingroup dbi * Retrieve (key,data) pair using db->get or dbcursor->c_get. * @param dbi index database handle * @param dbcursor database cursor @@ -125,7 +126,7 @@ struct _dbiVec { /*@out@*/ void ** datapp, /*@out@*/ size_t * datalenp, unsigned int flags); -/** +/** \ingroup dbi * Store (key,data) pair using db->put or dbcursor->c_put. * @param dbi index database handle * @param dbcursor database cursor @@ -141,7 +142,7 @@ struct _dbiVec { const void * datap, size_t datalen, unsigned int flags); -/** +/** \ingroup dbi * Is database byte swapped? * @param dbi index database handle * @return 0 no @@ -150,7 +151,7 @@ struct _dbiVec { }; -/** +/** \ingroup dbi * Describes an index database (implemented on Berkeley db[123] API). */ struct _dbiIndex { @@ -242,7 +243,7 @@ struct _dbiIndex { }; -/** +/** \ingroup rpmdb * Describes the collection of index databases used by rpm. */ struct rpmdb_s { @@ -278,19 +279,19 @@ struct rpmdb_s { extern "C" { #endif -/** +/** \ingroup db3 * Return new configured index database handle instance. * @param rpmdb rpm database */ /*@only@*/ /*@null@*/ dbiIndex db3New(/*@keep@*/ rpmdb rpmdb, int rpmtag); -/** +/** \ingroup db3 * Destroy index database handle instance. * @param dbi index database handle */ void db3Free( /*@only@*/ /*@null@*/ dbiIndex dbi); -/** +/** \ingroup dbi * Return handle for an index database. * @param rpmdb rpm database * @param rpmtag rpm tag @@ -300,7 +301,7 @@ void db3Free( /*@only@*/ /*@null@*/ dbiIndex dbi); /*@only@*/ /*@null@*/ dbiIndex dbiOpen(rpmdb rpmdb, int rpmtag, unsigned int flags); -/** +/** \ingroup dbi * @param dbi index database handle * @param flags (unused) */ @@ -309,7 +310,7 @@ int XdbiCopen(dbiIndex dbi, /*@out@*/ DBC ** dbcp, unsigned int flags, const cha #define dbiCopen(_a,_b,_c) \ XdbiCopen(_a, _b, _c, __FILE__, __LINE__) -/** +/** \ingroup dbi * @param dbi index database handle * @param flags (unused) */ @@ -318,7 +319,7 @@ int XdbiCclose(dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags, cons #define dbiCclose(_a,_b,_c) \ XdbiCclose(_a, _b, _c, __FILE__, __LINE__) -/** +/** \ingroup dbi * Delete (key,data) pair(s) from index database. * @param dbi index database handle * @param keyp key data @@ -329,7 +330,7 @@ int XdbiCclose(dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags, cons int dbiDel(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen, unsigned int flags); -/** +/** \ingroup dbi * Retrieve (key,data) pair from index database. * @param dbi index database handle * @param keypp address of key data @@ -342,7 +343,7 @@ int dbiDel(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen, int dbiGet(dbiIndex dbi, DBC * dbcursor, void ** keypp, size_t * keylenp, void ** datapp, size_t * datalenp, unsigned int flags); -/** +/** \ingroup dbi * Store (key,data) pair in index database. * @param dbi index database handle * @param keyp key data @@ -355,7 +356,7 @@ int dbiGet(dbiIndex dbi, DBC * dbcursor, void ** keypp, size_t * keylenp, int dbiPut(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen, const void * datap, size_t datalen, unsigned int flags); -/** +/** \ingroup dbi * Close index database. * @param dbi index database handle * @param flags (unused) @@ -363,7 +364,7 @@ int dbiPut(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen, */ int dbiClose(/*@only@*/ dbiIndex dbi, unsigned int flags); -/** +/** \ingroup dbi * Flush pending operations to disk. * @param dbi index database handle * @param flags (unused) @@ -371,44 +372,44 @@ int dbiClose(/*@only@*/ dbiIndex dbi, unsigned int flags); */ int dbiSync (dbiIndex dbi, unsigned int flags); -/** +/** \ingroup dbi * Is database byte swapped? * @param dbi index database handle * @return 0 no */ int dbiByteSwapped(dbiIndex dbi); -/** - * Return base file name for index database (legacy). +/** \ingroup db1 + * Return base file name for db1 database (legacy). * @param rpmtag rpm tag - * @return base file name + * @return base file name of db1 database */ char * db1basename(int rpmtag); -/** +/** \ingroup rpmdb */ unsigned int rpmdbGetIteratorFileNum(rpmdbMatchIterator mi); -/** +/** \ingroup rpmdb * @param rpmdb rpm database */ int rpmdbFindFpList(rpmdb rpmdb, fingerPrint * fpList, /*@out@*/dbiIndexSet * matchList, int numItems); -/** +/** \ingroup dbi * Destroy set of index database items. * @param set set of index database items */ void dbiFreeIndexSet(/*@only@*/ /*@null@*/ dbiIndexSet set); -/** +/** \ingroup dbi * Count items in index database set. * @param set set of index database items * @return number of items */ unsigned int dbiIndexSetCount(dbiIndexSet set); -/** +/** \ingroup dbi * Return record offset of header from element in index database set. * @param set set of index database items * @param recno index of item in set @@ -416,7 +417,7 @@ unsigned int dbiIndexSetCount(dbiIndexSet set); */ unsigned int dbiIndexRecordOffset(dbiIndexSet set, int recno); -/** +/** \ingroup dbi * Return file index from element in index database set. * @param set set of index database items * @param recno index of item in set diff --git a/lib/rpminstall.c b/lib/rpminstall.c index a63789d..1ed538c 100644 --- a/lib/rpminstall.c +++ b/lib/rpminstall.c @@ -1,3 +1,7 @@ +/** \ingroup rpmcli + * \file lib/rpminstall.c + */ + #include "system.h" #include diff --git a/lib/rpmlead.c b/lib/rpmlead.c index 9ec3f6d..e80f9d4 100644 --- a/lib/rpmlead.c +++ b/lib/rpmlead.c @@ -1,3 +1,7 @@ +/** \ingroup lead + * \file lib/rpmlead.c + */ + #include "system.h" #if HAVE_MACHINE_TYPES_H diff --git a/lib/rpmlead.h b/lib/rpmlead.h index a87fefe..bc41727 100644 --- a/lib/rpmlead.h +++ b/lib/rpmlead.h @@ -1,6 +1,10 @@ #ifndef _H_RPMLEAD #define _H_RPMLEAD +/** \file lib/rpmlead.h + * + */ + #include /* Other definitions went to rpmlib.h */ diff --git a/lib/rpmlib.h b/lib/rpmlib.h index 61d5df7..6be2e7c 100644 --- a/lib/rpmlib.h +++ b/lib/rpmlib.h @@ -1,6 +1,11 @@ #ifndef H_RPMLIB #define H_RPMLIB +/** \file lib/rpmlib.h + * \ingroup rpmcli rpmrc rpmdep rpmtrans rpmdb lead signature header payload dbi + * + */ + /* This is the *only* module users of rpmlib should need to include */ /* and it shouldn't need these :-( */ @@ -11,8 +16,6 @@ #include "header.h" #include "popt.h" -typedef /*@abstract@*/ struct _dbiIndexSet * dbiIndexSet; - #ifdef __cplusplus extern "C" { #endif @@ -52,22 +55,32 @@ int headerNVR(Header h, /*@out@*/ const char **np, /*@out@*/ const char **vp, /*@out@*/ const char **rp) /*@modifies *np, *vp, *rp @*/; /** + * Retrieve file names from header. + * The representation of file names in package headers changed in rpm-4.0. + * Originally, file names were stored as an array of paths. In rpm-4.0, + * file names are stored as separate arrays of dirname's and basename's, + * with a dirname index to associate the correct dirname with each basname. + * This function is used to retrieve file names independent of how the + * file names are represented in the package header. + * * @param h header + * @retval fileListPtr address of array of file names + * @retval fileCountPtr address of number of files */ -void rpmBuildFileList(Header h,/*@out@*/ const char *** fileListPtr, +void rpmBuildFileList(Header h, /*@out@*/ const char *** fileListPtr, /*@out@*/ int * fileCountPtr) /*@modifies *fileListPtr, *fileCountPtr @*/; /** * Retrieve tag info from header. - * XXX This is a "dressed" entry to headerGetEntry to do: + * This is a "dressed" entry to headerGetEntry to do: * 1) DIRNAME/BASENAME/DIRINDICES -> FILENAMES tag conversions. * 2) i18n lookaside (if enabled). * * @param h header * @param tag tag * @retval type address of tag value data type - * @retval p address of pointer to tag value + * @retval p address of pointer to tag value(s) * @retval c address of number of values * @return 0 on success, 1 on bad magic, 2 on error */ @@ -77,13 +90,14 @@ int rpmHeaderGetEntry(Header h, int_32 tag, /*@out@*/ int_32 *type, /** * Retrieve tag info from header. - * XXX Yet Another dressed entry to unify signature/header tag retrieval. + * Yet Another "dressed" entry to headerGetEntry in order to unify + * signature/header tag retrieval. * @param leadp rpm lead * @param h header * @param sigs signatures * @param tag tag * @retval type address of tag value data type - * @retval p address of pointer to tag value + * @retval p address of pointer to tag value(s) * @retval c address of number of values * @return 0 on success, 1 on bad magic, 2 on error */ @@ -91,13 +105,20 @@ int rpmPackageGetEntry(void *leadp, Header sigs, Header h, int_32 tag, int_32 *type, void **p, int_32 *c) /*@modifies *type, *p, *c @*/; -/** */ +/** + * Automatically generated table of tag name/value pairs. + */ extern const struct headerTagTableEntry rpmTagTable[]; -/** */ + +/** + * Number of entries in rpmTagTable. + */ extern const int rpmTagTableSize; -/* this chains to headerDefaultFormats[] */ -/** */ +/** + * Table of query format extensions. + * @note Chains to headerDefaultFormats[]. + */ extern const struct headerSprintfExtension rpmHeaderFormats[]; /* these pseudo-tags are used by the dbi iterator interface */ @@ -310,6 +331,11 @@ extern const struct headerSprintfExtension rpmHeaderFormats[]; #define isDependsMULTILIB(_dflags) ((_dflags) & RPMSENSE_MULTILIB) +#define xfree(_p) free((void *)_p) + +/* ==================================================================== */ +/** \name RPMRC */ +/*@{*/ /* Stuff for maintaining "variables" like SOURCEDIR, BUILDDIR, etc */ /* #define RPMVAR_SOURCEDIR 0 -- No longer used */ @@ -369,109 +395,152 @@ extern const struct headerSprintfExtension rpmHeaderFormats[]; #define RPMVAR_NUM 55 /* number of RPMVAR entries */ -#define xfree(_p) free((void *)_p) - -/** rpmrc.c **/ - -/** +/** \ingroup rpmrc + * Return value of rpmrc variable. + * @deprecated Use rpmExpand() with appropriate macro expression. */ const char * rpmGetVar(int var); -/** +/** \ingroup rpmrc + * Set value of rpmrc variable. + * @deprecated Use rpmDefineMacro() to change appropriate macro instead. */ void rpmSetVar(int var, const char *val); +/** \ingroup rpmrc + * Build and install arch/os table identifiers. + */ #define RPM_MACHTABLE_INSTARCH 0 #define RPM_MACHTABLE_INSTOS 1 #define RPM_MACHTABLE_BUILDARCH 2 #define RPM_MACHTABLE_BUILDOS 3 #define RPM_MACHTABLE_COUNT 4 /* number of arch/os tables */ -/** +/** \ingroup rpmrc + * Read rpmrc (and macro) configuration file(s) for a target. + * @param file colon separated files to read (NULL uses default) + * @param target target platform (NULL uses default) + * @return 0 on success, -1 on error */ int rpmReadConfigFiles(const char * file, const char * target); -/** +/** \ingroup rpmrc + * Read rpmrc (and macro) configuration file(s). + * @param file colon separated files to read (NULL uses default) + * @return 0 on succes */ int rpmReadRC(const char * file); -/** +/** \ingroup rpmrc + * Return current arch name and/or number. + * @retval name address of arch name (or NULL) + * @retval num address of arch number (or NULL) */ void rpmGetArchInfo( /*@out@*/ const char ** name, /*@out@*/ int * num); -/** +/** \ingroup rpmrc + * Return current os name and/or number. + * @retval name address of os name (or NULL) + * @retval num address of os number (or NULL) */ void rpmGetOsInfo( /*@out@*/ const char ** name, /*@out@*/ int * num); -/** +/** \ingroup rpmrc + * Return arch/os score of a name. + * An arch score measures the nearness of an arch name to the currently + * running (or defined) platform arch. For example, the score of "i586" + * on an i686 platform is (usually) 1. The arch score is used to select + * one of several otherwise identical packages based on the arch/os hints + * in the header of the intended platform. + * + * @param type any of the RPM_MACHTABLE_* constants + * @param name name + * @return arch score */ int rpmMachineScore(int type, const char * name); -/** +/** \ingroup rpmrc + * Display current rpmrc (and macro) configuration. + * @param f output file handle + * @return 0 always */ int rpmShowRC(FILE *f); -/** +/** \ingroup rpmrc + * @param archTable + * @param osTable */ void rpmSetTables(int archTable, int osTable); /* only used by build code */ -/* if either are NULL, they are set to the default value (munged uname()) - pushed through a translation table (if appropriate) */ -/** +/** \ingroup rpmrc + * Set current arch/os names. + * NULL as argument is set to the default value (munged uname()) + * pushed through a translation table (if appropriate). + * + * @param arch arch name (or NULL) + * @param os os name (or NULL) */ void rpmSetMachine(const char * arch, const char * os); -/** +/** \ingroup rpmrc + * Return current arch/os names. + * @retval arch address of arch name (or NULL) + * @retval os address of os name (or NULL) */ void rpmGetMachine( /*@out@*/ const char **arch, /*@out@*/ const char **os); -/** +/** \ingroup rpmrc + * Destroy rpmrc arch/os compatibility tables. */ void rpmFreeRpmrc(void); +/*@}*/ /* ==================================================================== */ -/** **/ +/** \name RPMDB */ +/*@{*/ typedef /*@abstract@*/ struct rpmdb_s * rpmdb; +typedef /*@abstract@*/ struct _dbiIndexSet * dbiIndexSet; -/** +/** \ingroup rpmdb + * Open rpm database. * @param root path to top of install tree * @retval dbp address of rpm database - * @return + * @param mode open(2) flags: O_RDWR or O_RDONLY (O_CREAT also) + * @param perms database permissions + * @return 0 on success */ int rpmdbOpen (const char * root, /*@out@*/ rpmdb * dbp, int mode, int perms); - /* 0 on error */ -/** +/** \ingroup rpmdb * Initialize database. * @param root path to top of install tree * @param perms database permissions - * @return + * @return 0 on success */ int rpmdbInit(const char * root, int perms); - /* nonzero on error */ -/** +/** \ingroup rpmdb * Close all database indices and free rpmdb. * @param rpmdb rpm database * @return 0 always */ int rpmdbClose ( /*@only@*/ rpmdb rpmdb); -/** +/** \ingroup rpmdb * Sync all database indices. * @param rpmdb rpm database * @return 0 always */ int rpmdbSync (rpmdb rpmdb); -/** +/** \ingroup rpmdb * Open all database indices. * @param rpmdb rpm database * @return 0 always */ int rpmdbOpenAll (rpmdb rpmdb); -/** +/** \ingroup rpmdb * Return number of instances of package in rpm database. * @param db rpm database * @param name rpm package name @@ -479,38 +548,38 @@ int rpmdbOpenAll (rpmdb rpmdb); */ int rpmdbCountPackages(rpmdb db, const char *name); -/** +/** \ingroup rpmdb */ typedef /*@abstract@*/ struct _rpmdbMatchIterator * rpmdbMatchIterator; -/** +/** \ingroup rpmdb * Destroy rpm database iterator. * @param mi rpm database iterator */ void rpmdbFreeIterator( /*@only@*/ rpmdbMatchIterator mi); -/** +/** \ingroup rpmdb * Return rpm database used by iterator. * @param mi rpm database iterator * @return rpm database handle */ rpmdb rpmdbGetIteratorRpmDB(rpmdbMatchIterator mi); -/** +/** \ingroup rpmdb * Return join key for current position of rpm database iterator. * @param mi rpm database iterator * @return current join key */ unsigned int rpmdbGetIteratorOffset(rpmdbMatchIterator mi); -/** +/** \ingroup rpmdb * Return number of elements in rpm database iterator. * @param mi rpm database iterator * @return number of elements */ int rpmdbGetIteratorCount(rpmdbMatchIterator mi); -/** +/** \ingroup rpmdb * Append items to set of package instances to iterate. * @param mi rpm database iterator * @param hdrNums array of package instances @@ -519,7 +588,7 @@ int rpmdbGetIteratorCount(rpmdbMatchIterator mi); */ int rpmdbAppendIterator(rpmdbMatchIterator mi, int * hdrNums, int nHdrNums); -/** +/** \ingroup rpmdb * Remove items from set of package instances to iterate. * @param mi rpm database iterator * @param hdrNums array of package instances @@ -530,42 +599,41 @@ int rpmdbAppendIterator(rpmdbMatchIterator mi, int * hdrNums, int nHdrNums); int rpmdbPruneIterator(rpmdbMatchIterator mi, int * hdrNums, int nHdrNums, int sorted); -/** +/** \ingroup rpmdb * Modify iterator to filter out headers that do not match version. - * TODO: replace with a more general mechanism. + * @todo replace with a more general mechanism using RE's on tag content. * @param mi rpm database iterator * @param version version to check for */ void rpmdbSetIteratorVersion(rpmdbMatchIterator mi, /*@kept@*/ const char * version); -/** +/** \ingroup rpmdb * Modify iterator to filter out headers that do not match release. - * TODO: replace with a more general mechanism. + * @todo replace with a more general mechanism using RE's on tag content. * @param mi rpm database iterator * @param release release to check for */ void rpmdbSetIteratorRelease(rpmdbMatchIterator mi, /*@kept@*/ const char * release); -/** +/** \ingroup rpmdb * Modify iterator to mark header for lazy write. - * TODO: replace with a more general mechanism. * @param mi rpm database iterator * @param modified new value of modified * @return previous value */ int rpmdbSetIteratorModified(rpmdbMatchIterator mi, int modified); -/** +/** \ingroup rpmdb * Return next package header from iteration. * @param mi rpm database iterator * @return NULL on end of iteration. */ Header rpmdbNextIterator(rpmdbMatchIterator mi); -Header XrpmdbNextIterator(rpmdbMatchIterator mi, const char * f, unsigned int l); #define rpmdbNextIterator(_a) \ XrpmdbNextIterator(_a, __FILE__, __LINE__) +Header XrpmdbNextIterator(rpmdbMatchIterator mi, const char * f, unsigned int l); -/** +/** \ingroup rpmdb * Return database iterator. * @param rpmdb rpm database * @param rpmtag rpm tag @@ -577,7 +645,7 @@ Header XrpmdbNextIterator(rpmdbMatchIterator mi, const char * f, unsigned int l) /*@kept@*/ rpmdb rpmdb, int rpmtag, const void * key, size_t keylen); -/** +/** \ingroup rpmdb * Remove package header from rpm database and indices. * @param rpmdb rpm database * @param offset location in Packages dbi @@ -585,7 +653,7 @@ Header XrpmdbNextIterator(rpmdbMatchIterator mi, const char * f, unsigned int l) */ int rpmdbRemove(rpmdb db, unsigned int offset); -/** +/** \ingroup rpmdb * Add package header to rpm database and indices. * @param rpmdb rpm database * @param rpmtag rpm tag @@ -593,17 +661,96 @@ int rpmdbRemove(rpmdb db, unsigned int offset); */ int rpmdbAdd(rpmdb rpmdb, Header dbentry); -/** +/** \ingroup rpmdb + * Rebuild database indices from package headers. * @param root path to top of install tree */ int rpmdbRebuild(const char * root); +/*@}*/ +/* ==================================================================== */ +/** \name RPMPROBS */ +/*@{*/ + +/** */ +typedef enum rpmProblemType_e { RPMPROB_BADARCH, + RPMPROB_BADOS, + RPMPROB_PKG_INSTALLED, + RPMPROB_BADRELOCATE, + RPMPROB_REQUIRES, + RPMPROB_CONFLICT, + RPMPROB_NEW_FILE_CONFLICT, + RPMPROB_FILE_CONFLICT, + RPMPROB_OLDPACKAGE, + RPMPROB_DISKSPACE, + RPMPROB_BADPRETRANS + } rpmProblemType; + +/** */ +typedef /*@abstract@*/ struct rpmProblem_s { + Header h, altH; +/*@dependent@*/ const void * key; + rpmProblemType type; + int ignoreProblem; +/*@only@*/ const char * str1; + unsigned long ulong1; +} rpmProblem; + +/** */ +typedef /*@abstract@*/ struct rpmProblemSet_s { + int numProblems; + int numProblemsAlloced; + rpmProblem * probs; +} * rpmProblemSet; + +/** + */ +void printDepFlags(FILE *fp, const char *version, int flags) + /*@modifies *fp @*/; + +/** + */ +struct rpmDependencyConflict { + char * byName, * byVersion, * byRelease; + Header byHeader; + /* these needs fields are misnamed -- they are used for the package + which isn't needed as well */ + char * needsName, * needsVersion; + int needsFlags; + /*@observer@*/ /*@null@*/ const void * suggestedPackage; /* NULL if none */ + enum { RPMDEP_SENSE_REQUIRES, RPMDEP_SENSE_CONFLICTS } sense; +} ; + +/** + */ +void printDepProblems(FILE *fp, struct rpmDependencyConflict *conflicts, + int numConflicts) /*@modifies *fp @*/; + +/** + */ +/*@only@*/ const char * rpmProblemString(rpmProblem prob) /*@*/; + +/** + */ +void rpmProblemPrint(FILE *fp, rpmProblem prob) /*@modifies *fp @*/; + +/** + */ +void rpmProblemSetPrint(FILE *fp, rpmProblemSet probs) /*@modifies *fp @*/; + +/** + */ +void rpmProblemSetFree( /*@only@*/ rpmProblemSet probs); + +/*@}*/ /* ==================================================================== */ +/** \name RPMTS */ +/*@{*/ /* we pass these around as an array with a sentinel */ typedef struct rpmRelocation_s { - const char * oldPath; /* NULL here evals to RPMTAG_DEFAULTPREFIX, */ /* XXX for backwards compatibility */ - const char * newPath; /* NULL means to omit the file completely! */ + const char * oldPath; /*!< NULL here evals to RPMTAG_DEFAULTPREFIX, */ + const char * newPath; /*!< NULL means to omit the file completely! */ } rpmRelocation; @@ -629,38 +776,12 @@ int rpmInstallSourcePackage(const char * root, FD_t fd, const char ** specFile, */ int rpmVersionCompare(Header first, Header second); - -/** - * @param root path to top of install tree - * @param h header - */ -int rpmVerifyFile(const char * root, Header h, int filenum, - /*@out@*/ int * result, int omitMask); - -/** - * @param root path to top of install tree - * @param h header - * @param err file handle - */ -int rpmVerifyScript(const char * root, Header h, FD_t err); - /* Transaction sets are inherently unordered! RPM may reorder transaction sets to reduce errors. In general, installs/upgrades are done before strict removals, and prerequisite ordering is done on installs/upgrades. */ typedef /*@abstract@*/ struct rpmTransactionSet_s * rpmTransactionSet; -struct rpmDependencyConflict { - char * byName, * byVersion, * byRelease; - Header byHeader; - /* these needs fields are misnamed -- they are used for the package - which isn't needed as well */ - char * needsName, * needsVersion; - int needsFlags; - /*@observer@*/ /*@null@*/ const void * suggestedPackage; /* NULL if none */ - enum { RPMDEP_SENSE_REQUIRES, RPMDEP_SENSE_CONFLICTS } sense; -} ; - -/** +/** \ingroup rpmtrans * Create an empty transaction set. * @param rpmdb rpm database (may be NULL if database is not accessed) * @param rootdir path to top of install tree @@ -669,7 +790,7 @@ struct rpmDependencyConflict { /*@only@*/ rpmTransactionSet rpmtransCreateSet( /*@only@*/ rpmdb rpmdb, const char * rootdir); -/** +/** \ingroup rpmtrans * Add package to be installed to unordered transaction set. * * If fd is NULL, the callback specified in rpmtransCreateSet() is used to @@ -689,7 +810,7 @@ int rpmtransAddPackage(rpmTransactionSet rpmdep, Header h, FD_t fd, /*@owned@*/ const void * key, int update, rpmRelocation * relocs); -/** +/** \ingroup rpmtrans * Add package to universe of possible packages to install in transaction set. * @param rpmdep rpm transaction set * @param h header @@ -698,27 +819,27 @@ int rpmtransAddPackage(rpmTransactionSet rpmdep, Header h, FD_t fd, void rpmtransAvailablePackage(rpmTransactionSet rpmdep, Header h, /*@owned@*/ const void * key); -/** +/** \ingroup rpmtrans * Add package to be removed to unordered transaction set. * @param rpmdep rpm transaction set * @param dboffset rpm database instance */ void rpmtransRemovePackage(rpmTransactionSet rpmdep, int dboffset); -/** +/** \ingroup rpmtrans * Destroy transaction set. * @param rpmdep rpm transaction set */ void rpmtransFree( /*@only@*/ rpmTransactionSet rpmdep); -/** +/** \ingroup rpmtrans * @param ts rpm transaction set * @param fd file handle */ void rpmtransSetScriptFd(rpmTransactionSet ts, FD_t fd); /* this checks for dependency satisfaction, but *not* ordering */ -/** +/** \ingroup rpmtrans * @param rpmdep rpm transaction set */ int rpmdepCheck(rpmTransactionSet rpmdep, @@ -729,12 +850,12 @@ int rpmdepCheck(rpmTransactionSet rpmdep, check is done, use rpmdepCheck() for that. If dependencies are not satisfied a "best-try" ordering is returned. */ -/** +/** \ingroup rpmtrans * @param order rpm transaction set */ int rpmdepOrder(rpmTransactionSet order); -/** +/** \ingroup rpmtrans * Destroy dependency conflicts. * @param conflicts dependency conflicts * @param numConflicts no. of dependency conflicts @@ -752,7 +873,7 @@ void rpmdepFreeConflicts( /*@only@*/ struct rpmDependencyConflict * conflicts, #define RPMTRANS_FLAG_KEEPOBSOLETE (1 << 7) #define RPMTRANS_FLAG_MULTILIB (1 << 8) -/** +/** \ingroup rpmdep * Compare two versioned dependency ranges, looking for overlap. * @param AName 1st dependncy name string * @param AEVR 1st dependency [epoch:]version[-release] string @@ -765,7 +886,7 @@ void rpmdepFreeConflicts( /*@only@*/ struct rpmDependencyConflict * conflicts, int rpmRangesOverlap(const char *AName, const char *AEVR, int AFlags, const char *BName, const char *BEVR, int BFlags) /*@*/; -/** +/** \ingroup rpmdep * Check dependency against internal rpmlib feature provides. * @param keyName dependency name string * @param keyEVR dependency [epoch:]version[-release] string @@ -775,68 +896,13 @@ int rpmRangesOverlap(const char *AName, const char *AEVR, int AFlags, int rpmCheckRpmlibProvides(const char * keyName, const char * keyEVR, int keyFlags) /*@*/; -/** +/** \ingroup rpmcli + * Display current rpmlib feature provides. + * @param fp output file handle */ void rpmShowRpmlibProvides(FILE * fp) /*@modifies *fp @*/; -/** */ -typedef enum rpmProblemType_e { RPMPROB_BADARCH, - RPMPROB_BADOS, - RPMPROB_PKG_INSTALLED, - RPMPROB_BADRELOCATE, - RPMPROB_REQUIRES, - RPMPROB_CONFLICT, - RPMPROB_NEW_FILE_CONFLICT, - RPMPROB_FILE_CONFLICT, - RPMPROB_OLDPACKAGE, - RPMPROB_DISKSPACE, - RPMPROB_BADPRETRANS - } rpmProblemType; - -/** */ -typedef /*@abstract@*/ struct rpmProblem_s { - Header h, altH; -/*@dependent@*/ const void * key; - rpmProblemType type; - int ignoreProblem; -/*@only@*/ const char * str1; - unsigned long ulong1; -} rpmProblem; - -/** */ -typedef /*@abstract@*/ struct rpmProblemSet_s { - int numProblems; - int numProblemsAlloced; - rpmProblem * probs; -} * rpmProblemSet; - -/** - */ -void printDepFlags(FILE *fp, const char *version, int flags) - /*@modifies *fp @*/; - -/** - */ -void printDepProblems(FILE *fp, struct rpmDependencyConflict *conflicts, - int numConflicts) /*@modifies *fp @*/; - -/** - */ -/*@only@*/ const char * rpmProblemString(rpmProblem prob) /*@*/; - -/** - */ -void rpmProblemPrint(FILE *fp, rpmProblem prob) /*@modifies *fp @*/; - -/** - */ -void rpmProblemSetPrint(FILE *fp, rpmProblemSet probs) /*@modifies *fp @*/; - -/** - */ -void rpmProblemSetFree( /*@only@*/ rpmProblemSet probs); - -/** +/** \ingroup rpmtrans * @param ts rpm transaction set */ int rpmRunTransactions(rpmTransactionSet ts, rpmCallbackFunction notify, @@ -853,6 +919,8 @@ int rpmRunTransactions(rpmTransactionSet ts, rpmCallbackFunction notify, #define RPMPROB_FILTER_OLDPACKAGE (1 << 6) #define RPMPROB_FILTER_DISKSPACE (1 << 7) +/*@}*/ + /** rpmlead.c **/ #define RPMLEAD_BINARY 0 @@ -867,6 +935,8 @@ int rpmRunTransactions(rpmTransactionSet ts, rpmCallbackFunction notify, #define RPMLEAD_SIZE 96 +/** \ingroup lead + */ struct rpmlead { unsigned char magic[4]; unsigned char major, minor; @@ -878,6 +948,8 @@ struct rpmlead { char reserved[16]; /* pads to 96 bytes -- 8 byte aligned! */ } ; +/** \ingroup lead + */ struct oldrpmlead { /* for version 1 packages */ unsigned char magic[4]; unsigned char major, minor; @@ -889,69 +961,6 @@ struct oldrpmlead { /* for version 1 packages */ unsigned int archiveOffset; } ; -/** signature.c **/ - -/**************************************************/ -/* */ -/* Signature Tags */ -/* */ -/* These go in the sig Header to specify */ -/* individual signature types. */ -/* */ -/**************************************************/ - -#define RPMSIGTAG_SIZE 1000 -/* the md5 sum was broken *twice* on big endian machines */ -#define RPMSIGTAG_LEMD5_1 1001 -#define RPMSIGTAG_PGP 1002 -#define RPMSIGTAG_LEMD5_2 1003 -#define RPMSIGTAG_MD5 1004 -#define RPMSIGTAG_GPG 1005 -#define RPMSIGTAG_PGP5 1006 /* XXX legacy use only */ - -/* Signature tags by Public Key Algorithm (RFC 2440) */ -/* N.B.: These tags are tenative, the values may change */ -#define RPMTAG_PK_BASE 2048 -#define RPMTAG_PK_RSA_ES RPMTAG_PK_BASE+1 -#define RPMTAG_PK_RSA_E RPMTAG_PK_BASE+2 -#define RPMTAG_PK_RSA_S RPMTAG_PK_BASE+3 -#define RPMTAG_PK_ELGAMAL_E RPMTAG_PK_BASE+16 -#define RPMTAG_PK_DSA RPMTAG_PK_BASE+17 -#define RPMTAG_PK_ELLIPTIC RPMTAG_PK_BASE+18 -#define RPMTAG_PK_ECDSA RPMTAG_PK_BASE+19 -#define RPMTAG_PK_ELGAMAL_ES RPMTAG_PK_BASE+20 -#define RPMTAG_PK_DH RPMTAG_PK_BASE+21 - -#define RPMTAG_HASH_BASE 2048+64 -#define RPMTAG_HASH_MD5 RPMTAG_HASH_BASE+1 -#define RPMTAG_HASH_SHA1 RPMTAG_HASH_BASE+2 -#define RPMTAG_HASH_RIPEMD160 RPMTAG_HASH_BASE+3 -#define RPMTAG_HASH_MD2 RPMTAG_HASH_BASE+5 -#define RPMTAG_HASH_TIGER192 RPMTAG_HASH_BASE+6 -#define RPMTAG_HASH_HAVAL_5_160 RPMTAG_HASH_BASE+7 - -/**************************************************/ -/* */ -/* verifySignature() results */ -/* */ -/**************************************************/ - -/* verifySignature() results */ -#define RPMSIG_OK 0 -#define RPMSIG_UNKNOWN 1 -#define RPMSIG_BAD 2 -#define RPMSIG_NOKEY 3 /* Do not have the key to check this signature */ -#define RPMSIG_NOTTRUSTED 4 /* We have the key but it is not trusted */ - -/** - */ -void rpmFreeSignature(Header h); - -/** - */ -int rpmVerifySignature(const char *file, int_32 sigTag, void *sig, int count, - char *result); - /** */ void freeFilesystems(void); @@ -966,8 +975,12 @@ int rpmGetFilesystemUsage(const char ** filelist, int_32 * fssizes, int numFiles, /*@out@*/ uint_32 ** usagesPtr, int flags); /* ==================================================================== */ +/** \name RPMBT */ +/*@{*/ /* --- build mode options */ +/** \ingroup rpmcli + */ struct rpmBuildArguments { int buildAmount; const char *buildRootOverride; @@ -978,22 +991,50 @@ struct rpmBuildArguments { int shortCircuit; char buildMode; char buildChar; - /*@dependent@*/ const char *rootdir; +/*@dependent@*/ const char *rootdir; }; +/** \ingroup rpmcli + */ typedef struct rpmBuildArguments BTA_t; +/** \ingroup rpmcli + */ extern struct rpmBuildArguments rpmBTArgs; +/** \ingroup rpmcli + */ extern struct poptOption rpmBuildPoptTable[]; +/*@}*/ /* ==================================================================== */ +/** \name RPMQV */ +/*@{*/ + +/** \ingroup rpmcli + * @param root path to top of install tree + * @param h header + */ +int rpmVerifyFile(const char * root, Header h, int filenum, + /*@out@*/ int * result, int omitMask); + +/** \ingroup rpmcli + * @param root path to top of install tree + * @param h header + * @param err file handle + */ +int rpmVerifyScript(const char * root, Header h, FD_t err); + /* --- query/verify mode options */ /* XXX SPECFILE is not verify sources */ +/** \ingroup rpmcli + */ enum rpmQVSources { RPMQV_PACKAGE = 0, RPMQV_PATH, RPMQV_ALL, RPMQV_RPM, RPMQV_GROUP, RPMQV_WHATPROVIDES, RPMQV_WHATREQUIRES, RPMQV_TRIGGEREDBY, RPMQV_DBOFFSET, RPMQV_SPECFILE }; +/** \ingroup rpmcli + */ struct rpmQVArguments { enum rpmQVSources qva_source; int qva_sourceCount; /* > 1 is an error */ @@ -1004,20 +1045,26 @@ struct rpmQVArguments { char qva_mode; char qva_char; }; +/** \ingroup rpmcli + */ typedef struct rpmQVArguments QVA_t; +/** \ingroup rpmcli + */ extern struct rpmQVArguments rpmQVArgs; +/** \ingroup rpmcli + */ extern struct poptOption rpmQVSourcePoptTable[]; -/** +/** \ingroup rpmcli * @param qva parsed query/verify options * @param db rpm database * @param h header to use for query/verify */ typedef int (*QVF_t) (QVA_t *qva, rpmdb db, Header h); -/** +/** \ingroup rpmcli * @param qva parsed query/verify options * @param mi rpm database iterator * @param showPackage query/verify routine @@ -1043,15 +1090,20 @@ int showMatches(QVA_t *qva, /*@only@*/ /*@null@*/ rpmdbMatchIterator mi, */ int tagValue(const char *tagstr) /*@*/; +/** \ingroup rpmcli + */ extern int specedit; + +/** \ingroup rpmcli + */ extern struct poptOption rpmQueryPoptTable[]; -/** +/** \ingroup rpmcli * @param f file handle to use for display */ void rpmDisplayQueryTags(FILE * f); -/** +/** \ingroup rpmcli * @param qva parsed query/verify options * @param source type of source to query/verify * @param arg name of source to query/verify @@ -1061,14 +1113,14 @@ void rpmDisplayQueryTags(FILE * f); int rpmQueryVerify(QVA_t *qva, enum rpmQVSources source, const char * arg, rpmdb db, QVF_t showPackage); -/** +/** \ingroup rpmcli * @param qva parsed query/verify options * @param db rpm database (unused for queries) * @param h header to use for query */ int showQueryPackage(QVA_t *qva, rpmdb db, Header h); -/** +/** \ingroup rpmcli * @param qva parsed query/verify options * @param source type of source to query * @param arg name of source to query @@ -1080,23 +1132,28 @@ int rpmQuery(QVA_t *qva, enum rpmQVSources source, const char * arg); #define VERIFY_SCRIPT (1 << 11) #define VERIFY_MD5 (1 << 12) +/** \ingroup rpmcli + */ extern struct poptOption rpmVerifyPoptTable[]; -/** +/** \ingroup rpmcli * @param qva parsed query/verify options * @param db rpm database * @param h header to use for verify */ int showVerifyPackage(QVA_t *qva, /*@only@*/ rpmdb db, Header h); -/** +/** \ingroup rpmcli * @param qva parsed query/verify options * @param source type of source to verify * @param arg name of source to verify */ int rpmVerify(QVA_t *qva, enum rpmQVSources source, const char *arg); +/*@}*/ /* ==================================================================== */ +/** \name RPMEIU */ +/*@{*/ /* --- install/upgrade/erase modes */ #define INSTALL_PERCENT (1 << 0) @@ -1111,38 +1168,105 @@ int rpmVerify(QVA_t *qva, enum rpmQVSources source, const char *arg); #define UNINSTALL_ALLMATCHES (1 << 1) -/** +/** \ingroup rpmcli * @param rootdir path to top of install tree * @param argv array of package file names (NULL terminated) */ int rpmInstall(const char * rootdir, const char ** argv, int installFlags, int interfaceFlags, int probFilter, rpmRelocation * relocations); -/** +/** \ingroup rpmcli */ int rpmInstallSource(const char * prefix, const char * arg, const char ** specFile, char ** cookie); -/** +/** \ingroup rpmcli * @param rootdir path to top of install tree * @param argv array of package file names (NULL terminated) */ int rpmErase(const char * rootdir, const char ** argv, int uninstallFlags, int interfaceFlags); +/*@}*/ /* ==================================================================== */ +/** \name RPMK */ +/*@{*/ + +/** signature.c **/ + +/**************************************************/ +/* */ +/* Signature Tags */ +/* */ +/* These go in the sig Header to specify */ +/* individual signature types. */ +/* */ +/**************************************************/ + +#define RPMSIGTAG_SIZE 1000 +/* the md5 sum was broken *twice* on big endian machines */ +#define RPMSIGTAG_LEMD5_1 1001 +#define RPMSIGTAG_PGP 1002 +#define RPMSIGTAG_LEMD5_2 1003 +#define RPMSIGTAG_MD5 1004 +#define RPMSIGTAG_GPG 1005 +#define RPMSIGTAG_PGP5 1006 /* XXX legacy use only */ + +/* Signature tags by Public Key Algorithm (RFC 2440) */ +/* N.B.: These tags are tenative, the values may change */ +#define RPMTAG_PK_BASE 2048 +#define RPMTAG_PK_RSA_ES RPMTAG_PK_BASE+1 +#define RPMTAG_PK_RSA_E RPMTAG_PK_BASE+2 +#define RPMTAG_PK_RSA_S RPMTAG_PK_BASE+3 +#define RPMTAG_PK_ELGAMAL_E RPMTAG_PK_BASE+16 +#define RPMTAG_PK_DSA RPMTAG_PK_BASE+17 +#define RPMTAG_PK_ELLIPTIC RPMTAG_PK_BASE+18 +#define RPMTAG_PK_ECDSA RPMTAG_PK_BASE+19 +#define RPMTAG_PK_ELGAMAL_ES RPMTAG_PK_BASE+20 +#define RPMTAG_PK_DH RPMTAG_PK_BASE+21 + +#define RPMTAG_HASH_BASE 2048+64 +#define RPMTAG_HASH_MD5 RPMTAG_HASH_BASE+1 +#define RPMTAG_HASH_SHA1 RPMTAG_HASH_BASE+2 +#define RPMTAG_HASH_RIPEMD160 RPMTAG_HASH_BASE+3 +#define RPMTAG_HASH_MD2 RPMTAG_HASH_BASE+5 +#define RPMTAG_HASH_TIGER192 RPMTAG_HASH_BASE+6 +#define RPMTAG_HASH_HAVAL_5_160 RPMTAG_HASH_BASE+7 + +/**************************************************/ +/* */ +/* verifySignature() results */ +/* */ +/**************************************************/ + +/* verifySignature() results */ +#define RPMSIG_OK 0 +#define RPMSIG_UNKNOWN 1 +#define RPMSIG_BAD 2 +#define RPMSIG_NOKEY 3 /* Do not have the key to check this signature */ +#define RPMSIG_NOTTRUSTED 4 /* We have the key but it is not trusted */ + +/** \ingroup signature + */ +void rpmFreeSignature(Header h); + +/** \ingroup signature + */ +int rpmVerifySignature(const char *file, int_32 sigTag, void *sig, int count, + char *result); + /* --- checksig/resign */ #define CHECKSIG_PGP (1 << 0) #define CHECKSIG_MD5 (1 << 1) #define CHECKSIG_GPG (1 << 2) -/** +/** \ingroup rpmcli * @param argv array of package file names (NULL terminated) */ int rpmCheckSig(int flags, const char ** argv); -/** +/** \ingroup rpmcli * @param argv array of package file names (NULL terminated) */ int rpmReSign(int add, char *passPhrase, const char ** argv); @@ -1150,6 +1274,8 @@ int rpmReSign(int add, char *passPhrase, const char ** argv); #define ADD_SIGNATURE 1 #define NEW_SIGNATURE 0 +/*@}*/ + #ifdef __cplusplus } #endif diff --git a/lib/rpmlibprov.c b/lib/rpmlibprov.c index 11e8d5a..1da8cc3 100644 --- a/lib/rpmlibprov.c +++ b/lib/rpmlibprov.c @@ -1,3 +1,7 @@ +/** \ingroup rpmdep + * \file lib/rpmlibprov.c + */ + #include "system.h" #include diff --git a/lib/signature.c b/lib/signature.c index 8005e40..0042eb9 100644 --- a/lib/signature.c +++ b/lib/signature.c @@ -1,3 +1,7 @@ +/** \ingroup signature + * \file lib/signature.c + */ + /* signature.c - RPM signature functions */ /* NOTES diff --git a/lib/signature.h b/lib/signature.h index 03cedd4..40f6d65 100644 --- a/lib/signature.h +++ b/lib/signature.h @@ -1,7 +1,9 @@ #ifndef H_SIGNATURE #define H_SIGNATURE -/* signature.h - generate and verify signatures */ +/** \file lib/signature.h + * Generate and verify signatures. + */ #include diff --git a/lib/stringbuf.c b/lib/stringbuf.c index 548c745..afd223e 100644 --- a/lib/stringbuf.c +++ b/lib/stringbuf.c @@ -1,3 +1,7 @@ +/** + * \file lib/stringbuf.c + */ + #include "system.h" #include "stringbuf.h" diff --git a/lib/stringbuf.h b/lib/stringbuf.h index 9b658ba..95474cb 100644 --- a/lib/stringbuf.h +++ b/lib/stringbuf.h @@ -1,6 +1,10 @@ #ifndef _STRINGBUF_H_ #define _STRINGBUF_H_ +/** \file lib/stringbuf.h + * + */ + typedef /*@abstract@*/ struct StringBufRec *StringBuf; #ifdef __cplusplus diff --git a/lib/stubs.c b/lib/stubs.c index 9a89691..a921d0a 100644 --- a/lib/stubs.c +++ b/lib/stubs.c @@ -1,3 +1,7 @@ +/** + * \file lib/stubs.c + */ + /* XXX Portable shared libraries require rpmlib to contain these functions. */ #include "system.h" diff --git a/lib/tagName.c b/lib/tagName.c index 202914d..365db28 100644 --- a/lib/tagName.c +++ b/lib/tagName.c @@ -1,3 +1,7 @@ +/** + * \file lib/tagName.c + */ + #include "system.h" #include diff --git a/lib/tufdio.c b/lib/tufdio.c index 0e266be..ef64fb4 100644 --- a/lib/tufdio.c +++ b/lib/tufdio.c @@ -1,3 +1,7 @@ +/** \ingroup rpmio + * \file lib/tufdio.c + */ + #include "system.h" #include diff --git a/lib/uninstall.c b/lib/uninstall.c index ef14682..09384c5 100644 --- a/lib/uninstall.c +++ b/lib/uninstall.c @@ -1,3 +1,7 @@ +/** \ingroup rpmtrans payload + * \file lib/uninstall.c + */ + #include "system.h" #include @@ -157,7 +161,7 @@ int removeBinaryPackage(const char * rootdir, rpmdb rpmdb, unsigned int offset, if (fnlen > fnmaxlen) fnmaxlen = fnlen; } - fnmaxlen += rootdir + sizeof("/"); /* XXX one byte too many */ + fnmaxlen += rdlen + sizeof("/"); /* XXX one byte too many */ fileName = alloca(fnmaxlen); diff --git a/lib/verify.c b/lib/verify.c index c35ba56..669242f 100644 --- a/lib/verify.c +++ b/lib/verify.c @@ -1,3 +1,7 @@ +/** \ingroup rpmcli + * \file lib/verify.c + */ + #include "system.h" #include -- 2.7.4