lib/rpmfiles.h

   1 #ifndef _RPMFILES_H
   2 #define _RPMFILES_H
   3
   4 /** \ingroup rpmfilesles
   5  * \file lib/rpmfiles.h
   6  * File info set API.
   7  */
   8 #include <sys/types.h>
   9 #include <sys/stat.h>
  10 #include <unistd.h>
  11
  12 #include <rpm/rpmtypes.h>
  13 #include <rpm/rpmvf.h>
  14 #include <rpm/rpmpgp.h>
  15
  16 /** \ingroup rpmfiles
  17  * File types.
  18  * These are the file types used internally by rpm. The file
  19  * type is determined by applying stat(2) macros like S_ISDIR to
  20  * the file mode tag from a header. The values are arbitrary,
  21  * but are identical to the linux stat(2) file types.
  22  */
  23 typedef enum rpmFileTypes_e {
  24     PIPE        =  1,   /*!< pipe/fifo */
  25     CDEV        =  2,   /*!< character device */
  26     XDIR        =  4,   /*!< directory */
  27     BDEV        =  6,   /*!< block device */
  28     REG         =  8,   /*!< regular file */
  29     LINK        = 10,   /*!< hard link */
  30     SOCK        = 12    /*!< socket */
  31 } rpmFileTypes;
  32
  33 /**
  34  * File States (when installed).
  35  */
  36 typedef enum rpmfileState_e {
  37     RPMFILE_STATE_MISSING       = -1,   /* used for unavailable data */
  38     RPMFILE_STATE_NORMAL        = 0,
  39     RPMFILE_STATE_REPLACED      = 1,
  40     RPMFILE_STATE_NOTINSTALLED  = 2,
  41     RPMFILE_STATE_NETSHARED     = 3,
  42     RPMFILE_STATE_WRONGCOLOR    = 4
  43 } rpmfileState;
  44
  45 #define RPMFILE_IS_INSTALLED(_x) ((_x) == RPMFILE_STATE_NORMAL || (_x) == RPMFILE_STATE_NETSHARED)
  46
  47 /**
  48  * Exported File Attributes (ie RPMTAG_FILEFLAGS)
  49  */
  50 enum rpmfileAttrs_e {
  51     RPMFILE_NONE        = 0,
  52     RPMFILE_CONFIG      = (1 <<  0),    /*!< from %%config */
  53     RPMFILE_DOC         = (1 <<  1),    /*!< from %%doc */
  54     RPMFILE_ICON        = (1 <<  2),    /*!< from %%donotuse. */
  55     RPMFILE_MISSINGOK   = (1 <<  3),    /*!< from %%config(missingok) */
  56     RPMFILE_NOREPLACE   = (1 <<  4),    /*!< from %%config(noreplace) */
  57     RPMFILE_SPECFILE    = (1 <<  5),    /*!< @todo (unnecessary) marks 1st file in srpm. */
  58     RPMFILE_GHOST       = (1 <<  6),    /*!< from %%ghost */
  59     RPMFILE_LICENSE     = (1 <<  7),    /*!< from %%license */
  60     RPMFILE_README      = (1 <<  8),    /*!< from %%readme */
  61     /* bits 9-10 unused */
  62     RPMFILE_PUBKEY      = (1 << 11),    /*!< from %%pubkey */
  63     RPMFILE_ARTIFACT    = (1 << 12),    /*!< from %%artifact */
  64     RPMFILE_SECMANIFEST        = (1 << 13),    /*!< from %%manifest */
  65 };
  66
  67 typedef rpmFlags rpmfileAttrs;
  68
  69 #define RPMFILE_ALL     ~(RPMFILE_NONE)
  70
  71 /** \ingroup rpmfiles
  72  * File disposition(s) during package install/erase transaction.
  73  */
  74 typedef enum rpmFileAction_e {
  75     FA_UNKNOWN          = 0,    /*!< initial action for file ... */
  76     FA_CREATE           = 1,    /*!< ... create from payload. */
  77     FA_COPYIN           = 2,    /*!< obsolete, unused. */
  78     FA_COPYOUT          = 3,    /*!< obsolete, unused. */
  79     FA_BACKUP           = 4,    /*!< ... renamed with ".rpmorig" extension. */
  80     FA_SAVE             = 5,    /*!< ... renamed with ".rpmsave" extension. */
  81     FA_SKIP             = 6,    /*!< ... already replaced, don't remove. */
  82     FA_ALTNAME          = 7,    /*!< ... create with ".rpmnew" extension. */
  83     FA_ERASE            = 8,    /*!< ... to be removed. */
  84     FA_SKIPNSTATE       = 9,    /*!< ... untouched, state "not installed". */
  85     FA_SKIPNETSHARED    = 10,   /*!< ... untouched, state "netshared". */
  86     FA_SKIPCOLOR        = 11,   /*!< ... untouched, state "wrong color". */
  87     FA_TOUCH            = 12,   /*!< ... change metadata only. */
  88     /* bits 16-31 reserved */
  89 } rpmFileAction;
  90
  91 #define XFA_SKIPPING(_a)        \
  92     ((_a) == FA_SKIP || (_a) == FA_SKIPNSTATE || (_a) == FA_SKIPNETSHARED || (_a) == FA_SKIPCOLOR)
  93
  94 /**
  95  * We pass these around as an array with a sentinel.
  96  */
  97 struct rpmRelocation_s {
  98     char * oldPath;     /*!< NULL here evals to RPMTAG_DEFAULTPREFIX, */
  99     char * newPath;     /*!< NULL means to omit the file completely! */
 100 };
 101
 102 enum rpmfiFlags_e {
 103     RPMFI_NOHEADER              = 0,
 104     RPMFI_KEEPHEADER            = (1 << 0),
 105     RPMFI_NOFILECLASS           = (1 << 1),
 106     RPMFI_NOFILEDEPS            = (1 << 2),
 107     RPMFI_NOFILELANGS           = (1 << 3),
 108     RPMFI_NOFILEUSER            = (1 << 4),
 109     RPMFI_NOFILEGROUP           = (1 << 5),
 110     RPMFI_NOFILEMODES           = (1 << 6),
 111     RPMFI_NOFILESIZES           = (1 << 7),
 112     RPMFI_NOFILECAPS            = (1 << 8),
 113     RPMFI_NOFILELINKTOS         = (1 << 9),
 114     RPMFI_NOFILEDIGESTS         = (1 << 10),
 115     RPMFI_NOFILEMTIMES          = (1 << 11),
 116     RPMFI_NOFILERDEVS           = (1 << 12),
 117     RPMFI_NOFILEINODES          = (1 << 13),
 118     RPMFI_NOFILESTATES          = (1 << 14),
 119     RPMFI_NOFILECOLORS          = (1 << 15),
 120     RPMFI_NOFILEVERIFYFLAGS     = (1 << 16),
 121     RPMFI_NOFILEFLAGS           = (1 << 17),
 122     RPMFI_NOFILESIGNATURES      = (1 << 18),
 123 };
 124
 125 typedef rpmFlags rpmfiFlags;
 126
 127 #define RPMFI_FLAGS_ERASE \
 128     (RPMFI_NOFILECLASS | RPMFI_NOFILELANGS | \
 129      RPMFI_NOFILEMTIMES | RPMFI_NOFILERDEVS | RPMFI_NOFILEINODES | \
 130      RPMFI_NOFILEVERIFYFLAGS)
 131
 132 #define RPMFI_FLAGS_INSTALL \
 133     (RPMFI_NOFILECLASS | RPMFI_NOFILEVERIFYFLAGS)
 134
 135 #define RPMFI_FLAGS_VERIFY \
 136     (RPMFI_NOFILECLASS | RPMFI_NOFILEDEPS | RPMFI_NOFILELANGS | \
 137      RPMFI_NOFILECOLORS)
 138
 139 #define RPMFI_FLAGS_QUERY \
 140     (RPMFI_NOFILECLASS | RPMFI_NOFILEDEPS | RPMFI_NOFILELANGS | \
 141      RPMFI_NOFILECOLORS | RPMFI_NOFILEVERIFYFLAGS)
 142
 143 #define RPMFI_FLAGS_FILETRIGGER \
 144     (RPMFI_NOFILECLASS | RPMFI_NOFILEDEPS | RPMFI_NOFILELANGS | \
 145      RPMFI_NOFILEUSER | RPMFI_NOFILEGROUP | RPMFI_NOFILEMODES | \
 146      RPMFI_NOFILESIZES | RPMFI_NOFILECAPS | RPMFI_NOFILELINKTOS | \
 147      RPMFI_NOFILEDIGESTS | RPMFI_NOFILEMTIMES | RPMFI_NOFILERDEVS | \
 148      RPMFI_NOFILEINODES | RPMFI_NOFILECOLORS | \
 149      RPMFI_NOFILEVERIFYFLAGS | RPMFI_NOFILEFLAGS)
 150
 151 #define RPMFI_FLAGS_ONLY_FILENAMES \
 152     (RPMFI_FLAGS_FILETRIGGER | RPMFI_NOFILESTATES)
 153
 154 typedef enum rpmFileIter_e {
 155     RPMFI_ITER_FWD      = 0,
 156     RPMFI_ITER_BACK     = 1,
 157     RPMFI_ITER_WRITE_ARCHIVE    = 2,
 158     RPMFI_ITER_READ_ARCHIVE     = 3,
 159     RPMFI_ITER_READ_ARCHIVE_CONTENT_FIRST = 4,
 160     RPMFI_ITER_READ_ARCHIVE_OMIT_HARDLINKS = 5,
 161     RPMFI_ITER_INTERVAL = 6,
 162 } rpmFileIter;
 163
 164 #define RPMFILEITERMAX 6
 165
 166 #ifdef __cplusplus
 167 extern "C" {
 168 #endif
 169
 170 /** \ingroup rpmfiles
 171  * Create and load a file info set.
 172  * @param pool          shared string pool (or NULL for private pool)
 173  * @param h             header
 174  * @param tagN          unused
 175  * @param flags         Flags to control what information is loaded.
 176  * @return              new file info set
 177  */
 178 rpmfiles rpmfilesNew(rpmstrPool pool, Header h, rpmTagVal tagN, rpmfiFlags flags);
 179
 180 /** \ingroup rpmfiles
 181  * Reference a file info set instance.
 182  * @param fi            file info set
 183  * @return              new file info set reference
 184  */
 185 rpmfiles rpmfilesLink(rpmfiles fi);
 186
 187 /** \ingroup rpmfiles
 188  * Destroy a file info set.
 189  * @param fi            file info set
 190  * @return              NULL always
 191  */
 192 rpmfiles rpmfilesFree(rpmfiles fi);
 193
 194 /** \ingroup rpmfiles
 195  * Return file count from file info set.
 196  * @param fi            file info set
 197  * @return              file count
 198  */
 199 rpm_count_t rpmfilesFC(rpmfiles fi);
 200
 201 /** \ingroup rpmfiles
 202  * Return directory count from file info set.
 203  * @param fi            file info set
 204  * @return              directory count
 205  */
 206 rpm_count_t rpmfilesDC(rpmfiles fi);
 207
 208 /** \ingroup rpmfiles
 209  * Return file index of the given file name or -1 if file is not in the rpmfi.
 210  * The file name may have "." prefixed but is then interpreted as a global
 211  * path without the prefixing "."
 212  * @param files         file info set
 213  * @param fn            file name
 214  * @return              file index or -1
 215  */
 216 int rpmfilesFindFN(rpmfiles files, const char * fn);
 217
 218 /** \ingroup rpmfiles
 219  * Return file index of the given original file name or -1 if file is not
 220  * in the rpmfi. The file name may have "." prefixed but is then interpreted
 221  * as a global path without the prefixing "."
 222  * @param files         file info set
 223  * @param fn            file name
 224  * @return              file index or -1
 225  */
 226 int rpmfilesFindOFN(rpmfiles files, const char * fn);
 227
 228 rpmfi rpmfilesIter(rpmfiles files, int itype);
 229
 230 /** \ingroup rpmfiles
 231  * Return digest algorithm of a file info set.
 232  * @param fi            file info set
 233  * @return              digest algorithm of file info set, 0 on invalid
 234  */
 235 int rpmfilesDigestAlgo(rpmfiles fi);
 236
 237 /** \ingroup rpmfiles
 238  * Return union of all file color bits from file info set.
 239  * @param files         file info set
 240  * @return              color
 241  */
 242 rpm_color_t rpmfilesColor(rpmfiles files);
 243
 244 /** \ingroup rpmfiles
 245  * Return file info comparison.
 246  * @param afi           1st file info
 247  * @param aix           index of the 1st file
 248  * @param bfi           2nd file info
 249  * @param bix           index of the 2nd file
 250  * @return              0 if identical
 251  */
 252 int rpmfilesCompare(rpmfiles afi, int aix, rpmfiles bfi, int bix);
 253
 254 /** \ingroup rpmfiles
 255  * Return base name from file info set.
 256  * @param fi            file info set
 257  * @param ix            file index
 258  * @return              base name, NULL on invalid
 259  */
 260 const char * rpmfilesBN(rpmfiles fi, int ix);
 261
 262 /** \ingroup rpmfiles
 263  * Return directory name from file info set. Note the index is on
 264  * distinct directories within the file set, not a file index. The
 265  * directory index associated with a given file index can be retrieved
 266  * with rpmfilesDI(). Ie to constuct the full path of file index X
 267  * you'd catenate the results of rpmfilesDN(f, rpmfilesDI(f, X)) and
 268  * rpmfilesBN(f, X).
 269  * @param fi            file info set
 270  * @param jx            directory index
 271  * @return              directory, NULL on invalid
 272  */
 273 const char * rpmfilesDN(rpmfiles fi, int jx);
 274
 275 /** \ingroup rpmfiles
 276  * Return directory index from file info set.
 277  * @param fi            file info set
 278  * @param ix            file index
 279  * @return              directory index, -1 on invalid
 280  */
 281 int rpmfilesDI(rpmfiles fi, int ix);
 282
 283 /** \ingroup rpmfiles
 284  * Return file name from file info set.
 285  * @param fi            file info set
 286  * @param ix            file index
 287  * @return              file name (malloced)
 288  */
 289 char * rpmfilesFN(rpmfiles fi, int ix);
 290
 291 /** \ingroup rpmfiles
 292  * Return original directory index from file info set.
 293  * @param fi            file info set
 294  * @param ix            file index
 295  * @return              directory index, -1 on invalid
 296  */
 297 int rpmfilesODI(rpmfiles fi, int ix);
 298
 299 /** \ingroup rpmfiles
 300  * Return original base name from file info set.
 301  * @param fi            file info set
 302  * @param ix            file index
 303  * @return              base name, NULL on invalid
 304  */
 305 const char * rpmfilesOBN(rpmfiles fi, int ix);
 306
 307 /** \ingroup rpmfiles
 308  * Return original directory name from file info set. Note the index is on
 309  * distinct directories within the file set, not a file index. The
 310  * directory index associated with a given file index can be retrieved
 311  * with rpmfilesODI(). Ie to constuct the full path of file index X
 312  * you'd catenate the results of rpmfilesODN(f, rpmfilesODI(f, X)) and
 313  * rpmfilesOBN(f, X).
 314  * @param fi            file info set
 315  * @param jx            directory index
 316  * @return              directory, NULL on invalid
 317  */
 318 const char * rpmfilesODN(rpmfiles fi, int jx);
 319
 320 /** \ingroup rpmfiles
 321  * Return original file name from file info set.
 322  * @param fi            file info set
 323  * @param ix            file index
 324  * @return              file name
 325  */
 326 char * rpmfilesOFN(rpmfiles fi, int ix);
 327
 328 /** \ingroup rpmfiles
 329  * Return file verify flags from file info set.
 330  * @param fi            file info set
 331  * @param ix            file index
 332  * @return              file verify flags, 0 on invalid
 333  */
 334 rpmVerifyAttrs rpmfilesVFlags(rpmfiles fi, int ix);
 335
 336 /** \ingroup rpmfiles
 337  * Return file state from file info set.
 338  * @param fi            file info set
 339  * @param ix            file index
 340  * @return              file state, 0 on invalid
 341  */
 342 rpmfileState rpmfilesFState(rpmfiles fi, int ix);
 343
 344 /** \ingroup rpmfiles
 345  * Return file linkto (i.e. symlink(2) target) from file info set.
 346  * @param fi            file info set
 347  * @param ix            file index
 348  * @return              file linkto, NULL on invalid
 349  */
 350 const char * rpmfilesFLink(rpmfiles fi, int ix);
 351
 352 /** \ingroup rpmfiles
 353  * Return file size from file info set.
 354  * @param fi            file info set
 355  * @param ix            file index
 356  * @return              file size, 0 on invalid
 357  */
 358 rpm_loff_t rpmfilesFSize(rpmfiles fi, int ix);
 359
 360 /** \ingroup rpmfiles
 361  * Return file color bits from file info set.
 362  * @param fi            file info set
 363  * @param ix            file index
 364  * @return              file color
 365  */
 366 rpm_color_t rpmfilesFColor(rpmfiles fi, int ix);
 367
 368 /** \ingroup rpmfiles
 369  * Return file class from file info set.
 370  * @param fi            file info set
 371  * @param ix            file index
 372  * @return              file class, 0 on invalid
 373  */
 374 const char * rpmfilesFClass(rpmfiles fi, int ix);
 375
 376 /** \ingroup rpmfiles
 377  * Return file depends dictionary from file info set.
 378  * @param fi            file info set
 379  * @param ix            file index
 380  * @retval *fddictp     file depends dictionary array (or NULL)
 381  * @return              no. of file depends entries, 0 on invalid
 382  */
 383 uint32_t rpmfilesFDepends(rpmfiles fi, int ix, const uint32_t ** fddictp);
 384
 385 /** \ingroup rpmfiles
 386  * Return (calculated) file nlink count from file info set.
 387  * @param fi            file info set
 388  * @param ix            file index
 389  * @return              file nlink count, 0 on invalid
 390  */
 391 uint32_t rpmfilesFNlink(rpmfiles fi, int ix);
 392
 393 /** \ingroup rpmfiles
 394  * Return (calculated) file nlink count from file info set.
 395  * @param fi            file info set
 396  * @param ix            file index
 397  * @param files         returns array of file ids hardlinked including ix,
 398                         NULL for nlink count == 1
 399  * @return              file nlink count, 0 on invalid
 400  */
 401 uint32_t rpmfilesFLinks(rpmfiles fi, int ix, const int ** files);
 402
 403 /** \ingroup rpmfiles
 404  * Return file language(s) from file info set.
 405  * @param fi            file info set
 406  * @param ix            file index
 407  * @return              file language(s), NULL on invalid
 408  */
 409 const char * rpmfilesFLangs(rpmfiles fi, int ix);
 410
 411 /** \ingroup rpmfiles
 412  * Return file flags from file info set.
 413  * @param fi            file info set
 414  * @param ix            file index
 415  * @return              file flags, 0 on invalid
 416  */
 417 rpmfileAttrs rpmfilesFFlags(rpmfiles fi, int ix);
 418
 419 /** \ingroup rpmfiles
 420  * Return file mode from file info set.
 421  * @param fi            file info set
 422  * @param ix            file index
 423  * @return              file mode, 0 on invalid
 424  */
 425 rpm_mode_t rpmfilesFMode(rpmfiles fi, int ix);
 426
 427 /** \ingroup rpmfiles
 428  * Return file (binary) digest of file info set.
 429  * @param fi            file info set
 430  * @param ix            file index
 431  * @retval algo         digest hash algorithm used (pass NULL to ignore)
 432  * @retval len          digest hash length (pass NULL to ignore)
 433  * @return              file digest, NULL on invalid
 434  */
 435 const unsigned char * rpmfilesFDigest(rpmfiles fi, int ix, int *algo, size_t *len);
 436
 437 /** \ingroup rpmfiles
 438  * Return file (binary) digest of file info set.
 439  * @param fi            file info set
 440  * @param ix            file index
 441  * @retval len       signature length (pass NULL to ignore)
 442  * @return              file signature, NULL on invalid
 443  */
 444 const unsigned char * rpmfilesFSignature(rpmfiles fi, int ix, size_t *len);
 445
 446 /** \ingroup rpmfiles
 447  * Return file rdev from file info set.
 448  * @param fi            file info set
 449  * @param ix            file index
 450  * @return              file rdev, 0 on invalid
 451  */
 452 rpm_rdev_t rpmfilesFRdev(rpmfiles fi, int ix);
 453
 454 /** \ingroup rpmfiles
 455  * Return file inode from file info set.
 456  * @param fi            file info set
 457  * @param ix            file index
 458  * @return              file inode, 0 on invalid
 459  */
 460 rpm_ino_t rpmfilesFInode(rpmfiles fi, int ix);
 461
 462 /** \ingroup rpmfiles
 463  * Return file modify time from file info set.
 464  * @param fi            file info set
 465  * @param ix            file index
 466  * @return              file modify time, 0 on invalid
 467  */
 468 rpm_time_t rpmfilesFMtime(rpmfiles fi, int ix);
 469
 470 /** \ingroup rpmfiles
 471  * Return file owner from file info set.
 472  * @param fi            file info set
 473  * @param ix            file index
 474  * @return              file owner, NULL on invalid
 475  */
 476 const char * rpmfilesFUser(rpmfiles fi, int ix);
 477
 478 /** \ingroup rpmfiles
 479  * Return file group from file info set.
 480  * @param fi            file info set
 481  * @param ix            file index
 482  * @return              file group, NULL on invalid
 483  */
 484 const char * rpmfilesFGroup(rpmfiles fi, int ix);
 485
 486 /** \ingroup rpmfiles
 487  * Return textual representation of file capabilities
 488  * from file info set. See cap_from_text(3) for details.
 489  * @param fi            file info set
 490  * @param ix            file index
 491  * @return              file capability description, "" for no capabilities
 492  *                      and NULL on invalid
 493  */
 494 const char * rpmfilesFCaps(rpmfiles fi, int ix);
 495
 496 /** \ingroup rpmfi
 497  * Map file stat(2) info.
 498  * @param fi            file info set
 499  * @param ix            file index
 500  * @param flags         flags
 501  * @retval sb           mapped stat(2) data
 502  * @return              0 on success
 503  */
 504 int rpmfilesStat(rpmfiles fi, int ix, int flags, struct stat *sb);
 505
 506 /** \ingroup rpmfiles
 507  * Verify file attributes (including digest).
 508  * @param fi            file info set
 509  * @param ix            file index
 510  * @param omitMask      bit(s) to disable verify checks
 511  * @return              bit(s) to indicate failure (ie 0 for passed verify)
 512  */
 513 rpmVerifyAttrs rpmfilesVerify(rpmfiles fi, int ix, rpmVerifyAttrs omitMask);
 514
 515 #ifdef __cplusplus
 516 }
 517 #endif
 518
 519 #endif /* _RPMFILES_H */