home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_200 / 265_01 / format.doc < prev    next >
Text File  |  1990-02-15  |  10KB  |  463 lines
  1.  
  2.  
  3.  
  4.                   - 1 -
  5.  
  6.  
  7.  
  8.        1.  Introduction
  9.  
  10.        This document describes the physical and    logical     format     of
  11.        the data    exchange standard of the C Users Group.
  12.  
  13.        This standard  allowes  it  to  transfer     data  files  among
  14.        different systems.
  15.  
  16.  
  17.        2.  Exchange Media
  18.  
  19.        This  standard  does  not  define  only    some  general  data
  20.        exchange     medias.   All possible    medias may be used, as long
  21.        as CUG has the necessary    hardware  and  driver  software     to
  22.        read and    write the physical format.
  23.  
  24.        Because of the real-world systems, at  least  the  following
  25.        medias should be    supported:
  26.  
  27.       - 8 inch, single sided, single  density  diskette  (about
  28.         254KB?)
  29.  
  30.       - 5.25  inch,     double     sided,     double     density   diskette
  31.         (360KB) as found in    the IBM    PC family of computers
  32.  
  33.       - 3.5    inch, ????, ???    diskette (720KB) as  found  in    the
  34.         newer  IBM PS/2 systems and    many smaller machines (like
  35.         Atari ST)
  36.  
  37.       - 9 track industrial standard    tape
  38.  
  39.        From all    medias only the    9-track    tape needs explantation: It
  40.        is  for    some  systems  easier to read tapes than diskettes.
  41.        Other systems  (Unisys  Series 1100  e.    g.)  don't  support
  42.        diskette     drives    but tapes.  To support such systems, the 9-
  43.        track tape is the only alternative and must be  included     as
  44.        exchange     media.    (I'm not sure if it's better to    write tapes
  45.        in the EBCDIC character set????).
  46.  
  47.        Other exchange medias may be standardized if requested.    The
  48.        most  important    fact  is  that    there  must be input/output
  49.        drivers which are able to read the media    as a single file,
  50.        bypassing the operating system directory    structure.
  51.  
  52.  
  53.        3.  Archive Format
  54.  
  55.        The archive file    is a single sequential file that contains a
  56.        well-defined  set  of  header  and  data     blocks.   A single
  57.        header/data block set describes an  entire  file.   Multiple
  58.        sets may    be included in a single    archive    file, as long as no
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.                   - 2 -
  71.  
  72.  
  73.  
  74.        single set is devided across archive file boundaries.
  75.  
  76.        The archive file    contains only true ascii  characters  (that
  77.        is, characters within the range 0..127)1.
  78.  
  79.        The archive file    format bases on    the  X/OPEN  cpio  standard
  80.        (with -c    option active).     One goal of this exchange standard
  81.        is that X/OPEN cpio disks can be    read and written  with    CUG
  82.        utilities.
  83.  
  84.        3.1  File Layout
  85.  
  86.        As mentioned above, the file contains  a     continous  set     of
  87.        header (HDRB) and data (DATB) blocks.  A    special    end-of-file
  88.        header block (EOFB) annonces the    end of    the  archive  file.
  89.        Note  that this block may be present before the physical    end
  90.        of file.     There is no corresponding begin-of-file block.
  91.  
  92.             Figure 1....  general archive layout
  93.           <HDRB><DATB><HDRB><DATB>...<HDRB><DATB><EOFB>
  94.  
  95.        3.2  Header Block (HDRB)    Format
  96.  
  97.        The header block    closely    corrosponds to the X/OPEN cpio file
  98.        header  standard.   It  can  be    described  by the following
  99.        scanf():
  100.  
  101.        scanf("%6o%6o%6o%6o%6o%6o%6o%6o%11lo%6o%6o%s",
  102.  
  103.       >isn't this an error and the following correct:  <
  104.       >scanf("%6o%6o%6o%6o%6o%6o%6o%6o%11lo%6o%11lo%s",<
  105.  
  106.          &Hdr.h_magic, &Hdr.h_dev, &Hdr.h_ino, &Hdr.h_mode,
  107.          &Hdr.h_uid, &Hdr.h_gid, &Hdr.h_nlink, &Hdr.h_rdev,
  108.          &Longtime,    &Hdr.h_namesize, &Longfile, Hdr.h_name);
  109.  
  110.        Because most of the fields in the header     record     only  have
  111.        meaning     on  Unix  systems,  they  are    only  included    for
  112.        conformance to the X/OPEN standard and are not used  by    the
  113.        exchange     standard.  Their exact    meaning    in the CUG exchange
  114.        format is as follows2:
  115.  
  116.  
  117.        __________
  118.  
  119.     1. If the target system    ueses a    different character set,
  120.        conversion takes place when reading and writing the
  121.        exchange media not when building or    extracting the
  122.        archive files.
  123.  
  124.     2. Note    that the term "not used" means that the    field is
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.                   - 3 -
  137.  
  138.  
  139.  
  140.        h_magic          Identifies the record as header block.   Must
  141.               be  the constant 070707 (octal).    Every other
  142.               value indicates an error.
  143.  
  144.        h_dev          not used
  145.  
  146.        h_ino          not used
  147.  
  148.        h_mode          not used,    set  to     0100666  on  output  (this
  149.               setting identifies it as a regular file which
  150.               can be read and written by  everyone  to    the
  151.               Unix cpio)
  152.  
  153.        h_uid          not used
  154.  
  155.        h_gid          not used
  156.  
  157.        h_nlink          not used,    ignored    on input,  set    to  one on
  158.               output
  159.  
  160.        h_rdev          not used
  161.  
  162.        Longtime          not used
  163.  
  164.        h_namesize     This field contains the length of     the  null-
  165.               terminated   pathname  h_name  including    the
  166.               null-byte.
  167.  
  168.        Longfile          This field contains the  exact size  of    the
  169.               following      data    block  (DATB).     Immedeatly
  170.               after reading Longfile number bytes from    the
  171.               archive,    the  next  archive record must be a
  172.               HDRB (or EOFB).
  173.  
  174.        h_name          File name    of the following data block (DATB).
  175.               When  extracting    the  archive, the following
  176.               data block is stored under this name.
  177.  
  178.               Note that    there are  restrictions     for  file-
  179.               name  construction: No system-dependant parts
  180.               should be    included.  This    is  even  true    for
  181.               pathnames,   which  are  not  common  to    all
  182.               systems.    So the following  rules     should     be
  183.               applied to file name construction.  They base
  184.               on the KERMIT file transfer protocol and will
  185.  
  186.  
  187.        ____________________________________________________________
  188.  
  189.        ignored on input and    set to zero on output.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.                   - 4 -
  203.  
  204.  
  205.  
  206.               guarantee    that the file can be created  under
  207.               virtually     every operating system.  Violation
  208.               of  this    rules  may  cause  useless  of    the
  209.               archive file on some OS.
  210.  
  211.              - The only allowed characters in filenames
  212.                are    digits    and  upper-case    alphabetics
  213.                (ascii 0x30-0x39 and    0x41-0x5a).
  214.  
  215.              - A  filename    consits     of   at   most      8
  216.                characters,    an  optional  period and at
  217.                most    additional  three  characters.     If
  218.                you    want  to  specify  the    last  three
  219.                characters, the period _m_u_s_t be included.
  220.                This     are  the  same    rules as for MS-DOS
  221.                files (without pathnames).
  222.  
  223.              - No  system-dependant     information  (like
  224.                drive  specifiers  or  pathnames) may be
  225.                included.
  226.  
  227.        3.3  EOF Block (EOFB) Format
  228.     
  229.        The EOF block is a special case of the header  block.   It's
  230.        an  ordinary  header  block  with  Longfile  set    to zero    and
  231.        h_name set to the constant "TRAILER!!!".
  232.  
  233.        3.4  Data Block (DATB) Format
  234.  
  235.        The data    block contains the files data.    No file    is splitted
  236.        across  two  or    more  data  blocks.   To achive    portability
  237.        between different systems, the following     restrictions  must
  238.        be applied to the data block:
  239.  
  240.       - The     data    block    contains   only      printable   ascii
  241.         characters.      The  one  and     only  exception  from this
  242.         general rule is the    newline    character, which is used to
  243.         partition source lines.
  244.  
  245.       - The     newline  sequence  consits  of     a  single  newline
  246.         character ('0, ascii 0x10).     This representation is    not
  247.         affected  by  the  target  system    newline      sequence.
  248.         Newline conversion is (if needed) done when    reading    and
  249.         writing the    archive    files.
  250.  
  251.       - Tabulation characters are  expanded     when  the  archive
  252.         file   is    written.    They   are     not  automatically
  253.         recompressed when extracting the archive file.  This is
  254.         neccessary    because    of the different tab settings under
  255.         different operating    systems    (some don't support tabs at
  256.         all).
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.                   - 5 -
  269.  
  270.  
  271.  
  272.        4.  Implementation
  273.  
  274.        The exchange utilities are divided in two parts:     The  first
  275.        one  read  or  write  the  exchange  media,  constructing an
  276.        ordinary    sequential file    that can  be  processed     by  normal
  277.        operating  system  calls.   The    second part reads or writes
  278.        these sequential    files and extracts the single source files.
  279.  
  280.  
  281.        5.  Usage of the archive/unarchive Utilities
  282.  
  283.        - usage of unarchive utility:
  284.      read  file start-sector byte-length
  285.            file is the name    of the sequential output file
  286.            start-sector is the first sector    read form
  287.            sector length is    computed using the byte    length
  288.  
  289.        - usage of archive utility:
  290.      write file start-sector
  291.            file is the name    of the sequential input    file
  292.            start-sector is the first sector    written    to
  293.            the byte    length is determined by    the length of the input
  294.            file. no    input file may be larger than a    single disk
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.                  CONTENTS
  339.  
  340.  
  341.        1.  Introduction.........................................  1
  342.  
  343.        2.  Exchange Media.......................................  1
  344.  
  345.        3.  Archive Format.......................................  1
  346.        3.1    File Layout.....................................  2
  347.        3.2    Header Block (HDRB) Format......................  2
  348.        3.3    EOF Block (EOFB) Format.........................  4
  349.        3.4    Data Block (DATB) Format........................  4
  350.  
  351.        4.  Implementation.......................................  5
  352.  
  353.        5.  Usage of the    archive/unarchive Utilities.............  5
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.                   - i -
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.                  LIST OF FIGURES
  408.  
  409.  
  410.        Figure 1.  general archive layout........................  2
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.                   - ii -
  459.  
  460.  
  461.  
  462.  
  463.