# Tape archive (tar) tools

The /ar/tar.fs unit contains tool to manipulate archives of the "tar" format
originating from UNIX. It does so through two structs, "record" and "tar".

## Record

This wraps a 512 bytes tar header record containing metadata about the
represented element. You are supposed to use it with a pointer to the actual
data. For example, if you've read a tar header sector to "here", then "here
recordname" will yield the name of the record.

Fields:

zname
omode
ouid
ogid
ofilesz
omtime
checksum
zlinkname
  Pointer to the address corresponding to the record field.

type
  Character corresponding to the record type ('5'=directory, NULL=file)

Words:

RECORDSSZ ( -- 512 )
  Size in bytes of a record structure.

empty? ( rec -- f )
  Whether the record is empty (starts with null characters).

dir? ( rec -- f )
  Whether the record is a directory (type = '5')

recordname ( rec -- str )
  Name of the file or directory. If the name has a trailing '/', it is removed.
  This name is stored in a static buffer that is overwritten at each :name call.

recordsize ( rec -- sz )
  Parsed version of "ofilesz". This is the file size in bytes that follow the
  record.

## Tar

This structure iterates over a Drive, interpreting sectors as tar records. At
creation, it is supplied a Drive struct as well as an "origin" sector. Is is
then possible to iterate over record through "nextrecord" or to find a record
with a specific name through "tarfind".

Fields:

drv
  Drive we're iterating through

sec0
  Origin sector number

sec
  Sector of the current record

buf(
  Buffer with the contents of the current sector

Words:

newtar ( sec0 drv -- tar )
  Create new Tar struct with specified Drive and origin sector.

sec! ( sec tar -- )
  Read and set current sector.

record ( tar -- rec )
  TarRecord we're currently pointing at.

rewind ( tar -- )
  Set current sector to origin sector.

nextrecord ( tar -- rec )
  Advance current sector to next record and return it.

tarfind ( name tar -- rec? f )
  Rewind, then iterate over record over a record of the specified name is found.
  If found, f=1 and rec is set. Otherwise, f=0 and rec is absent.
