Documentation comments.

CVS patchset: 3537
CVS date: 2000/01/24 22:13:45

2 files changed, 57 insertions, 19 deletions

diff --git a/lib/cpio.c b/lib/cpio.c
index 2f5f676f0..93c49728f 100644
--- a/lib/cpio.c
+++ b/lib/cpio.c
@@ -11,6 +11,7 @@
    should both be the same, but really odd things are going to happen if
    that's not true! */
 
+/** */
 struct hardLink {
     struct hardLink * next;
     const char ** files;	/* nlink of these, used by install */
@@ -23,6 +24,7 @@ struct hardLink {
     struct stat sb;
 };
 
+/** */
 struct cpioCrcPhysicalHeader {
     char magic[6];
     char inode[8];
@@ -42,6 +44,7 @@ struct cpioCrcPhysicalHeader {
 
 #define	PHYS_HDR_SIZE	110		/* don't depend on sizeof(struct) */
 
+/** */
 struct cpioHeader {
     ino_t inode;
     mode_t mode;
@@ -54,6 +57,7 @@ struct cpioHeader {
     /*@owned@*/char * path;
 };
 
+/** */
 static inline off_t saferead(FD_t cfd, /*@out@*/void * vbuf, size_t amount)
 {
     off_t rc = 0;
@@ -74,6 +78,7 @@ static inline off_t saferead(FD_t cfd, /*@out@*/void * vbuf, size_t amount)
     return rc;
 }
 
+/** */
 static inline off_t ourread(FD_t cfd, /*@out@*/void * buf, size_t size)
 {
     off_t i = saferead(cfd, buf, size);
@@ -82,6 +87,7 @@ static inline off_t ourread(FD_t cfd, /*@out@*/void * buf, size_t size)
     return i;
 }
 
+/** */
 static inline void padinfd(FD_t cfd, int modulo)
 {
     int buf[10];
@@ -91,6 +97,7 @@ static inline void padinfd(FD_t cfd, int modulo)
     (void)ourread(cfd, buf, amount);
 }
 
+/** */
 static inline off_t safewrite(FD_t cfd, const void * vbuf, size_t amount)
 {
     off_t rc = 0;
@@ -112,6 +119,7 @@ static inline off_t safewrite(FD_t cfd, const void * vbuf, size_t amount)
     return rc; 
 }
 
+/** */
 static inline int padoutfd(FD_t cfd, size_t * where, int modulo)
 {
     static int buf[10] = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 };
@@ -125,6 +133,7 @@ static inline int padoutfd(FD_t cfd, size_t * where, int modulo)
     return 0;
 }
 
+/** */
 static int strntoul(const char *str, /*@out@*/char **endptr, int base, int num)
 {
     char * buf, * end;
@@ -150,6 +159,7 @@ static int strntoul(const char *str, /*@out@*/char **endptr, int base, int num)
 	sprintf(space, "%8.8lx", (unsigned long) (val)); \
 	memcpy(phys, space, 8);
 
+/** */
 static int getNextHeader(FD_t cfd, /*@out@*/ struct cpioHeader * chPtr)
 {
     struct cpioCrcPhysicalHeader physHeader;
@@ -196,6 +206,7 @@ static int getNextHeader(FD_t cfd, /*@out@*/ struct cpioHeader * chPtr)
     return 0;
 }
 
+/** */
 int cpioFileMapCmp(const void * a, const void * b)
 {
     const struct cpioFileMapping * first = a;
@@ -205,6 +216,7 @@ int cpioFileMapCmp(const void * a, const void * b)
 }
 
 /* This could trash files in the path! I'm not sure that's a good thing */
+/** */
 static int createDirectory(char * path, mode_t perms)
 {
     struct stat sb;
@@ -241,6 +253,7 @@ static int createDirectory(char * path, mode_t perms)
     return 0;
 }
 
+/** */
 static int setInfo(struct cpioHeader * hdr)
 {
     int rc = 0;
@@ -266,6 +279,7 @@ static int setInfo(struct cpioHeader * hdr)
     return rc;
 }
 
+/** */
 static int checkDirectory(const char * filename)
 {
     /*@only@*/ static char * lastDir = NULL;	/* XXX memory leak */
@@ -311,6 +325,7 @@ static int checkDirectory(const char * filename)
     return rc;
 }
 
+/** */
 static int expandRegular(FD_t cfd, struct cpioHeader * hdr,
 			 cpioCallback cb, void * cbData)
 {
@@ -375,6 +390,7 @@ static int expandRegular(FD_t cfd, struct cpioHeader * hdr,
     return rc;
 }
 
+/** */
 static int expandSymlink(FD_t cfd, struct cpioHeader * hdr)
 {
     char buf[2048], buf2[2048];
@@ -408,6 +424,7 @@ static int expandSymlink(FD_t cfd, struct cpioHeader * hdr)
     return 0;
 }
 
+/** */
 static int expandFifo( /*@unused@*/ FD_t cfd, struct cpioHeader * hdr)
 {
     struct stat sb;
@@ -425,6 +442,7 @@ static int expandFifo( /*@unused@*/ FD_t cfd, struct cpioHeader * hdr)
     return 0; 
 }
 
+/** */
 static int expandDevice( /*@unused@*/ FD_t cfd, struct cpioHeader * hdr)
 {
     struct stat sb;
@@ -443,6 +461,7 @@ static int expandDevice( /*@unused@*/ FD_t cfd, struct cpioHeader * hdr)
     return 0;
 }
 
+/** */
 static void freeLink( /*@only@*/ struct hardLink * li)
 {
     int i;
@@ -455,6 +474,7 @@ static void freeLink( /*@only@*/ struct hardLink * li)
     free(li->files);
 }
 
+/** */
 static int createLinks(struct hardLink * li, /*@out@*/const char ** failedFile)
 {
     int i;
@@ -486,6 +506,7 @@ static int createLinks(struct hardLink * li, /*@out@*/const char ** failedFile)
     return 0;
 }
 
+/** */
 static int eatBytes(FD_t cfd, int amount)
 {
     char buf[4096];
@@ -501,6 +522,7 @@ static int eatBytes(FD_t cfd, int amount)
     return 0;
 }
 
+/** */
 int cpioInstallArchive(FD_t cfd, struct cpioFileMapping * mappings, 
 		       int numMappings, cpioCallback cb, void * cbData,
 		       const char ** failedFile)
@@ -681,6 +703,7 @@ int cpioInstallArchive(FD_t cfd, struct cpioFileMapping * mappings,
     return rc;
 }
 
+/** */
 static int writeFile(FD_t cfd, struct stat sb, struct cpioFileMapping * map, 
 		     /*@out@*/size_t * sizep, int writeData)
 {
@@ -816,6 +839,7 @@ static int writeFile(FD_t cfd, struct stat sb, struct cpioFileMapping * map,
     return 0;
 }
 
+/** */
 static int writeLinkedFile(FD_t cfd, struct hardLink * hlink, 
 			   struct cpioFileMapping * mappings,
 			   cpioCallback cb, void * cbData,
@@ -866,6 +890,7 @@ static int writeLinkedFile(FD_t cfd, struct hardLink * hlink,
     return 0;
 }
 
+/** */
 int cpioBuildArchive(FD_t cfd, struct cpioFileMapping * mappings, 
 		     int numMappings, cpioCallback cb, void * cbData,
 		     unsigned int * archiveSize, const char ** failedFile)
@@ -979,6 +1004,7 @@ int cpioBuildArchive(FD_t cfd, struct cpioFileMapping * mappings,
     return 0;
 }
 
+/** */
 const char * cpioStrerror(int rc)
 {
     static char msg[256];
@@ -1022,7 +1048,7 @@ const char * cpioStrerror(int rc)
 	if (l > 0) strncat(msg, s, l);
 	l -= strlen(s);
     }
-    if (rc & CPIOERR_CHECK_ERRNO) {
+    if ((rc & CPIOERR_CHECK_ERRNO) && myerrno) {
 	s = _(" failed - ");
 	if (l > 0) strncat(msg, s, l);
 	l -= strlen(s);
diff --git a/lib/cpio.h b/lib/cpio.h
index 99dfd6429..ed19f89d8 100644
--- a/lib/cpio.h
+++ b/lib/cpio.h
@@ -1,11 +1,6 @@
 #ifndef H_CPIO
 #define H_CPIO
 
-#include <zlib.h>
-#include <sys/types.h>
-
-#include <rpmio.h>
-
 /** \file lib/cpio.h
  *  Structures used to handle cpio payloads within rpm packages.
  *
@@ -17,9 +12,15 @@
  *
  */
 
-/* Note the CPIO_CHECK_ERRNO bit is set only if errno is valid. These have to
-   be positive numbers or this setting the high bit stuff is a bad idea. */
+#include <zlib.h>
+#include <sys/types.h>
 
+#include <rpmio.h>
+
+/**
+ * Note:  CPIO_CHECK_ERRNO bit is set only if errno is valid. These have to
+ * be positive numbers or this setting the high bit stuff is a bad idea.
+ */
 #define CPIOERR_CHECK_ERRNO	0x00008000
 
 #define CPIOERR_BAD_MAGIC	(2			)
@@ -51,14 +52,16 @@
 #define CPIO_MAP_GID		(1 << 3)
 #define CPIO_FOLLOW_SYMLINKS	(1 << 4)  /* only for building */
 
-/*! The structure used to define a cpio payload file. */
+/** The structure used to define a cpio payload file. */
 struct cpioFileMapping {
+/*@{*/
     /*@owned@*/ const char * archivePath; /*!< Path to store in cpio archive. */
     /*@owned@*/ const char * fsPath;	/*!< Location of payload file. */
     mode_t finalMode;		/*!< Mode of payload file (from header). */
     uid_t finalUid;		/*!< Uid of payload file (from header). */
     gid_t finalGid;		/*!< Gid of payload file (from header). */
     int mapFlags;
+/*@}*/
 };
 
 /** The structure passed as first argument during a cpio progress callback.
@@ -66,35 +69,44 @@ struct cpioFileMapping {
  * Note: When building the cpio payload, only "file" is filled in.
  */
 struct cpioCallbackInfo {
+/*@{*/
     /*@dependent@*/ const char * file;	/*!< File name being installed. */
     long fileSize;			/*!< Total file size. */
     long fileComplete;			/*!< Amount of file unpacked. */
     long bytesProcessed;		/*!< No. bytes in archive read. */
+/*@}*/
 };
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-typedef void (*cpioCallback)(struct cpioCallbackInfo * filespec, void * data);
-
-/* If no mappings are passed, this installs everything! If one is passed
-   it should be sorted according to cpioFileMapCmp() and only files included
-   in the map are installed. Files are installed relative to the current
-   directory unless a mapping is given which specifies an absolute
-   directory. The mode mapping is only used for the permission bits, not
-   for the file type. The owner/group mappings are ignored for the nonroot
-   user. If *failedFile is non-NULL on return, it should be free()d. */
+typedef void (*cpioCallback) (struct cpioCallbackInfo * filespec, void * data);
+
+/**
+ * The RPM internal equivalent of the command line "cpio -i".
+ * If no mappings are passed, this installs everything! If one is passed
+ * it should be sorted according to cpioFileMapCmp() and only files included
+ * in the map are installed. Files are installed relative to the current
+ * directory unless a mapping is given which specifies an absolute
+ * directory. The mode mapping is only used for the permission bits, not
+ * for the file type. The owner/group mappings are ignored for the nonroot
+ * user. If *failedFile is non-NULL on return, it should be free()d.
+ */
 int cpioInstallArchive(FD_t cfd, struct cpioFileMapping * mappings,
 		       int numMappings, cpioCallback cb, void * cbData,
 		       /*@out@*/const char ** failedFile);
+/**
+ * The RPM internal equivalent of the command line "cpio -o".
+ */
 int cpioBuildArchive(FD_t cfd, struct cpioFileMapping * mappings,
 		     int numMappings, cpioCallback cb, void * cbData,
 		     unsigned int * archiveSize, /*@out@*/const char ** failedFile);
 
-/* This is designed to be qsort/bsearch compatible */
+/** This is designed to be qsort/bsearch compatible */
 int cpioFileMapCmp(const void * a, const void * b);
 
+/** */
 /*@observer@*/ const char *cpioStrerror(int rc);
 
 #ifdef __cplusplus