.\" $Id: binpack.man,v 1.20 2012/08/09 19:17:10 ksb Exp $ .\" by Kevin Braunsdorf .\" $Compile: Display%h .\" $Display: ${groff:-groff} -Tascii -man %f |${PAGER:-less} .\" $Display(*): ${groff:-groff} -T%s -man %f .\" $Install: %b -mDeinstall %o %f && cp %f ${DESTDIR}/usr/local/man/man1/binpack.1 .\" $Deinstall: ${rm-rm} -f ${DESTDIR}/usr/local/man/[cm]a[nt]1/binpack.1* .TH BINPACK 1 LOCAL .SH NAME binpack - pack files into shell commands to create uniform media .SH SYNOPSIS .ds PN "binpack \fI\*(PN\fP [\fB\-Nvz\fP] [\fB\-b\fP\~\fIbytes\fP] [\fB\-E\fP\~\fIname\fP] [\fB\-n\fP\~\fIfiles\fP] [\fB\-o\fP\~\fIoverhead\fP] [\fB\-p\fP\~\fIpacking\fP] [\fB\-r\fP\~\fIround\fP] [\fB\-w\fP\~\fIwindow\fP] [\fIcmd\fP] .br \fI\*(PN\fP [\fB\-uvz\fP] [\fB\-b\fP\~\fIbytes\fP] [\fB\-E\fP\~\fIname\fP] [\fB\-n\fP\~\fIfiles\fP] [\fB\-p\fP\~\fIpacking\fP] [\fB\-w\fP\~\fIwindow\fP] [\fIcmd\fP] .br \fI\*(PN\fP \fB\-h\fP .br \fI\*(PN\fP \fB\-V\fP .SH DESCRIPTION This program \fI\*(PN\fP approximates a solution to one of the classic Computer Science non-polynomial tasks ("bin packing"). .P Given a list of files on \fIstdin\fP the program \fBstat\fP(2)'s each file to compute a size. That size is biased by adding \fIoverhead\fP, then rounded to even \fIround\fP units, and finally by adding \fIpacking\fP. .P 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 \fIwindow\fP will fit in the bin, that bin forms an argument list to \fIcmd\fP. Files which are larger than \fIbytes\fP are each given to \fIcmd\fP singly. .P The output commands are \fBnot\fP given to a shell, rather they are output to \fIstdout\fP which might filter them before sending them to a shell. .P New files are read from \fIstdin\fP to refill the \fIwindow\fP. This process is repeated until the EOF, at which point all remaining bins are filled (the last is usually short a bit). Any \fIwindow\fP smaller that \fIfiles\fP limits the size of each output bin, in fact a small window \fBseriously limits\fP the packing optimization. .P This program is excellent for assembling files on ISO images for CD-ROM burns, floppy packing, shell archives, or filling off-site tapes. .SH OPTIONS This command reads the environment variable \fBBINPACK\fP for options. .TP .nf \fB\-b\fP \fIbytes\fP .fi 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 \fB\-N\fP option sets a different default based on the number of characters allow in a program's arguments by \fIexecve\fP(2). .TP .nf \fB\-E\fP \fIname\fP .fi 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. .sp The empty \fIname\fP 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 certainly not be found in $PATH. .\" See Simple Commands from the shell manual page, if you are not .\" shell literate. .TP .nf \fB\-h\fP .fi Print a brief help message. .TP .nf \fB\-n\fP \fIfiles\fP .fi The max number of files per bin. For example when inodes are limited. .TP .nf \fB\-N\fP .fi Use the length of the name of each input \fIfile\fP, not the size \fIstat\fP(2) returns. This allows \fI\*(PN\fP to act as a command compaction processor for \fIxapply\fP (or the shell). Under this option the default \fIbytes\fP 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 additional allowance is made for any \fIname\fP assignment prefixed to the command, and the words in \fIcmd\fP. .TP .nf \fB\-o\fP \fIoverhead\fP .fi How much overhead per file, after unit rounding (default "0"). Under \fB\-N\fP the default is the size of an argument pointer (\fBsizeof(char *)\fP). .TP .nf \fB\-p\fP \fIpacking\fP .fi Packing header size, added before rounding (default "0"). If \fI\*(PN\fP overruns the limit for an argument vector, bais computation with this parameter. Some systems have a few bytes of undocumented additional overhead. .TP .nf \fB\-r\fP \fIround\fP .fi Specify the round units to pack with (default "1"). For a UFS one would pick the frag-size (\fB\-f\fP) from either \fBnewfs\fP 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. .TP .nf \fB\-v\fP .fi Be verbose by reporting packing statistics on \fIstderr\fP. .TP .nf \fB\-u\fP .fi Change the input format to a 2 column file where the user provides the size for each element on column 1, in which case the element doesn't have to be a file (because \fI\*(PN\fP doesn't have to \fBstat\fP(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 \fBstrtol\fP(3). .TP .nf \fB\-V\fP .fi Show some version information. .TP .nf \fB\-w\fP \fIwindow\fP .fi The window of files to consider for packing (default 8192), if the window size is too small to allow any optimization a diagnostic is issued on \fIstderr\fP. The product of the average size of a file times the number of files in the window should be at least \fIbytes\fP. 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 \fI\*(PN\fP. If the files are sorted by size, then you'll need even more \fIwindow\fP. .TP .nf \fB\-z\fP .fi Read stdin as `find \-print0' output. .SH EXAMPLES .TP .nf find . \-type f \-print |\fI\*(PN\fP \-r 2048 \-b 700m-62k \-p 128 \fImy-burn\fP .fi Break the files in this directory into nearly full ISO images. The \fB2048\fP is the size of a CD block, the \fB700m-62k\fP is the size of my CD minus the over-head for an empty ISO filesystem. The \fB128\fP is about the overhead for the directory and Rock Ridge map file. Tune as thou mote. .TP .nf \fI\*(PN\fP \-b '700m-2*31k?' \-V .fi Show version information and a table of the units \fB\-b\fP accepts. .TP .nf find . \-type f \-print | \fI\*(PN\fP \-b 9999 \-\- wc \-c |sh |grep total\e$ .fi Show how \fI\*(PN\fP 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. .TP .nf find . \-type f \-print0 | \fI\*(PN\fP \-zN \-\- grep token |sh .fi Back the filename into maximum size argument lists and feed them to the shell to \fIgrep\fP for \*(lqtoken\*(rq. Note that this does permute the list of input files, so don't depend on the order of them. (Also \fIfind\fP's output order is not really stable.) .TP .nf find . \-type f \-print0 | \fI\*(PN\fP \-zN \-\- grep token |xapply \-fP nice \- .fi Same as above, but run 4 in parallel via \fIxapply\fP(1l). .TP .nf \fI\*(PN\fP \-b 1440k \-n 28 \-r 4096 make-floppy ../$N.iso burncd \-f /dev/acd0c \-s 48 \-e data $N.iso fixate rm \-r ../burn$$ $N.iso cdcontrol \-f /dev/acd0 eject .fi .RE .SH AUTHOR KS Braunsdorf .br Provided by the Non-Player Character Guild .br binpack at ksb.npcguild.org. .SH "SEE ALSO" .hlm 0 sh(1), wc(1), find(1), burncd(8), mkisofs(1), xapply(1l), mt(1), newfs(8), strtol(3), cdcontrol(1)