lib/bup/metadata.py

   1 """Metadata read/write support for bup."""
   2
   3 # Copyright (C) 2010 Rob Browning
   4 #
   5 # This code is covered under the terms of the GNU Library General
   6 # Public License as described in the bup LICENSE file.
   7 import errno, os, sys, stat, pwd, grp, struct, re
   8 from cStringIO import StringIO
   9 from bup import vint, xstat
  10 from bup.drecurse import recursive_dirlist
  11 from bup.helpers import add_error, mkdirp, log, is_superuser
  12 from bup.xstat import utime, lutime, lstat
  13 import bup._helpers as _helpers
  14
  15 try:
  16     import xattr
  17 except ImportError:
  18     log('Warning: Linux xattr support missing; install python-pyxattr.\n')
  19     xattr = None
  20 if xattr:
  21     try:
  22         xattr.get_all
  23     except AttributeError:
  24         log('Warning: python-xattr module is too old; '
  25             'install python-pyxattr instead.\n')
  26         xattr = None
  27 try:
  28     import posix1e
  29 except ImportError:
  30     log('Warning: POSIX ACL support missing; install python-pylibacl.\n')
  31     posix1e = None
  32 try:
  33     from bup._helpers import get_linux_file_attr, set_linux_file_attr
  34 except ImportError:
  35     # No need for a warning here; the only reason they won't exist is that we're
  36     # not on Linux, in which case files don't have any linux attrs anyway, so
  37     # lacking the functions isn't a problem.
  38     get_linux_file_attr = set_linux_file_attr = None
  39
  40
  41 # WARNING: the metadata encoding is *not* stable yet.  Caveat emptor!
  42
  43 # Q: Consider hardlink support?
  44 # Q: Is it OK to store raw linux attr (chattr) flags?
  45 # Q: Can anything other than S_ISREG(x) or S_ISDIR(x) support posix1e ACLs?
  46 # Q: Is the application of posix1e has_extended() correct?
  47 # Q: Is one global --numeric-ids argument sufficient?
  48 # Q: Do nfsv4 acls trump posix1e acls? (seems likely)
  49 # Q: Add support for crtime -- ntfs, and (only internally?) ext*?
  50
  51 # FIXME: Fix relative/abs path detection/stripping wrt other platforms.
  52 # FIXME: Add nfsv4 acl handling - see nfs4-acl-tools.
  53 # FIXME: Consider other entries mentioned in stat(2) (S_IFDOOR, etc.).
  54 # FIXME: Consider pack('vvvvsss', ...) optimization.
  55 # FIXME: Consider caching users/groups.
  56
  57 ## FS notes:
  58 #
  59 # osx (varies between hfs and hfs+):
  60 #   type - regular dir char block fifo socket ...
  61 #   perms - rwxrwxrwxsgt
  62 #   times - ctime atime mtime
  63 #   uid
  64 #   gid
  65 #   hard-link-info (hfs+ only)
  66 #   link-target
  67 #   device-major/minor
  68 #   attributes-osx see chflags
  69 #   content-type
  70 #   content-creator
  71 #   forks
  72 #
  73 # ntfs
  74 #   type - regular dir ...
  75 #   times - creation, modification, posix change, access
  76 #   hard-link-info
  77 #   link-target
  78 #   attributes - see attrib
  79 #   ACLs
  80 #   forks (alternate data streams)
  81 #   crtime?
  82 #
  83 # fat
  84 #   type - regular dir ...
  85 #   perms - rwxrwxrwx (maybe - see wikipedia)
  86 #   times - creation, modification, access
  87 #   attributes - see attrib
  88
  89 verbose = 0
  90
  91 _have_lchmod = hasattr(os, 'lchmod')
  92
  93
  94 def _clean_up_path_for_archive(p):
  95     # Not the most efficient approach.
  96     result = p
  97
  98     # Take everything after any '/../'.
  99     pos = result.rfind('/../')
 100     if pos != -1:
 101         result = result[result.rfind('/../') + 4:]
 102
 103     # Take everything after any remaining '../'.
 104     if result.startswith("../"):
 105         result = result[3:]
 106
 107     # Remove any '/./' sequences.
 108     pos = result.find('/./')
 109     while pos != -1:
 110         result = result[0:pos] + '/' + result[pos + 3:]
 111         pos = result.find('/./')
 112
 113     # Remove any leading '/'s.
 114     result = result.lstrip('/')
 115
 116     # Replace '//' with '/' everywhere.
 117     pos = result.find('//')
 118     while pos != -1:
 119         result = result[0:pos] + '/' + result[pos + 2:]
 120         pos = result.find('//')
 121
 122     # Take everything after any remaining './'.
 123     if result.startswith('./'):
 124         result = result[2:]
 125
 126     # Take everything before any remaining '/.'.
 127     if result.endswith('/.'):
 128         result = result[:-2]
 129
 130     if result == '' or result.endswith('/..'):
 131         result = '.'
 132
 133     return result
 134
 135
 136 def _risky_path(p):
 137     if p.startswith('/'):
 138         return True
 139     if p.find('/../') != -1:
 140         return True
 141     if p.startswith('../'):
 142         return True
 143     if p.endswith('/..'):
 144         return True
 145     return False
 146
 147
 148 def _clean_up_extract_path(p):
 149     result = p.lstrip('/')
 150     if result == '':
 151         return '.'
 152     elif _risky_path(result):
 153         return None
 154     else:
 155         return result
 156
 157
 158 # These tags are currently conceptually private to Metadata, and they
 159 # must be unique, and must *never* be changed.
 160 _rec_tag_end = 0
 161 _rec_tag_path = 1
 162 _rec_tag_common = 2           # times, owner, group, type, perms, etc.
 163 _rec_tag_symlink_target = 3
 164 _rec_tag_posix1e_acl = 4      # getfacl(1), setfacl(1), etc.
 165 _rec_tag_nfsv4_acl = 5        # intended to supplant posix1e acls?
 166 _rec_tag_linux_attr = 6       # lsattr(1) chattr(1)
 167 _rec_tag_linux_xattr = 7      # getfattr(1) setfattr(1)
 168
 169
 170 class ApplyError(Exception):
 171     # Thrown when unable to apply any given bit of metadata to a path.
 172     pass
 173
 174
 175 class Metadata:
 176     # Metadata is stored as a sequence of tagged binary records.  Each
 177     # record will have some subset of add, encode, load, create, and
 178     # apply methods, i.e. _add_foo...
 179
 180     ## Common records
 181
 182     # Timestamps are (sec, ns), relative to 1970-01-01 00:00:00, ns
 183     # must be non-negative and < 10**9.
 184
 185     def _add_common(self, path, st):
 186         self.mode = st.st_mode
 187         self.uid = st.st_uid
 188         self.gid = st.st_gid
 189         self.rdev = st.st_rdev
 190         self.atime = st.st_atime
 191         self.mtime = st.st_mtime
 192         self.ctime = st.st_ctime
 193         self.owner = self.group = ''
 194         try:
 195             self.owner = pwd.getpwuid(st.st_uid)[0]
 196         except KeyError, e:
 197             add_error("no user name for id %s '%s'" % (st.st_gid, path))
 198         try:
 199             self.group = grp.getgrgid(st.st_gid)[0]
 200         except KeyError, e:
 201             add_error("no group name for id %s '%s'" % (st.st_gid, path))
 202
 203     def _encode_common(self):
 204         atime = xstat.nsecs_to_timespec(self.atime)
 205         mtime = xstat.nsecs_to_timespec(self.mtime)
 206         ctime = xstat.nsecs_to_timespec(self.ctime)
 207         result = vint.pack('VVsVsVvVvVvV',
 208                            self.mode,
 209                            self.uid,
 210                            self.owner,
 211                            self.gid,
 212                            self.group,
 213                            self.rdev,
 214                            atime[0],
 215                            atime[1],
 216                            mtime[0],
 217                            mtime[1],
 218                            ctime[0],
 219                            ctime[1])
 220         return result
 221
 222     def _load_common_rec(self, port):
 223         data = vint.read_bvec(port)
 224         (self.mode,
 225          self.uid,
 226          self.owner,
 227          self.gid,
 228          self.group,
 229          self.rdev,
 230          self.atime,
 231          atime_ns,
 232          self.mtime,
 233          mtime_ns,
 234          self.ctime,
 235          ctime_ns) = vint.unpack('VVsVsVvVvVvV', data)
 236         self.atime = xstat.timespec_to_nsecs((self.atime, atime_ns))
 237         self.mtime = xstat.timespec_to_nsecs((self.mtime, mtime_ns))
 238         self.ctime = xstat.timespec_to_nsecs((self.ctime, ctime_ns))
 239
 240     def _recognized_file_type(self):
 241         return stat.S_ISREG(self.mode) \
 242             or stat.S_ISDIR(self.mode) \
 243             or stat.S_ISCHR(self.mode) \
 244             or stat.S_ISBLK(self.mode) \
 245             or stat.S_ISFIFO(self.mode) \
 246             or stat.S_ISSOCK(self.mode) \
 247             or stat.S_ISLNK(self.mode)
 248
 249     def _create_via_common_rec(self, path, create_symlinks=True):
 250         # If the path already exists and is a dir, try rmdir.
 251         # If the path already exists and is anything else, try unlink.
 252         st = None
 253         try:
 254             st = xstat.lstat(path)
 255         except OSError, e:
 256             if e.errno != errno.ENOENT:
 257                 raise
 258         if st:
 259             if stat.S_ISDIR(st.st_mode):
 260                 try:
 261                     os.rmdir(path)
 262                 except OSError, e:
 263                     if e.errno == errno.ENOTEMPTY:
 264                         msg = 'refusing to overwrite non-empty dir' + path
 265                         raise Exception(msg)
 266                     raise
 267             else:
 268                 os.unlink(path)
 269
 270         if stat.S_ISREG(self.mode):
 271             assert(self._recognized_file_type())
 272             fd = os.open(path, os.O_CREAT|os.O_WRONLY|os.O_EXCL, 0600)
 273             os.close(fd)
 274         elif stat.S_ISDIR(self.mode):
 275             assert(self._recognized_file_type())
 276             os.mkdir(path, 0700)
 277         elif stat.S_ISCHR(self.mode):
 278             assert(self._recognized_file_type())
 279             os.mknod(path, 0600 | stat.S_IFCHR, self.rdev)
 280         elif stat.S_ISBLK(self.mode):
 281             assert(self._recognized_file_type())
 282             os.mknod(path, 0600 | stat.S_IFBLK, self.rdev)
 283         elif stat.S_ISFIFO(self.mode):
 284             assert(self._recognized_file_type())
 285             os.mknod(path, 0600 | stat.S_IFIFO)
 286         elif stat.S_ISSOCK(self.mode):
 287             os.mknod(path, 0600 | stat.S_IFSOCK)
 288         elif stat.S_ISLNK(self.mode):
 289             assert(self._recognized_file_type())
 290             if self.symlink_target and create_symlinks:
 291                 # on MacOS, symlink() permissions depend on umask, and there's
 292                 # no way to chown a symlink after creating it, so we have to
 293                 # be careful here!
 294                 oldumask = os.umask((self.mode & 0777) ^ 0777)
 295                 try:
 296                     os.symlink(self.symlink_target, path)
 297                 finally:
 298                     os.umask(oldumask)
 299         # FIXME: S_ISDOOR, S_IFMPB, S_IFCMP, S_IFNWK, ... see stat(2).
 300         else:
 301             assert(not self._recognized_file_type())
 302             add_error('not creating "%s" with unrecognized mode "0x%x"\n'
 303                       % (path, self.mode))
 304
 305     def _apply_common_rec(self, path, restore_numeric_ids=False):
 306         # FIXME: S_ISDOOR, S_IFMPB, S_IFCMP, S_IFNWK, ... see stat(2).
 307         # EACCES errors at this stage are fatal for the current path.
 308         if lutime and stat.S_ISLNK(self.mode):
 309             try:
 310                 lutime(path, (self.atime, self.mtime))
 311             except OSError, e:
 312                 if e.errno == errno.EACCES:
 313                     raise ApplyError('lutime: %s' % e)
 314                 else:
 315                     raise
 316         else:
 317             try:
 318                 utime(path, (self.atime, self.mtime))
 319             except OSError, e:
 320                 if e.errno == errno.EACCES:
 321                     raise ApplyError('utime: %s' % e)
 322                 else:
 323                     raise
 324
 325         # Don't try to restore owner unless we're root, and even
 326         # if asked, don't try to restore the owner or group if
 327         # it doesn't exist in the system db.
 328         uid = self.uid
 329         gid = self.gid
 330         if not restore_numeric_ids:
 331             if not self.owner:
 332                 uid = -1
 333                 add_error('ignoring missing owner for "%s"\n' % path)
 334             else:
 335                 if not is_superuser():
 336                     uid = -1 # Not root; assume we can't change owner.
 337                 else:
 338                     try:
 339                         uid = pwd.getpwnam(self.owner)[2]
 340                     except KeyError:
 341                         uid = -1
 342                         fmt = 'ignoring unknown owner %s for "%s"\n'
 343                         add_error(fmt % (self.owner, path))
 344             if not self.group:
 345                 gid = -1
 346                 add_error('ignoring missing group for "%s"\n' % path)
 347             else:
 348                 try:
 349                     gid = grp.getgrnam(self.group)[2]
 350                 except KeyError:
 351                     gid = -1
 352                     add_error('ignoring unknown group %s for "%s"\n'
 353                               % (self.group, path))
 354
 355         try:
 356             os.lchown(path, uid, gid)
 357         except OSError, e:
 358             if e.errno == errno.EPERM:
 359                 add_error('lchown: %s' %  e)
 360             else:
 361                 raise
 362
 363         if _have_lchmod:
 364             os.lchmod(path, stat.S_IMODE(self.mode))
 365         elif not stat.S_ISLNK(self.mode):
 366             os.chmod(path, stat.S_IMODE(self.mode))
 367
 368
 369     ## Path records
 370
 371     def _encode_path(self):
 372         if self.path:
 373             return vint.pack('s', self.path)
 374         else:
 375             return None
 376
 377     def _load_path_rec(self, port):
 378         self.path = vint.unpack('s', vint.read_bvec(port))[0]
 379
 380
 381     ## Symlink targets
 382
 383     def _add_symlink_target(self, path, st):
 384         try:
 385             if stat.S_ISLNK(st.st_mode):
 386                 self.symlink_target = os.readlink(path)
 387         except OSError, e:
 388             add_error('readlink: %s', e)
 389
 390     def _encode_symlink_target(self):
 391         return self.symlink_target
 392
 393     def _load_symlink_target_rec(self, port):
 394         self.symlink_target = vint.read_bvec(port)
 395
 396
 397     ## POSIX1e ACL records
 398
 399     # Recorded as a list:
 400     #   [txt_id_acl, num_id_acl]
 401     # or, if a directory:
 402     #   [txt_id_acl, num_id_acl, txt_id_default_acl, num_id_default_acl]
 403     # The numeric/text distinction only matters when reading/restoring
 404     # a stored record.
 405     def _add_posix1e_acl(self, path, st):
 406         if not posix1e: return
 407         if not stat.S_ISLNK(st.st_mode):
 408             try:
 409                 if posix1e.has_extended(path):
 410                     acl = posix1e.ACL(file=path)
 411                     self.posix1e_acl = [acl, acl] # txt and num are the same
 412                     if stat.S_ISDIR(st.st_mode):
 413                         acl = posix1e.ACL(filedef=path)
 414                         self.posix1e_acl.extend([acl, acl])
 415             except EnvironmentError, e:
 416                 if e.errno != errno.EOPNOTSUPP:
 417                     raise
 418
 419     def _encode_posix1e_acl(self):
 420         # Encode as two strings (w/default ACL string possibly empty).
 421         if self.posix1e_acl:
 422             acls = self.posix1e_acl
 423             txt_flags = posix1e.TEXT_ABBREVIATE
 424             num_flags = posix1e.TEXT_ABBREVIATE | posix1e.TEXT_NUMERIC_IDS
 425             acl_reps = [acls[0].to_any_text('', '\n', txt_flags),
 426                         acls[1].to_any_text('', '\n', num_flags)]
 427             if len(acls) < 3:
 428                 acl_reps += ['', '']
 429             else:
 430                 acl_reps.append(acls[2].to_any_text('', '\n', txt_flags))
 431                 acl_reps.append(acls[3].to_any_text('', '\n', num_flags))
 432             return vint.pack('ssss',
 433                              acl_reps[0], acl_reps[1], acl_reps[2], acl_reps[3])
 434         else:
 435             return None
 436
 437     def _load_posix1e_acl_rec(self, port):
 438         data = vint.read_bvec(port)
 439         acl_reps = vint.unpack('ssss', data)
 440         if acl_reps[2] == '':
 441             acl_reps = acl_reps[:2]
 442         self.posix1e_acl = [posix1e.ACL(text=x) for x in acl_reps]
 443
 444     def _apply_posix1e_acl_rec(self, path, restore_numeric_ids=False):
 445         if not posix1e:
 446             if self.posix1e_acl:
 447                 add_error("%s: can't restore ACLs; posix1e support missing.\n"
 448                           % path)
 449             return
 450         if self.posix1e_acl:
 451             acls = self.posix1e_acl
 452             if len(acls) > 2:
 453                 if restore_numeric_ids:
 454                     acls[3].applyto(path, posix1e.ACL_TYPE_DEFAULT)
 455                 else:
 456                     acls[2].applyto(path, posix1e.ACL_TYPE_DEFAULT)
 457             if restore_numeric_ids:
 458                 acls[1].applyto(path, posix1e.ACL_TYPE_ACCESS)
 459             else:
 460                 acls[0].applyto(path, posix1e.ACL_TYPE_ACCESS)
 461
 462
 463     ## Linux attributes (lsattr(1), chattr(1))
 464
 465     def _add_linux_attr(self, path, st):
 466         if not get_linux_file_attr: return
 467         if stat.S_ISREG(st.st_mode) or stat.S_ISDIR(st.st_mode):
 468             try:
 469                 attr = get_linux_file_attr(path)
 470                 if attr != 0:
 471                     self.linux_attr = attr
 472             except OSError, e:
 473                 if e.errno == errno.EACCES:
 474                     add_error('read Linux attr: %s' % e)
 475                 elif e.errno == errno.ENOTTY or e.errno == errno.ENOSYS:
 476                     # ENOTTY: Function not implemented.
 477                     # ENOSYS: Inappropriate ioctl for device.
 478                     # Assume filesystem doesn't support attrs.
 479                     return
 480                 else:
 481                     raise
 482
 483     def _encode_linux_attr(self):
 484         if self.linux_attr:
 485             return vint.pack('V', self.linux_attr)
 486         else:
 487             return None
 488
 489     def _load_linux_attr_rec(self, port):
 490         data = vint.read_bvec(port)
 491         self.linux_attr = vint.unpack('V', data)[0]
 492
 493     def _apply_linux_attr_rec(self, path, restore_numeric_ids=False):
 494         if self.linux_attr:
 495             if not set_linux_file_attr:
 496                 add_error("%s: can't restore linuxattrs: "
 497                           "linuxattr support missing.\n" % path)
 498                 return
 499             set_linux_file_attr(path, self.linux_attr)
 500
 501
 502     ## Linux extended attributes (getfattr(1), setfattr(1))
 503
 504     def _add_linux_xattr(self, path, st):
 505         if not xattr: return
 506         try:
 507             self.linux_xattr = xattr.get_all(path, nofollow=True)
 508         except EnvironmentError, e:
 509             if e.errno != errno.EOPNOTSUPP:
 510                 raise
 511
 512     def _encode_linux_xattr(self):
 513         if self.linux_xattr:
 514             result = vint.pack('V', len(self.linux_xattr))
 515             for name, value in self.linux_xattr:
 516                 result += vint.pack('ss', name, value)
 517             return result
 518         else:
 519             return None
 520
 521     def _load_linux_xattr_rec(self, file):
 522         data = vint.read_bvec(file)
 523         memfile = StringIO(data)
 524         result = []
 525         for i in range(vint.read_vuint(memfile)):
 526             key = vint.read_bvec(memfile)
 527             value = vint.read_bvec(memfile)
 528             result.append((key, value))
 529         self.linux_xattr = result
 530
 531     def _apply_linux_xattr_rec(self, path, restore_numeric_ids=False):
 532         if not xattr:
 533             if self.linux_xattr:
 534                 add_error("%s: can't restore xattr; xattr support missing.\n"
 535                           % path)
 536             return
 537         existing_xattrs = set(xattr.list(path, nofollow=True))
 538         if self.linux_xattr:
 539             for k, v in self.linux_xattr:
 540                 if k not in existing_xattrs \
 541                         or v != xattr.get(path, k, nofollow=True):
 542                     try:
 543                         xattr.set(path, k, v, nofollow=True)
 544                     except IOError, e:
 545                         if e.errno == errno.EPERM:
 546                             raise ApplyError('xattr.set: %s' % e)
 547                         else:
 548                             raise
 549                 existing_xattrs -= frozenset([k])
 550             for k in existing_xattrs:
 551                 try:
 552                     xattr.remove(path, k, nofollow=True)
 553                 except IOError, e:
 554                     if e.errno == errno.EPERM:
 555                         raise ApplyError('xattr.remove: %s' % e)
 556                     else:
 557                         raise
 558
 559     def __init__(self):
 560         # optional members
 561         self.path = None
 562         self.symlink_target = None
 563         self.linux_attr = None
 564         self.linux_xattr = None
 565         self.posix1e_acl = None
 566         self.posix1e_acl_default = None
 567
 568     def write(self, port, include_path=True):
 569         records = include_path and [(_rec_tag_path, self._encode_path())] or []
 570         records.extend([(_rec_tag_common, self._encode_common()),
 571                         (_rec_tag_symlink_target, self._encode_symlink_target()),
 572                         (_rec_tag_posix1e_acl, self._encode_posix1e_acl()),
 573                         (_rec_tag_linux_attr, self._encode_linux_attr()),
 574                         (_rec_tag_linux_xattr, self._encode_linux_xattr())])
 575         for tag, data in records:
 576             if data:
 577                 vint.write_vuint(port, tag)
 578                 vint.write_bvec(port, data)
 579         vint.write_vuint(port, _rec_tag_end)
 580
 581     @staticmethod
 582     def read(port):
 583         # This method should either: return a valid Metadata object;
 584         # throw EOFError if there was nothing at all to read; throw an
 585         # Exception if a valid object could not be read completely.
 586         tag = vint.read_vuint(port)
 587         try: # From here on, EOF is an error.
 588             result = Metadata()
 589             while True: # only exit is error (exception) or _rec_tag_end
 590                 if tag == _rec_tag_path:
 591                     result._load_path_rec(port)
 592                 elif tag == _rec_tag_common:
 593                     result._load_common_rec(port)
 594                 elif tag == _rec_tag_symlink_target:
 595                     result._load_symlink_target_rec(port)
 596                 elif tag == _rec_tag_posix1e_acl:
 597                     result._load_posix1e_acl_rec(port)
 598                 elif tag ==_rec_tag_nfsv4_acl:
 599                     result._load_nfsv4_acl_rec(port)
 600                 elif tag == _rec_tag_linux_attr:
 601                     result._load_linux_attr_rec(port)
 602                 elif tag == _rec_tag_linux_xattr:
 603                     result._load_linux_xattr_rec(port)
 604                 elif tag == _rec_tag_end:
 605                     return result
 606                 else: # unknown record
 607                     vint.skip_bvec(port)
 608                 tag = vint.read_vuint(port)
 609         except EOFError:
 610             raise Exception("EOF while reading Metadata")
 611
 612     def isdir(self):
 613         return stat.S_ISDIR(self.mode)
 614
 615     def create_path(self, path, create_symlinks=True):
 616         self._create_via_common_rec(path, create_symlinks=create_symlinks)
 617
 618     def apply_to_path(self, path=None, restore_numeric_ids=False):
 619         # apply metadata to path -- file must exist
 620         if not path:
 621             path = self.path
 622         if not path:
 623             raise Exception('Metadata.apply_to_path() called with no path');
 624         if not self._recognized_file_type():
 625             add_error('not applying metadata to "%s"' % path
 626                       + ' with unrecognized mode "0x%x"\n' % self.mode)
 627             return
 628         num_ids = restore_numeric_ids
 629         try:
 630             self._apply_common_rec(path, restore_numeric_ids=num_ids)
 631             self._apply_posix1e_acl_rec(path, restore_numeric_ids=num_ids)
 632             self._apply_linux_attr_rec(path, restore_numeric_ids=num_ids)
 633             self._apply_linux_xattr_rec(path, restore_numeric_ids=num_ids)
 634         except ApplyError, e:
 635             add_error(e)
 636
 637
 638 def from_path(path, statinfo=None, archive_path=None, save_symlinks=True):
 639     result = Metadata()
 640     result.path = archive_path
 641     st = statinfo or xstat.lstat(path)
 642     result._add_common(path, st)
 643     if save_symlinks:
 644         result._add_symlink_target(path, st)
 645     result._add_posix1e_acl(path, st)
 646     result._add_linux_attr(path, st)
 647     result._add_linux_xattr(path, st)
 648     return result
 649
 650
 651 def save_tree(output_file, paths,
 652               recurse=False,
 653               write_paths=True,
 654               save_symlinks=True,
 655               xdev=False):
 656
 657     # Issue top-level rewrite warnings.
 658     for path in paths:
 659         safe_path = _clean_up_path_for_archive(path)
 660         if safe_path != path:
 661             log('archiving "%s" as "%s"\n' % (path, safe_path))
 662
 663     start_dir = os.getcwd()
 664     try:
 665         for (p, st) in recursive_dirlist(paths, xdev=xdev):
 666             dirlist_dir = os.getcwd()
 667             os.chdir(start_dir)
 668             safe_path = _clean_up_path_for_archive(p)
 669             m = from_path(p, statinfo=st, archive_path=safe_path,
 670                           save_symlinks=save_symlinks)
 671             if verbose:
 672                 print >> sys.stderr, m.path
 673             m.write(output_file, include_path=write_paths)
 674             os.chdir(dirlist_dir)
 675     finally:
 676         os.chdir(start_dir)
 677
 678
 679 def _set_up_path(meta, create_symlinks=True):
 680     # Allow directories to exist as a special case -- might have
 681     # been created by an earlier longer path.
 682     if meta.isdir():
 683         mkdirp(meta.path)
 684     else:
 685         parent = os.path.dirname(meta.path)
 686         if parent:
 687             mkdirp(parent)
 688             meta.create_path(meta.path, create_symlinks=create_symlinks)
 689
 690
 691 class _ArchiveIterator:
 692     def next(self):
 693         try:
 694             return Metadata.read(self._file)
 695         except EOFError:
 696             raise StopIteration()
 697
 698     def __iter__(self):
 699         return self
 700
 701     def __init__(self, file):
 702         self._file = file
 703
 704
 705 def display_archive(file):
 706     for meta in _ArchiveIterator(file):
 707         if verbose:
 708             print meta.path # FIXME
 709         else:
 710             print meta.path
 711
 712
 713 def start_extract(file, create_symlinks=True):
 714     for meta in _ArchiveIterator(file):
 715         if verbose:
 716             print >> sys.stderr, meta.path
 717         xpath = _clean_up_extract_path(meta.path)
 718         if not xpath:
 719             add_error(Exception('skipping risky path "%s"' % meta.path))
 720         else:
 721             meta.path = xpath
 722             _set_up_path(meta, create_symlinks=create_symlinks)
 723
 724
 725 def finish_extract(file, restore_numeric_ids=False):
 726     all_dirs = []
 727     for meta in _ArchiveIterator(file):
 728         xpath = _clean_up_extract_path(meta.path)
 729         if not xpath:
 730             add_error(Exception('skipping risky path "%s"' % dir.path))
 731         else:
 732             if os.path.isdir(meta.path):
 733                 all_dirs.append(meta)
 734             else:
 735                 if verbose:
 736                     print >> sys.stderr, meta.path
 737                 meta.apply_to_path(path=xpath,
 738                                    restore_numeric_ids=restore_numeric_ids)
 739     all_dirs.sort(key = lambda x : len(x.path), reverse=True)
 740     for dir in all_dirs:
 741         # Don't need to check xpath -- won't be in all_dirs if not OK.
 742         xpath = _clean_up_extract_path(dir.path)
 743         if verbose:
 744             print >> sys.stderr, dir.path
 745         dir.apply_to_path(path=xpath, restore_numeric_ids=restore_numeric_ids)
 746
 747
 748 def extract(file, restore_numeric_ids=False, create_symlinks=True):
 749     # For now, just store all the directories and handle them last,
 750     # longest first.
 751     all_dirs = []
 752     for meta in _ArchiveIterator(file):
 753         xpath = _clean_up_extract_path(meta.path)
 754         if not xpath:
 755             add_error(Exception('skipping risky path "%s"' % meta.path))
 756         else:
 757             meta.path = xpath
 758             if verbose:
 759                 print >> sys.stderr, '+', meta.path
 760             _set_up_path(meta, create_symlinks=create_symlinks)
 761             if os.path.isdir(meta.path):
 762                 all_dirs.append(meta)
 763             else:
 764                 if verbose:
 765                     print >> sys.stderr, '=', meta.path
 766                 meta.apply_to_path(restore_numeric_ids=restore_numeric_ids)
 767     all_dirs.sort(key = lambda x : len(x.path), reverse=True)
 768     for dir in all_dirs:
 769         # Don't need to check xpath -- won't be in all_dirs if not OK.
 770         xpath = _clean_up_extract_path(dir.path)
 771         if verbose:
 772             print >> sys.stderr, '=', xpath
 773         # Shouldn't have to check for risky paths here (omitted above).
 774         dir.apply_to_path(path=dir.path,
 775                           restore_numeric_ids=restore_numeric_ids)