lib/libtar.h

   1 /*
   2 **  Copyright 1998-2003 University of Illinois Board of Trustees
   3 **  Copyright 1998-2003 Mark D. Roth
   4 **  All rights reserved.
   5 **
   6 **  libtar.h - header file for libtar library
   7 **
   8 **  Mark D. Roth <roth@uiuc.edu>
   9 **  Campus Information Technologies and Educational Services
  10 **  University of Illinois at Urbana-Champaign
  11 */
  12
  13 #ifndef LIBTAR_H
  14 #define LIBTAR_H
  15
  16 #include <sys/types.h>
  17 #include <sys/stat.h>
  18 #include <tar.h>
  19
  20 #include <libtar_listhash.h>
  21
  22 #ifdef __cplusplus
  23 extern "C"
  24 {
  25 #endif
  26
  27
  28 /* useful constants */
  29 /* see FIXME note in block.c regarding T_BLOCKSIZE */
  30 #define T_BLOCKSIZE             512
  31 #define T_NAMELEN               100
  32 #define T_PREFIXLEN             155
  33 #define T_MAXPATHLEN            (T_NAMELEN + T_PREFIXLEN)
  34
  35 /* GNU extensions for typeflag */
  36 #define GNU_LONGNAME_TYPE       'L'
  37 #define GNU_LONGLINK_TYPE       'K'
  38
  39 /* our version of the tar header structure */
  40 struct tar_header
  41 {
  42         char name[100];
  43         char mode[8];
  44         char uid[8];
  45         char gid[8];
  46         char size[12];
  47         char mtime[12];
  48         char chksum[8];
  49         char typeflag;
  50         char linkname[100];
  51         char magic[6];
  52         char version[2];
  53         char uname[32];
  54         char gname[32];
  55         char devmajor[8];
  56         char devminor[8];
  57         char prefix[155];
  58         char padding[12];
  59         char *gnu_longname;
  60         char *gnu_longlink;
  61 };
  62
  63
  64 /***** handle.c ************************************************************/
  65
  66 typedef int (*openfunc_t)(const char *, int, ...);
  67 typedef int (*closefunc_t)(int);
  68 typedef ssize_t (*readfunc_t)(int, void *, size_t);
  69 typedef ssize_t (*writefunc_t)(int, const void *, size_t);
  70
  71 typedef struct
  72 {
  73         openfunc_t openfunc;
  74         closefunc_t closefunc;
  75         readfunc_t readfunc;
  76         writefunc_t writefunc;
  77 }
  78 tartype_t;
  79
  80 typedef struct
  81 {
  82         tartype_t *type;
  83         char *pathname;
  84         long fd;
  85         int oflags;
  86         int options;
  87         struct tar_header th_buf;
  88         libtar_hash_t *h;
  89
  90         /* introduced in libtar 1.2.21 */
  91         char *th_pathname;
  92 }
  93 TAR;
  94
  95 /* constant values for the TAR options field */
  96 #define TAR_GNU                  1      /* use GNU extensions */
  97 #define TAR_VERBOSE              2      /* output file info to stdout */
  98 #define TAR_NOOVERWRITE          4      /* don't overwrite existing files */
  99 #define TAR_IGNORE_EOT           8      /* ignore double zero blocks as EOF */
 100 #define TAR_CHECK_MAGIC         16      /* check magic in file header */
 101 #define TAR_CHECK_VERSION       32      /* check version in file header */
 102 #define TAR_IGNORE_CRC          64      /* ignore CRC in file header */
 103
 104 /* this is obsolete - it's here for backwards-compatibility only */
 105 #define TAR_IGNORE_MAGIC        0
 106
 107 extern const char libtar_version[];
 108
 109
 110 /* open a new tarfile handle */
 111 int tar_open(TAR **t, const char *pathname, tartype_t *type,
 112              int oflags, int mode, int options);
 113
 114 /* make a tarfile handle out of a previously-opened descriptor */
 115 int tar_fdopen(TAR **t, int fd, const char *pathname, tartype_t *type,
 116                int oflags, int mode, int options);
 117
 118 /* returns the descriptor associated with t */
 119 int tar_fd(TAR *t);
 120
 121 /* close tarfile handle */
 122 int tar_close(TAR *t);
 123
 124
 125 /***** append.c ************************************************************/
 126
 127 /* forward declaration to appease the compiler */
 128 struct tar_dev;
 129
 130 /* cleanup function */
 131 void tar_dev_free(struct tar_dev *tdp);
 132
 133 /* Appends a file to the tar archive.
 134  * Arguments:
 135  *    t        = TAR handle to append to
 136  *    realname = path of file to append
 137  *    savename = name to save the file under in the archive
 138  */
 139 int tar_append_file(TAR *t, const char *realname, const char *savename);
 140
 141 /* write EOF indicator */
 142 int tar_append_eof(TAR *t);
 143
 144 /* add file contents to a tarchive */
 145 int tar_append_regfile(TAR *t, const char *realname);
 146
 147
 148 /***** block.c *************************************************************/
 149
 150 /* macros for reading/writing tarchive blocks */
 151 #define tar_block_read(t, buf) \
 152         (*((t)->type->readfunc))((t)->fd, (char *)(buf), T_BLOCKSIZE)
 153 #define tar_block_write(t, buf) \
 154         (*((t)->type->writefunc))((t)->fd, (char *)(buf), T_BLOCKSIZE)
 155
 156 /* read/write a header block */
 157 int th_read(TAR *t);
 158 int th_write(TAR *t);
 159
 160
 161 /***** decode.c ************************************************************/
 162
 163 /* determine file type */
 164 #define TH_ISREG(t)     ((t)->th_buf.typeflag == REGTYPE \
 165                          || (t)->th_buf.typeflag == AREGTYPE \
 166                          || (t)->th_buf.typeflag == CONTTYPE \
 167                          || (S_ISREG((mode_t)oct_to_int((t)->th_buf.mode)) \
 168                              && (t)->th_buf.typeflag != LNKTYPE))
 169 #define TH_ISLNK(t)     ((t)->th_buf.typeflag == LNKTYPE)
 170 #define TH_ISSYM(t)     ((t)->th_buf.typeflag == SYMTYPE \
 171                          || S_ISLNK((mode_t)oct_to_int((t)->th_buf.mode)))
 172 #define TH_ISCHR(t)     ((t)->th_buf.typeflag == CHRTYPE \
 173                          || S_ISCHR((mode_t)oct_to_int((t)->th_buf.mode)))
 174 #define TH_ISBLK(t)     ((t)->th_buf.typeflag == BLKTYPE \
 175                          || S_ISBLK((mode_t)oct_to_int((t)->th_buf.mode)))
 176 #define TH_ISDIR(t)     ((t)->th_buf.typeflag == DIRTYPE \
 177                          || S_ISDIR((mode_t)oct_to_int((t)->th_buf.mode)) \
 178                          || ((t)->th_buf.typeflag == AREGTYPE \
 179                              && strlen((t)->th_buf.name) \
 180                              && ((t)->th_buf.name[strlen((t)->th_buf.name) - 1] == '/')))
 181 #define TH_ISFIFO(t)    ((t)->th_buf.typeflag == FIFOTYPE \
 182                          || S_ISFIFO((mode_t)oct_to_int((t)->th_buf.mode)))
 183 #define TH_ISLONGNAME(t)        ((t)->th_buf.typeflag == GNU_LONGNAME_TYPE)
 184 #define TH_ISLONGLINK(t)        ((t)->th_buf.typeflag == GNU_LONGLINK_TYPE)
 185
 186 /* decode tar header info */
 187 #define th_get_crc(t) oct_to_int((t)->th_buf.chksum)
 188 /* We cast from int (what oct_to_int() returns) to
 189    unsigned int, to avoid unwieldy sign extensions
 190    from occurring on systems where size_t is bigger than int,
 191    since th_get_size() is often stored into a size_t. */
 192 #define th_get_size(t) ((unsigned int)oct_to_int((t)->th_buf.size))
 193 #define th_get_mtime(t) oct_to_int((t)->th_buf.mtime)
 194 #define th_get_devmajor(t) oct_to_int((t)->th_buf.devmajor)
 195 #define th_get_devminor(t) oct_to_int((t)->th_buf.devminor)
 196 #define th_get_linkname(t) ((t)->th_buf.gnu_longlink \
 197                             ? (t)->th_buf.gnu_longlink \
 198                             : (t)->th_buf.linkname)
 199 char *th_get_pathname(TAR *t);
 200 mode_t th_get_mode(TAR *t);
 201 uid_t th_get_uid(TAR *t);
 202 gid_t th_get_gid(TAR *t);
 203
 204
 205 /***** encode.c ************************************************************/
 206
 207 /* encode file info in th_header */
 208 void th_set_type(TAR *t, mode_t mode);
 209 void th_set_path(TAR *t, const char *pathname);
 210 void th_set_link(TAR *t, const char *linkname);
 211 void th_set_device(TAR *t, dev_t device);
 212 void th_set_user(TAR *t, uid_t uid);
 213 void th_set_group(TAR *t, gid_t gid);
 214 void th_set_mode(TAR *t, mode_t fmode);
 215 #define th_set_mtime(t, fmtime) \
 216         int_to_oct_nonull((fmtime), (t)->th_buf.mtime, 12)
 217 #define th_set_size(t, fsize) \
 218         int_to_oct_nonull((fsize), (t)->th_buf.size, 12)
 219
 220 /* encode everything at once (except the pathname and linkname) */
 221 void th_set_from_stat(TAR *t, struct stat *s);
 222
 223 /* encode magic, version, and crc - must be done after everything else is set */
 224 void th_finish(TAR *t);
 225
 226
 227 /***** extract.c ***********************************************************/
 228
 229 /* sequentially extract next file from t */
 230 int tar_extract_file(TAR *t, char *realname);
 231
 232 /* extract different file types */
 233 int tar_extract_dir(TAR *t, char *realname);
 234 int tar_extract_hardlink(TAR *t, char *realname);
 235 int tar_extract_symlink(TAR *t, char *realname);
 236 int tar_extract_chardev(TAR *t, char *realname);
 237 int tar_extract_blockdev(TAR *t, char *realname);
 238 int tar_extract_fifo(TAR *t, char *realname);
 239
 240 /* for regfiles, we need to extract the content blocks as well */
 241 int tar_extract_regfile(TAR *t, char *realname);
 242 int tar_skip_regfile(TAR *t);
 243
 244
 245 /***** output.c ************************************************************/
 246
 247 /* print the tar header */
 248 void th_print(TAR *t);
 249
 250 /* print "ls -l"-like output for the file described by th */
 251 void th_print_long_ls(TAR *t);
 252
 253
 254 /***** util.c *************************************************************/
 255
 256 /* hashing function for pathnames */
 257 int path_hashfunc(char *key, int numbuckets);
 258
 259 /* matching function for dev_t's */
 260 int dev_match(dev_t *dev1, dev_t *dev2);
 261
 262 /* matching function for ino_t's */
 263 int ino_match(ino_t *ino1, ino_t *ino2);
 264
 265 /* hashing function for dev_t's */
 266 int dev_hash(dev_t *dev);
 267
 268 /* hashing function for ino_t's */
 269 int ino_hash(ino_t *inode);
 270
 271 /* create any necessary dirs */
 272 int mkdirhier(char *path);
 273
 274 /* calculate header checksum */
 275 int th_crc_calc(TAR *t);
 276
 277 /* calculate a signed header checksum */
 278 int th_signed_crc_calc(TAR *t);
 279
 280 /* compare checksums in a forgiving way */
 281 #define th_crc_ok(t) (th_get_crc(t) == th_crc_calc(t) || th_get_crc(t) == th_signed_crc_calc(t))
 282
 283 /* string-octal to integer conversion */
 284 int oct_to_int(char *oct);
 285
 286 /* integer to NULL-terminated string-octal conversion */
 287 #define int_to_oct(num, oct, octlen) \
 288         snprintf((oct), (octlen), "%*lo ", (octlen) - 2, (unsigned long)(num))
 289
 290 /* integer to string-octal conversion, no NULL */
 291 void int_to_oct_nonull(int num, char *oct, size_t octlen);
 292
 293
 294 /***** wrapper.c **********************************************************/
 295
 296 /* extract groups of files */
 297 int tar_extract_glob(TAR *t, char *globname, char *prefix);
 298 int tar_extract_all(TAR *t, char *prefix);
 299
 300 /* add a whole tree of files */
 301 int tar_append_tree(TAR *t, char *realdir, char *savedir);
 302
 303
 304 #ifdef __cplusplus
 305 }
 306 #endif
 307
 308 #endif /* ! LIBTAR_H */
 309