BINPACK(1)                                                          BINPACK(1)



NAME
       binpack - pack files into shell commands to create uniform media

SYNOPSIS
       binpack  [-Nvz] [-b bytes] [-E name] [-n files] [-o overhead] [-p pack-
       ing] [-r round] [-w window] [cmd]
       binpack [-uvz] [-b bytes] [-E name] [-n files] [-p packing] [-w window]
       [cmd]
       binpack -h
       binpack -V

DESCRIPTION
       This program binpack approximates a solution to one of the classic Com-
       puter Science non-polynomial tasks ("bin packing").

       Given a list of files on stdin the program stat(2)'s each file to  com-
       pute  a  size.  That size is biased by adding overhead, then rounded to
       even round units, and finally by adding packing.

       Each media (called a "bin") starts with 0 bytes in  it,  as  files  are
       added  to  the  bin its size grows by the metric computed for the files
       added.  When no file in the present window will fit in  the  bin,  that
       bin  forms  an argument list to cmd.  Files which are larger than bytes
       are each given to cmd singly.

       The output commands are not given to a shell, rather they are output to
       stdout which might filter them before sending them to a shell.

       New  files  are  read from stdin to refill the window.  This process is
       repeated until the EOF, at which point all remaining  bins  are  filled
       (the  last is usually short a bit).  Any window smaller that files lim-
       its the size of each output bin, in fact a small window seriously  lim-
       its the packing optimization.

       This program is excellent for assembling files on ISO images for CD-ROM
       burns, floppy packing, shell archives, or filling off-site tapes.

OPTIONS
       This command reads the environment variable BINPACK for options.

       -b bytes
              Specify the bin size (default "1440k").  Other useful values are
              "700m"  for a modern CDROM, "4200m" for a DVD, and "8400m" for a
              dual-layer DVD.  See the EXAMPLES below for the list  of  scalar
              suffixes  available.   Note  that the -N option sets a different
              default based on the number of characters allow in  a  program's
              arguments by execve(2).

       -E name
              This  provides  the information needed to detect over-flow bins.
              The specified environment variable is assigned the computed size
              for each bin as the first item on each output line.

              The  empty  name outputs the size without an assignment, for the
              next filter.  In this case the shell will not be able to run the
              output  stream  directly,  as  the integer size will almost cer-
              tainly not be found in $PATH.

       -h
              Print only a brief help message.

       -n files
              The max number of files per bin.  For example  when  inodes  are
              limited.

       -N
              Use  the  length  of  the  name of each input file, not the size
              stat(2) returns.  This allows binpack to act as a  command  com-
              paction  processor for xapply (or the shell).  Under this option
              the default bytes is the number of characters  available  in  an
              argument list with an allowance made for the current environment
              (which counts against that limit on most  systems).   And  addi-
              tional allowance is made for any name assignment prefixed to the
              command, and the words in cmd.

       -o overhead
              How much overhead per file, after unit rounding  (default  "0").
              Under  -N  the  default  is  the  size  of  an  argument pointer
              (sizeof(char *)).

       -p packing
              Packing header size, added before rounding  (default  "0").   If
              binpack overruns the limit for an argument vector, bais computa-
              tion with this parameter.  Some systems  have  a  few  bytes  of
              undocumented additional overhead.

       -r round
              Specify  the  round units to pack with (default "1").  For a UFS
              one would pick the frag-size (-f) from either newfs or from  the
              disk label.  For a CD burn one might use 2k, as that is the size
              of a block on a Compact Disc.

       -v
              Be verbose by reporting packing statistics on stderr.

       -u
              Change the input format to a 2 column file where the  user  pro-
              vides  the  size for each element on column 1, in which case the
              element doesn't have to be a file (because binpack doesn't  have
              to stat(2) it to deduce the size).  If only 1 column is provided
              the name of the element is the size.  The size is converted with
              strtol(3).

       -V
              Show only the standerd version banner.

       -w window
              The  window  of files to consider for packing (default 8192), if
              the window size is too small to allow any optimization  a  diag-
              nostic  is issued on stderr.  The product of the average size of
              a file times the number of files in  the  window  should  be  at
              least  bytes.   To allow for even moderate optimization at least
              an extra 40% more slots should be allowed.  If you do  not  want
              the items permuted, then you do not want to use binpack.  If the
              files are sorted by size, then you'll need even more window.

       -z
              Read stdin as 'find -print0' output.

EXAMPLES
       find . -type f -print |binpack -r 2048 -b 700m-62k -p 128 my-burn
              Break the files in this directory into nearly full  ISO  images.
              The  2048 is the size of a CD block, the 700m-62k is the size of
              my CD minus the over-head for an empty ISO filesystem.  The  128
              is about the overhead for the directory and Rock Ridge map file.
              Tune as thou mote.

       binpack -b '700m-2*31k?' -V
              Show version information and a table of the units -b accepts.

       find . -type f -print | binpack -b 9999 -- wc -c |sh |grep total\$
              Show how binpack might pack the present directory into less than
              10,000  byte bins.  On a large source directory this resulted in
              1150 bins with an average size of 9925 bytes, including the last
              bin  of  4187  bytes, that is about 0.8% above the best possible
              solution.

       find . -type f -print0 | binpack -zN -- grep token |sh
              Back the filename into maximum size argument lists and feed them
              to  the  shell to grep(1) for "token".  Note that this does per-
              mute the list of input files, so don't depend on  the  order  of
              them.  (Also find's output order is not really stable.)

       find . -type f -print0 | binpack -zN -- grep token |xapply -fP nice -
              Same as above, but run 4 in parallel via xapply(1l).

       binpack -b 1440k -n 28 -r 4096 make-floppy <packing.list
              Pack  files onto a floppy, follow the instructions in /etc/disk-
              tab for making a floppy, viz. for a list of files  that  average
              about  48k.   The  script  "make-floppy"  should  prompt for the
              insertion of a floppy, wait for a  confirmation  from  /dev/tty,
              then  build a filesystem on the floppy device and copy the files
              in its argument list to that floppy, unmount the floppy, ask the
              operator to eject the floppy.

       newfs -a 2880 -e 2880 -h 29 -p 0 -c 80 -o space -m 0 -b 4096 -f 4096 -t 1 -u 36 -l 1 -i 65536 fd0.1440
              A  good tune to make the raw floppies for the command above, the
              -b option might better be  8192  when  most  of  the  files  are
              larger.

       binpack -E TOTAL -b 1440k -n 28 -r 4096 make-floppy <packing.list |sh -x
              Same  as  the  above, but the make-floppy script may consult the
              environment variable $TOTAL for the total size (in bytes) of the
              payload.   Also  different  in that we actually execute the com-
              mands with the shell, in trace mode.

BUGS
       This version will only pack files up to about 3,483,774,700 bytes long.

       The  parameters  output are protected from the shell's standard quoting
       rules, so filename with embedded whitespace or quotes are  passed  cor-
       rectly  to  cmd.   This leads to some issues with complex processing of
       stdout by programs other than the shell.  There is no  option  to  turn
       shell quoting off.

       You need to code a burn script to make the ISO and burn in a pipe-line,
       something like (replace the -s 48 with the speed of your CD burner):
              echo "Enter CD number return to burn (as 2 or 2 3 for 2 of 3)"
              read N junk
              mkdir ../burn$$
              find "$@" -depth -print0 | cpio -zpld ../burn$$
              (cd ../burn$$ && mkisofs -V "Disc $N ${junk:+of $junk}" -r -J . ) >../$N.iso
              burncd -f /dev/acd0c -s 48 -e data $N.iso fixate
              rm -r ../burn$$ $N.iso
              cdcontrol -f /dev/acd0 eject

AUTHOR
       KS Braunsdorf
       Provided by the Non-Player Character Guild
       binpack at ksb.npcguild.org.

SEE ALSO
       sh(1),  wc(1),  find(1),  burncd(8),  mkisofs(1),  xapply(1l),   mt(1),
       newfs(8), strtol(3), cdcontrol(1)



                                     LOCAL                          BINPACK(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | BUGS | AUTHOR | SEE ALSO