1 #ifndef H_HEADER 2 #define H_HEADER 3 4 /** \ingroup header 5 * \file lib/header.h 6 * 7 * An rpm header carries all information about a package. A header is 8 * a collection of data elements called tags. Each tag has a data type, 9 * and includes 1 or more values. 10 * 11 */ 12 13 /* RPM - Copyright (C) 1995-2001 Red Hat Software */ 14 15 #include <rpm/rpmio.h> 16 #include <rpm/rpmtypes.h> 17 #include <rpm/rpmtd.h> 18 #include <rpm/rpmutil.h> 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 /** \ingroup header 25 * Header magic value 26 */ 27 extern const unsigned char rpm_header_magic[8]; 28 29 /** \ingroup header 30 * Include calculation for 8 bytes of (magic, 0)? 31 */ 32 enum hMagic { 33 HEADER_MAGIC_NO = 0, 34 HEADER_MAGIC_YES = 1 35 }; 36 37 /** \ingroup header 38 * Create new (empty) header instance. 39 * @return header 40 */ 41 Header headerNew(void); 42 43 /** \ingroup header 44 * Dereference a header instance. 45 * @param h header 46 * @return NULL always 47 */ 48 Header headerFree( Header h); 49 50 /** \ingroup header 51 * Reference a header instance. 52 * @param h header 53 * @return new header reference 54 */ 55 Header headerLink(Header h); 56 57 /** \ingroup header 58 * Return size of on-disk header representation in bytes. 59 * @param h header 60 * @param magicp include size of 8 bytes for (magic, 0)? 61 * @return size of on-disk header 62 */ 63 unsigned int headerSizeof(Header h, int magicp); 64 65 /** \ingroup header 66 * Convert header to on-disk representation. 67 * @deprecated Use headerExport() instead 68 * @param h header (with pointers) 69 * @return on-disk header blob (i.e. with offsets) 70 */ 71 void * headerUnload(Header h); 72 73 /** \ingroup header 74 * Export header to on-disk representation. 75 * @param h header (with pointers) 76 * @retval bsize on-disk header blob size in bytes 77 * @return on-disk header blob (i.e. with offsets) 78 */ 79 void * headerExport(Header h, unsigned int * bsize); 80 81 /** \ingroup header 82 * Convert header to on-disk representation, and then reload. 83 * This is used to insure that all header data is in one chunk. 84 * @param h header (with pointers) 85 * @param tag region tag 86 * @return on-disk header (with offsets) 87 */ 88 Header headerReload(Header h, rpmTagVal tag); 89 90 /** \ingroup header 91 * Duplicate a header. 92 * @param h header 93 * @return new header instance 94 */ 95 Header headerCopy(Header h); 96 97 /** \ingroup header 98 * Convert header to in-memory representation. 99 * @deprecated Use headerImport() instead 100 * @param uh on-disk header blob (i.e. with offsets) 101 * @return header 102 */ 103 Header headerLoad(void * uh); 104 105 /** \ingroup header 106 * Make a copy and convert header to in-memory representation. 107 * @deprecated Use headerImport() instead 108 * @param uh on-disk header blob (i.e. with offsets) 109 * @return header 110 */ 111 Header headerCopyLoad(const void * uh); 112 113 enum headerImportFlags_e { 114 HEADERIMPORT_COPY = (1 << 0), /* Make copy of blob on import? */ 115 HEADERIMPORT_FAST = (1 << 1), /* Faster but less safe? */ 116 }; 117 118 typedef rpmFlags headerImportFlags; 119 120 /** \ingroup header 121 * Import header to in-memory representation. 122 * @param blob on-disk header blob (i.e. with offsets) 123 * @param bsize on-disk header blob size in bytes (0 if unknown) 124 * @param flags flags to control operation 125 * @return header 126 */ 127 Header headerImport(void *blob, unsigned int bsize, headerImportFlags flags); 128 129 /** \ingroup header 130 * Read (and load) header from file handle. 131 * @param fd file handle 132 * @param magicp read (and verify) 8 bytes of (magic, 0)? 133 * @return header (or NULL on error) 134 */ 135 Header headerRead(FD_t fd, int magicp); 136 137 /** \ingroup header 138 * Write (with unload) header to file handle. 139 * @param fd file handle 140 * @param h header 141 * @param magicp prefix write with 8 bytes of (magic, 0)? 142 * @return 0 on success, 1 on error 143 */ 144 int headerWrite(FD_t fd, Header h, int magicp); 145 146 /** \ingroup header 147 * Check if tag is in header. 148 * @param h header 149 * @param tag tag 150 * @return 1 on success, 0 on failure 151 */ 152 int headerIsEntry(Header h, rpmTagVal tag); 153 154 /** \ingroup header 155 * Modifier flags for headerGet() operation. 156 * For consistent behavior you'll probably want to use ALLOC to ensure 157 * the caller owns the data, but MINMEM is useful for avoiding extra 158 * copy of data when you are sure the header wont go away. 159 * Most of the time you'll probably want EXT too, but note that extensions 160 * tags don't generally honor the other flags, MINMEM, RAW, ALLOC and ARGV 161 * are only relevant for non-extension data. 162 */ 163 enum headerGetFlags_e { 164 HEADERGET_DEFAULT = 0, /* legacy headerGetEntry() behavior */ 165 HEADERGET_MINMEM = (1 << 0), /* pointers can refer to header memory */ 166 HEADERGET_EXT = (1 << 1), /* lookup extension types too */ 167 HEADERGET_RAW = (1 << 2), /* return raw contents (no i18n lookups) */ 168 HEADERGET_ALLOC = (1 << 3), /* always allocate memory for all data */ 169 HEADERGET_ARGV = (1 << 4), /* return string arrays NULL-terminated */ 170 }; 171 172 typedef rpmFlags headerGetFlags; 173 174 /** \ingroup header 175 * Retrieve tag value. 176 * @param h header 177 * @param tag tag 178 * @retval td tag data container 179 * @param flags retrieval modifier flags 180 * @return 1 on success, 0 on failure 181 */ 182 int headerGet(Header h, rpmTagVal tag, rpmtd td, headerGetFlags flags); 183 184 185 enum headerPutFlags_e { 186 HEADERPUT_DEFAULT = 0, 187 HEADERPUT_APPEND = (1 << 0), 188 }; 189 190 typedef rpmFlags headerPutFlags; 191 192 /** \ingroup header 193 * Add or append tag to header. 194 * 195 * @param h header 196 * @param td tag data container 197 * @param flags flags to control operation 198 * @return 1 on success, 0 on failure 199 */ 200 int headerPut(Header h, rpmtd td, headerPutFlags flags); 201 202 /** \ingroup header 203 * @{ 204 * Type-safe methods for inserting tag data to header. 205 * Tag data type is validated to match the function type, ie things like 206 * headerPutUint32(h, RPMTAG_NAME, ...) will return failure. For non-array 207 * types size must equal 1, and data is checked to be non-NULL. For array 208 * types, add-or-append mode is always used. 209 * 210 * headerPutString() can be used on both RPM_STRING_TYPE and 211 * RPM_STRING_ARRAY_TYPE (to add a single string into the array) tags, 212 * for others the type must match exactly. 213 * 214 * These are intended to "do the right thing" in the common case, if you 215 * need more fine grained control use headerPut() & friends instead. 216 * @todo Make doxygen group these meaningfully. 217 * 218 * @param h header 219 * @param tag tag to insert 220 * @param val pointer to value(s) 221 * @param size number of items in array (1 or larger) 222 * @return 1 on success, 0 on failure 223 * 224 */ 225 int headerPutBin(Header h, rpmTagVal tag, const uint8_t *val, rpm_count_t size); 226 int headerPutString(Header h, rpmTagVal tag, const char *val); 227 int headerPutStringArray(Header h, rpmTagVal tag, const char **val, rpm_count_t size); 228 int headerPutChar(Header h, rpmTagVal tag, const char *val, rpm_count_t size); 229 int headerPutUint8(Header h, rpmTagVal tag, const uint8_t *val, rpm_count_t size); 230 int headerPutUint16(Header h, rpmTagVal tag, const uint16_t *val, rpm_count_t size); 231 int headerPutUint32(Header h, rpmTagVal tag, const uint32_t *val, rpm_count_t size); 232 int headerPutUint64(Header h, rpmTagVal tag, const uint64_t *val, rpm_count_t size); 233 /** @} */ 234 235 /** \ingroup header 236 * Add locale specific tag to header. 237 * A NULL lang is interpreted as the C locale. Here are the rules: 238 * \verbatim 239 * - If the tag isn't in the header, it's added with the passed string 240 * as new value. 241 * - If the tag occurs multiple times in entry, which tag is affected 242 * by the operation is undefined. 243 * - If the tag is in the header w/ this language, the entry is 244 * *replaced* (like headerMod()). 245 * \endverbatim 246 * This function is intended to just "do the right thing". If you need 247 * more fine grained control use headerPut() and headerMod(). 248 * 249 * @param h header 250 * @param tag tag 251 * @param string tag value 252 * @param lang locale 253 * @return 1 on success, 0 on failure 254 */ 255 int headerAddI18NString(Header h, rpmTagVal tag, const char * string, 256 const char * lang); 257 258 /** \ingroup header 259 * Modify tag in header. 260 * If there are multiple entries with this tag, the first one gets replaced. 261 * @param h header 262 * @param td tag data container 263 * @return 1 on success, 0 on failure 264 */ 265 int headerMod(Header h, rpmtd td); 266 267 /** \ingroup header 268 * Delete tag in header. 269 * Removes all entries of type tag from the header, returns 1 if none were 270 * found. 271 * 272 * @param h header 273 * @param tag tag 274 * @return 0 on success, 1 on failure (INCONSISTENT) 275 */ 276 int headerDel(Header h, rpmTagVal tag); 277 278 /** \ingroup header 279 * Return formatted output string from header tags. 280 * The returned string must be free()d. 281 * 282 * @param h header 283 * @param fmt format to use 284 * @retval errmsg error message (if any) 285 * @return formatted output string (malloc'ed) 286 */ 287 char * headerFormat(Header h, const char * fmt, errmsg_t * errmsg); 288 289 /** \ingroup header 290 * Duplicate tag values from one header into another. 291 * @param headerFrom source header 292 * @param headerTo destination header 293 * @param tagstocopy array of tags that are copied 294 */ 295 void headerCopyTags(Header headerFrom, Header headerTo, 296 const rpmTagVal * tagstocopy); 297 298 /** \ingroup header 299 * Destroy header tag iterator. 300 * @param hi header tag iterator 301 * @return NULL always 302 */ 303 HeaderIterator headerFreeIterator(HeaderIterator hi); 304 305 /** \ingroup header 306 * Create header tag iterator. 307 * @param h header 308 * @return header tag iterator 309 */ 310 HeaderIterator headerInitIterator(Header h); 311 312 /** \ingroup header 313 * Return next tag contents from header. 314 * @param hi header tag iterator 315 * @retval td tag data container 316 * @return 1 on success, 0 on failure 317 */ 318 int headerNext(HeaderIterator hi, rpmtd td); 319 320 /** \ingroup header 321 * Return next tag number from header. 322 * @param hi header tag iterator 323 * @return next tag, RPMTAG_NOT_FOUND to stop iteration 324 */ 325 rpmTagVal headerNextTag(HeaderIterator hi); 326 327 /** \ingroup header 328 * Return any non-array tag from header, converted to string 329 * @param h header 330 * @param tag tag to retrieve 331 * @return string pointer (malloced) or NULL on failure 332 */ 333 char * headerGetAsString(Header h, rpmTagVal tag); 334 335 /** \ingroup header 336 * Return a simple string tag from header 337 * @param h header 338 * @param tag tag to retrieve 339 * @return string pointer (to header memory) or NULL on failure 340 */ 341 const char * headerGetString(Header h, rpmTagVal tag); 342 343 /** \ingroup header 344 * Return a simple number tag (or extension) from header 345 * @param h header 346 * @param tag tag to retrieve 347 * @return numeric tag value or 0 on failure 348 */ 349 uint64_t headerGetNumber(Header h, rpmTagVal tag); 350 351 /** \ingroup header 352 * Check if header is a source or binary package header 353 * @param h header 354 * @return 0 == binary, 1 == source 355 */ 356 int headerIsSource(Header h); 357 358 /** \ingroup header 359 * Return header instance, ie is the header from rpmdb. 360 * @param h header 361 * @return rpmdb record number or 0 362 */ 363 unsigned int headerGetInstance(Header h); 364 365 typedef enum headerConvOps_e { 366 HEADERCONV_EXPANDFILELIST = 0, 367 HEADERCONV_COMPRESSFILELIST = 1, 368 HEADERCONV_RETROFIT_V3 = 2, 369 } headerConvOps; 370 371 /** \ingroup header 372 * Convert header to/from (legacy) data presentation 373 * @param h header 374 * @param op one of headerConvOps operations 375 * @return 1 on success, 0 on failure 376 */ 377 int headerConvert(Header h, int op); 378 379 #ifdef __cplusplus 380 } 381 #endif 382 383 #endif /* H_HEADER */ 384