doxygen annotations.

- fix: more (possible) xstrdup side effects.

CVS patchset: 4186
CVS date: 2000/09/29 19:50:29

CHANGES

@@ -11,6 +11,7 @@
 	- fix: avoid calling getpass twice as side effect of xstrdup macro
 		(katzj@linuxpower.org) (#17672).
 	- handle possible db3 dependency on -lpthread more gracefully.
+	- fix: more (possible) xstrdup side effects.
 
 3.0.6 -> 4.0
 	- use DIRNAMES/BASENAMES/DIRINDICES not FILENAMES in packages and db.

lib/formats.c

@@ -514,7 +514,8 @@ static int i18nTag(Header h, int_32 tag, /*@out@*/ int_32 * type,
 	++_nl_msg_cat_cntr;
 
 	if (domain && msgid) {
-	    *data = xstrdup(/*@-unrecog@*/ dgettext(domain, msgid) /*@=unrecog@*/);
+	    *data = /*@-unrecog@*/ dgettext(domain, msgid) /*@=unrecog@*/;
+	    *data = xstrdup(*data);	/* XXX xstrdup has side effects. */
 	    *count = 1;
 	    *freeData = 1;
 	}

po/rpm.pot

@@ -6,7 +6,7 @@
 msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
-"POT-Creation-Date: 2000-09-26 10:31-0400\n"
+"POT-Creation-Date: 2000-09-29 14:55-0400\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -3799,84 +3799,84 @@ msgstr ""
 msgid "logging into %s as %s, pw %s\n"
 msgstr ""
 
-#: rpmio/macro.c:169
+#: rpmio/macro.c:183
 #, c-format
 msgid "======================== active %d empty %d\n"
 msgstr ""
 
 #. XXX just in case
-#: rpmio/macro.c:264
+#: rpmio/macro.c:297
 #, c-format
 msgid "%3d>%*s(empty)"
 msgstr ""
 
-#: rpmio/macro.c:299
+#: rpmio/macro.c:338
 #, c-format
 msgid "%3d<%*s(empty)\n"
 msgstr ""
 
-#: rpmio/macro.c:478
+#: rpmio/macro.c:551
 msgid "Macro %%%s has unterminated body"
 msgstr ""
 
-#: rpmio/macro.c:504
+#: rpmio/macro.c:577
 msgid "Macro %%%s has illegal name (%%define)"
 msgstr ""
 
-#: rpmio/macro.c:510
+#: rpmio/macro.c:583
 msgid "Macro %%%s has unterminated opts"
 msgstr ""
 
-#: rpmio/macro.c:515
+#: rpmio/macro.c:588
 msgid "Macro %%%s has empty body"
 msgstr ""
 
-#: rpmio/macro.c:520
+#: rpmio/macro.c:593
 msgid "Macro %%%s failed to expand"
 msgstr ""
 
-#: rpmio/macro.c:545
+#: rpmio/macro.c:624
 msgid "Macro %%%s has illegal name (%%undefine)"
 msgstr ""
 
-#: rpmio/macro.c:622
+#: rpmio/macro.c:717
 msgid "Macro %%%s (%s) was not used below level %d"
 msgstr ""
 
-#: rpmio/macro.c:706
+#: rpmio/macro.c:809
 #, c-format
 msgid "Unknown option %c in %s(%s)"
 msgstr ""
 
-#: rpmio/macro.c:864
+#: rpmio/macro.c:985
 #, c-format
 msgid "Recursion depth(%d) greater than max(%d)"
 msgstr ""
 
-#: rpmio/macro.c:930 rpmio/macro.c:946
+#: rpmio/macro.c:1051 rpmio/macro.c:1067
 #, c-format
 msgid "Unterminated %c: %s"
 msgstr ""
 
-#: rpmio/macro.c:986
+#: rpmio/macro.c:1107
 msgid "A %% is followed by an unparseable macro"
 msgstr ""
 
-#: rpmio/macro.c:1112
+#: rpmio/macro.c:1233
 msgid "Macro %%%.*s not found, skipping"
 msgstr ""
 
-#: rpmio/macro.c:1193
+#: rpmio/macro.c:1314
 msgid "Target buffer overflow"
 msgstr ""
 
 #. XXX Fstrerror
-#: rpmio/macro.c:1373 rpmio/macro.c:1379
+#: rpmio/macro.c:1493 rpmio/macro.c:1499
 #, c-format
 msgid "File %s: %s"
 msgstr ""
 
-#: rpmio/macro.c:1382
+#: rpmio/macro.c:1502
 #, c-format
 msgid "File %s is smaller than %d bytes"
 msgstr ""
@@ -3925,22 +3925,22 @@ msgstr ""
 msgid "Password for %s@%s: "
 msgstr ""
 
-#: rpmio/url.c:247 rpmio/url.c:273
+#: rpmio/url.c:248 rpmio/url.c:274
 #, c-format
 msgid "error: %sport must be a number\n"
 msgstr ""
 
-#: rpmio/url.c:409
+#: rpmio/url.c:410
 msgid "url port must be a number\n"
 msgstr ""
 
-#: rpmio/url.c:449
+#: rpmio/url.c:450
 #, c-format
 msgid "failed to open %s: %s\n"
 msgstr ""
 
 #. XXX Fstrerror
-#: rpmio/url.c:466
+#: rpmio/url.c:467
 #, c-format
 msgid "failed to create %s: %s\n"
 msgstr ""

rpmio/macro.c

@@ -56,7 +56,7 @@ struct MacroContext rpmGlobalMacroContext;
 struct MacroContext rpmCLIMacroContext;
 
 /**
- * Macro expansion data structure.
+ * Macro expansion state.
  */
 typedef struct MacroBuf {
 	const char *s;		/*!< Text to expand. */
@@ -88,6 +88,12 @@ int print_expand_trace = 0;
 
 /* =============================================================== */
 
+/**
+ * Compare macro entries by name (qsort/bsearch).
+ * @param ap		1st macro entry
+ * @param bp		2nd macro entry
+ * @return		result of comparison
+ */
 static int
 compareMacroName(const void *ap, const void *bp)
 {
@@ -103,6 +109,10 @@ compareMacroName(const void *ap, const void *bp)
 	return strcmp(ame->name, bme->name);
 }
 
+/**
+ * Enlarge macro table.
+ * @param mc		macro context
+ */
 static void
 expandMacroTable(MacroContext *mc)
 {
@@ -120,6 +130,10 @@ expandMacroTable(MacroContext *mc)
 	memset(&mc->macroTable[mc->firstFree], 0, MACRO_CHUNK_SIZE * sizeof(*(mc->macroTable)));
 }
 
+/**
+ * Sort entries in macro table.
+ * @param mc		macro context
+ */
 static void
 sortMacroTable(MacroContext *mc)
 {
@@ -170,6 +184,13 @@ rpmDumpMacroTable(MacroContext * mc, FILE * fp)
 		nactive, nempty);
 }
 
+/**
+ * Find entry in macro table.
+ * @param mc		macro context
+ * @param name		macro name
+ * @param namelen	no. of byes
+ * @return		address of slot in macro table with name (or NULL)
+ */
 static MacroEntry **
 findEntry(MacroContext *mc, const char *name, size_t namelen)
 {
@@ -198,8 +219,9 @@ findEntry(MacroContext *mc, const char *name, size_t namelen)
 
 /* =============================================================== */
 
-/* fgets analogue that reads \ continuations. Last newline always trimmed. */
+/**
-
+ * fgets(3) analogue that reads \ continuations. Last newline always trimmed.
+ */
 static char *
 rdcl(char *buf, size_t size, FD_t fd, int escapes)
 {
@@ -232,8 +254,13 @@ rdcl(char *buf, size_t size, FD_t fd, int escapes)
 	return (nread > 0 ? buf : NULL);
 }
 
-/* Return text between pl and matching pr */
+/**
-
+ * Return text between pl and matching pr.
+ * @param p		start of text
+ * @param pl		left char, i.e. '[', '(', '{', etc.
+ * @param pr		right char, i.e. ']', ')', '}', etc.
+ * @return		address of last char before pr (or NULL)
+ */
 static const char *
 matchchar(const char *p, char pl, char pr)
 {
@@ -253,6 +280,12 @@ matchchar(const char *p, char pl, char pr)
 	return (const char *)NULL;
 }
 
+/**
+ * Pre-print macro expression to be expanded.
+ * @param mb		macro expansion state
+ * @param s		current expansion string
+ * @param se		end of string
+ */
 static void
 printMacro(MacroBuf *mb, const char *s, const char *se)
 {
@@ -289,6 +322,12 @@ printMacro(MacroBuf *mb, const char *s, const char *se)
 	fprintf(stderr, "\n");
 }
 
+/**
+ * Post-print expanded macro expression.
+ * @param mb		macro expansion state
+ * @param t		current expansion string result
+ * @param te		end of string
+ */
 static void
 printExpansion(MacroBuf *mb, const char *t, const char *te)
 {
@@ -355,7 +394,13 @@ printExpansion(MacroBuf *mb, const char *t, const char *te)
 	*(_be) = '\0';		\
     }
 
-/* Save source and expand field into target */
+/**
+ * Save source and expand field into target.
+ * @param mb		macro expansion state
+ * @param f		field
+ * @param flen		no. bytes in field
+ * @return		result of expansion
+ */
 static int
 expandT(MacroBuf *mb, const char *f, size_t flen)
 {
@@ -375,7 +420,13 @@ expandT(MacroBuf *mb, const char *f, size_t flen)
 }
 
 #if 0
-/* Save target and expand sbuf into target */
+/**
+ * Save target and expand sbuf into target.
+ * @param mb		macro expansion state
+ * @param tbuf		target buffer
+ * @param tbuflen	no. bytes in target buffer
+ * @return		result of expansion
+ */
 static int
 expandS(MacroBuf *mb, char *tbuf, size_t tbuflen)
 {
@@ -392,6 +443,13 @@ expandS(MacroBuf *mb, char *tbuf, size_t tbuflen)
 }
 #endif
 
+/**
+ * Save source/target and expand macro in u.
+ * @param mb		macro expansion state
+ * @param u		input macro, output expansion
+ * @param ulen		no. bytes in u buffer
+ * @return		result of expansion
+ */
 static int
 expandU(MacroBuf *mb, char *u, size_t ulen)
 {
@@ -420,6 +478,13 @@ expandU(MacroBuf *mb, char *u, size_t ulen)
 	return rc;
 }
 
+/**
+ * Expand output of shell command into target buffer.
+ * @param mb		macro expansion state
+ * @param cmd		shell command
+ * @param clen		no. bytes in shell command
+ * @return		result of expansion
+ */
 static int
 doShellEscape(MacroBuf *mb, const char *cmd, size_t clen)
 {
@@ -448,6 +513,14 @@ doShellEscape(MacroBuf *mb, const char *cmd, size_t clen)
 	return 0;
 }
 
+/**
+ * Parse (and execute) new macro definition.
+ * @param mb		macro expansion state
+ * @param se		macro definition to parse
+ * @param level		macro recursion level
+ * @param expandbody	should body be expanded?
+ * @return		address to continue parsing
+ */
 static const char *
 doDefine(MacroBuf *mb, const char *se, int level, int expandbody)
 {
@@ -526,6 +599,12 @@ doDefine(MacroBuf *mb, const char *se, int level, int expandbody)
 	return se;
 }
 
+/**
+ * Parse (and execute) macro undefinition.
+ * @param mc		macro context
+ * @param se		macro name to undefine
+ * @return		address to continue parsing
+ */
 static const char *
 doUndefine(MacroContext *mc, const char *se)
 {
@@ -565,6 +644,14 @@ dumpME(const char *msg, MacroEntry *me)
 }
 #endif
 
+/**
+ * Push new macro definition onto macro entry stack.
+ * @param mep		address of macro entry slot
+ * @param n		macro name
+ * @param o		macro parameters (NULL if none)
+ * @param b		macro body (NULL becomes "")
+ * @param level		macro recursion level
+ */
 static void
 pushMacro(MacroEntry **mep, const char *n, const char *o, const char *b, int level)
 {
@@ -580,6 +667,10 @@ pushMacro(MacroEntry **mep, const char *n, const char *o, const char *b, int lev
 	*mep = me;
 }
 
+/**
+ * Pop macro definition from macro entry stack.
+ * @param mep		address of macro entry slot
+ */
 static void
 popMacro(MacroEntry **mep)
 {
@@ -595,6 +686,10 @@ popMacro(MacroEntry **mep)
 	}
 }
 
+/**
+ * Free parsed arguments for parameterized macro.
+ * @param mb		macro expansion state
+ */
 static void
 freeArgs(MacroBuf *mb)
 {
@@ -633,6 +728,14 @@ freeArgs(MacroBuf *mb)
 		sortMacroTable(mc);
 }
 
+/**
+ * Parse arguments (to next new line) for parameterized macro.
+ * @param mb		macro expansion state
+ * @param me		macro entry slot
+ * @param se		arguments to parse
+ * @param lastc		stop parsing at lastc
+ * @return		address to continue parsing
+ */
 static const char *
 grabArgs(MacroBuf *mb, const MacroEntry *me, const char *se, char lastc)
 {
@@ -742,6 +845,13 @@ grabArgs(MacroBuf *mb, const MacroEntry *me, const char *se, char lastc)
     return se;
 }
 
+/**
+ * Perform macro message output
+ * @param mb		macro expansion state
+ * @param waserror	use rpmError()?
+ * @param msg		message to ouput
+ * @param msglen	no. of bytes in message
+ */
 static void
 doOutput(MacroBuf *mb, int waserror, const char *msg, size_t msglen)
 {
@@ -756,6 +866,15 @@ doOutput(MacroBuf *mb, int waserror, const char *msg, size_t msglen)
 		fprintf(stderr, "%s", buf);
 }
 
+/**
+ * Execute macro primitives.
+ * @param mb		macro expansion state
+ * @param negate	should logic be inverted?
+ * @param f		beginning of field f
+ * @param fn		length of field f
+ * @param g		beginning of field g
+ * @param gn		length of field g
+ */
 static void
 doFoo(MacroBuf *mb, int negate, const char *f, size_t fn, const char *g, size_t glen)
 {
@@ -841,8 +960,10 @@ doFoo(MacroBuf *mb, int negate, const char *f, size_t fn, const char *g, size_t
 }
 
 /**
- * The main recursion engine.
+ * The main macro recursion loop.
  * @todo Dynamically reallocate target buffer.
+ * @param mb		macro expansion state
+ * @return		0 on success, 1 on failure
  */
 static int
 expandMacro(MacroBuf *mb)
@@ -1248,7 +1369,6 @@ rpmDefineMacro(MacroContext *mc, const char *macro, int level)
 	return 0;
 }
 
-/* Load a macro context into rpmGlobalMacroContext */
 void
 rpmLoadMacros(MacroContext * mc, int level)
 {
@@ -1406,7 +1526,7 @@ int isCompressed(const char *file, int *compressed)
 }
 
 /* =============================================================== */
-/* Return concatenated and expanded macro list */
+
 char * 
 rpmExpand(const char *arg, ...)
 {
@@ -1455,7 +1575,7 @@ rpmExpandNumeric(const char *arg)
     return rc;
 }
 
-/* XXX FIXME: ../sbin/./../bin/ */
+/* @todo "../sbin/./../bin/" not correct. */
 char *rpmCleanPath(char * path)
 {
     const char *s;
@@ -1531,6 +1651,7 @@ char *rpmCleanPath(char * path)
 }
 
 /* Return concatenated and expanded canonical path. */
+
 const char *
 rpmGetPath(const char *path, ...)
 {
@@ -1554,7 +1675,8 @@ rpmGetPath(const char *path, ...)
     va_end(ap);
     expandMacros(NULL, NULL, buf, sizeof(buf));
 
-    return xstrdup( rpmCleanPath(buf) );
+    (void) rpmCleanPath(buf);
+    return xstrdup(buf);	/* XXX xstrdup has side effects. */
 }
 
 /* Merge 3 args into path, any or all of which may be a url. */

rpmio/rpmio.h

@@ -35,6 +35,9 @@ extern "C" {
  * \name RPMIO Vectors.
  */
 /*@{*/
+
+/** \ingroup rpmio
+ */
 typedef ssize_t fdio_read_function_t (void *cookie, char *buf, size_t nbytes);
 
 /** \ingroup rpmio
@@ -98,6 +101,9 @@ typedef int fdio_fflush_function_t (FD_t fd);
  * \name RPMRPC Vectors.
  */
 /*@{*/
+
+/** \ingroup rpmio
+ */
 typedef int fdio_mkdir_function_t (const char * path, mode_t mode);
 
 /** \ingroup rpmrpc
@@ -163,19 +169,23 @@ struct FDIO_s {
 /*@{*/
 
 /** \ingroup rpmio
+ * strerror(3) clone.
  */
 /*@observer@*/ const char * Fstrerror(FD_t fd);
 
 /** \ingroup rpmio
+ * fread(3) clone.
  */
 size_t	Fread	(/*@out@*/ void * buf, size_t size, size_t nmemb, FD_t fd);
 
 /** \ingroup rpmio
+ * fwrite(3) clone.
  */
 size_t	Fwrite	(const void *buf, size_t size, size_t nmemb, FD_t fd);
 
 
 /** \ingroup rpmio
+ * fseek(3) clone.
  */
 #ifdef USE_COOKIE_SEEK_POINTER
 int	Fseek	(FD_t fd, _IO_off64_t offset, int whence);
@@ -184,6 +194,7 @@ int	Fseek	(FD_t fd, off_t offset, int whence);
 #endif
 
 /** \ingroup rpmio
+ * fclose(3) clone.
  */
 int	Fclose	( /*@killref@*/ FD_t fd);
 
@@ -192,28 +203,34 @@ int	Fclose	( /*@killref@*/ FD_t fd);
 FD_t	Fdopen	(FD_t fd, const char * fmode);
 
 /** \ingroup rpmio
+ * fopen(3) clone.
  */
 FD_t	Fopen	(const char * path, const char * fmode);
 
 
 /** \ingroup rpmio
+ * fflush(3) clone.
  */
 int	Fflush	(FD_t fd);
 
 /** \ingroup rpmio
+ * ferror(3) clone.
  */
 int	Ferror	(FD_t fd);
 
 /** \ingroup rpmio
+ * fileno(3) clone.
  */
 int	Fileno	(FD_t fd);
 
 
 /** \ingroup rpmio
+ * fcntl(2) clone.
  */
-int	Fcntl	(FD_t, int op, void *lip);
+int	Fcntl	(FD_t fd, int op, void *lip);
 
 /** \ingroup rpmio
+ * pread(2) clone.
  */
 #ifdef USE_COOKIE_SEEK_POINTER
 ssize_t Pread(FD_t fd, void * buf, size_t count, _IO_off64_t offset);
@@ -222,6 +239,7 @@ ssize_t Pread(FD_t fd, void * buf, size_t count, off_t offset);
 #endif
 
 /** \ingroup rpmio
+ * pwrite(2) clone.
  */
 #ifdef USE_COOKIE_SEEK_POINTER
 ssize_t Pwrite(FD_t fd, const void * buf, size_t count, _IO_off64_t offset);
@@ -234,65 +252,83 @@ ssize_t Pwrite(FD_t fd, const void * buf, size_t count, off_t offset);
  * \name RPMRPC Interface.
  */
 /*@{*/
+
+/** \ingroup rpmrpc
+ * mkdir(2) clone.
+ */
 int	Mkdir	(const char * path, mode_t mode);
 
 /** \ingroup rpmrpc
+ * chdir(2) clone.
  */
 int	Chdir	(const char * path);
 
 /** \ingroup rpmrpc
+ * rmdir(2) clone.
  */
 int	Rmdir	(const char * path);
 
 /** \ingroup rpmrpc
+ * rename(2) clone.
  */
 int	Rename	(const char * oldpath, const char * newpath);
 
 /** \ingroup rpmrpc
+ * link(2) clone.
  */
 int	Link	(const char * oldpath, const char * newpath);
 
 /** \ingroup rpmrpc
+ * unlink(2) clone.
  */
 int	Unlink	(const char * path);
 
 /** \ingroup rpmrpc
+ * readlink(2) clone.
  */
 int	Readlink(const char * path, char * buf, size_t bufsiz);
 
 
 /** \ingroup rpmrpc
+ * stat(2) clone.
  */
 int	Stat	(const char * path, /*@out@*/ struct stat * st);
 
 /** \ingroup rpmrpc
+ * lstat(2) clone.
  */
 int	Lstat	(const char * path, /*@out@*/ struct stat * st);
 
 /** \ingroup rpmrpc
+ * access(2) clone.
  */
 int	Access	(const char * path, int amode);
 
 
 /** \ingroup rpmrpc
+ * glob(3) clone.
  */
 int	Glob	(const char * pattern, int flags,
 		int errfunc(const char * epath, int eerrno), /*@out@*/ glob_t * pglob);
 
 /** \ingroup rpmrpc
+ * globfree(3) clone.
  */
 void	Globfree( /*@only@*/ glob_t * pglob);
 
 
 /** \ingroup rpmrpc
+ * opendir(3) clone.
  */
 DIR *	Opendir	(const char * name);
 
 /** \ingroup rpmrpc
+ * readdir(3) clone.
  */
 struct dirent *	Readdir	(DIR * dir);
 
 /** \ingroup rpmrpc
+ * closedir(3) clone.
  */
 int	Closedir(DIR * dir);
 /*@}*/
@@ -302,8 +338,10 @@ int	Closedir(DIR * dir);
  * \name RPMIO Utilities.
  */
 /*@{*/
-off_t	fdSize	(FD_t fd);
 
+/** \ingroup rpmio
+ */
+off_t	fdSize	(FD_t fd);
 
 /** \ingroup rpmio
  */
@@ -314,7 +352,6 @@ off_t	fdSize	(FD_t fd);
 
 /* XXX Legacy interfaces needed by gnorpm, rpmfind et al */
 
-
 /** \ingroup rpmio
  */
 /*@-shadow@*/

rpmio/rpmmacro.h

@@ -7,23 +7,23 @@
 
 /*! The structure used to store a macro. */
 typedef /*@abstract@*/ struct MacroEntry {
-	struct MacroEntry *prev;/*!< Macro entry stack. */
+    struct MacroEntry *prev;/*!< Macro entry stack. */
-	const char *name;	/*!< Macro name. */
+    const char *name;	/*!< Macro name. */
-	const char *opts;	/*!< Macro parameters (a la getopt) */
+    const char *opts;	/*!< Macro parameters (a la getopt) */
-	const char *body;	/*!< Macro body. */
+    const char *body;	/*!< Macro body. */
-	int	used;		/*!< No. of expansions. */
+    int	used;		/*!< No. of expansions. */
-	int	level;		/*!< Scoping level. */
+    int	level;		/*!< Scoping level. */
 } MacroEntry;
 
 /*! The structure used to store the set of macros in a context. */
 typedef /*@abstract@*/ struct MacroContext {
-	MacroEntry **	macroTable;	/*!< Macro entry table for context. */
+    MacroEntry **macroTable;	/*!< Macro entry table for context. */
-	int		macrosAllocated;/*!< No. of allocated macros. */
+    int		macrosAllocated;/*!< No. of allocated macros. */
-	int		firstFree;	/*!< No. of macros. */
+    int		firstFree;	/*!< No. of macros. */
 } MacroContext;
 
-/*
+/**
- * Markers for types of macros added throughout rpm.
+ * Markers for sources of macros added throughout rpm.
  */
 #define	RMIL_DEFAULT	-15
 #define	RMIL_MACROFILES	-13
@@ -40,44 +40,79 @@ extern "C" {
 #endif
 
 /**
+ * Print macros to file stream.
+ * @param mc		macro context (NULL uses global context).
+ * @param fp		file stream
  */
 void	rpmDumpMacroTable	(MacroContext * mc, FILE * fp);
 
 /**
+ * Return value of macro.
  * @deprecated Used only in build/expression.c.
  * @todo Eliminate.
+ * @param mc		macro context (NULL uses global context).
+ * @param name		macro name
+ * @return		macro body
  */
 const char *getMacroBody (MacroContext *mc, const char *name);
 
 /**
+ * Expand macro into buffer.
  * @deprecated Use rpmExpand().
  * @todo Eliminate from API.
+ * @param spec		cookie (unused)
+ * @param mc		macro context (NULL uses global context).
+ * @retval sbuf		input macro to expand, output expansion
+ * @param sbuflen	size of buffer
+ * @return		0 on success
  */
 int	expandMacros	(void * spec, MacroContext * mc, char * sbuf,
 				size_t sbuflen);
 
 /**
+ * Add macro to context.
+ * @deprecated Use rpmDefineMacro().
+ * @param mc		macro context (NULL uses global context).
+ * @param n		macro name
+ * @param o		macro paramaters
+ * @param b		macro body
+ * @param level		macro recursion level (0 is entry API)
  */
 void	addMacro	(MacroContext * mc, const char * n, const char * o,
-				const char * b, int depth);
+				const char * b, int level);
 
 /**
+ * Delete macro from context.
+ * @param mc		macro context (NULL uses global context).
+ * @param n		macro name
  */
 void	delMacro	(MacroContext * mc, const char * n);
 
 /**
+ * Define macro in context.
+ * @param mc		macro context (NULL uses global context).
+ * @param n		macro name, options, body
+ * @param level		macro recursion level (0 is entry API)
  */
 int	rpmDefineMacro	(MacroContext * mc, const char * macro, int level);
 
 /**
+ * Load macros from context into global context.
+ * @param mc		macro context (NULL does nothing).
+ * @param level		macro recursion level (0 is entry API)
  */
 void	rpmLoadMacros	(MacroContext *mc, int level);
 
 /**
+ * Initialize macro context from set of macrofile(s).
+ * @param mc		macro context (NULL uses global context).
+ * @param macrofiles	colon separated list of macro files (NULL does nothing)
  */
 void	rpmInitMacros	(MacroContext * mc, const char * macrofiles);
 
 /**
+ * Destroy macro context.
+ * @param mc		macro context (NULL uses global context).
  */
 void	rpmFreeMacros	(MacroContext * mc);
 
@@ -86,27 +121,53 @@ void	rpmFreeMacros	(MacroContext * mc);
 #define COMPRESSED_BZIP2 2
 
 /**
+ * Return type of compression used in file.
+ * @param file		name of file
+ * @retval compressed	address of compression type
+ * @return		0 on success, 1 on I/O error
  */
 int	isCompressed	(const char * file, int * compressed);
 
 /**
+ * Return (malloc'ed) concatenated macro expansion(s).
+ * @param arg		macro(s) to expand (NULL terminates list)
+ * @return		macro expansion (malloc'ed)
  */
 char *	rpmExpand	(const char * arg, ...);
 
 /**
+ * Canonicalize file path.
+ * @param path		path to canonicalize (in-place)
+ * @return		canonicalized path (malloc'ed)
  */
 char *	rpmCleanPath	(char * path);
 
 /**
+ * Return (malloc'ed) expanded, canonicalized, file path.
+ * @param path		macro(s) to expand (NULL terminates list)
+ * @return		canonicalized path (malloc'ed)
  */
 const char *rpmGetPath	(const char * path, ...);
 
 /**
+ * Merge 3 args into path, any or all of which may be a url.
+ * The leading part of the first URL encountered is used
+ * for the result, other URL's are discarded, permitting
+ * a primitive form of inheiritance.
+ * @param root		root URL (often path to chroot, or NULL)
+ * @param mdir		directory URL (often a directory, or NULL)
+ * @param file		file URL (often a file, or NULL)
+ * @return		expanded, merged, canonicalized path (malloc'ed)
  */
 const char *rpmGenPath	(const char * root, const char * mdir,
 				const char * file);
 
 /**
+ * Return macro expansion as a numeric value.
+ * Boolean values ('Y' or 'y' returns 1, 'N' or 'n' returns 0)
+ * are permitted as well. An undefined macro returns 0.
+ * @param arg		macro to expand
+ * @return		numeric value
  */
 int	rpmExpandNumeric (const char * arg);
 

rpmio/url.c

@@ -221,9 +221,8 @@ static void urlFind(urlinfo *uret, int mustAsk)
 	    prompt = alloca(strlen(u->host) + strlen(u->user) + 256);
 	    sprintf(prompt, _("Password for %s@%s: "), u->user, u->host);
 	    if (u->password)	xfree(u->password);
-	    /* XXX xstrdup has side effects. */
 	    u->password = /*@-unrecog@*/ getpass(prompt) /*@=unrecog@*/;
-	    u->password = xstrdup(u->password);
+	    u->password = xstrdup(u->password);	/* XXX xstrdup has side effects. */
 	}
 
 	if (u->proxyh == NULL) {