fortune/strfile/strfile.8

   1 .\"     $NetBSD: strfile.8,v 1.7 1999/09/09 06:30:10 simonb Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" Ken Arnold.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"     This product includes software developed by the University of
  20 .\"     California, Berkeley and its contributors.
  21 .\" 4. Neither the name of the University nor the names of its contributors
  22 .\"    may be used to endorse or promote products derived from this software
  23 .\"    without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  35 .\" SUCH DAMAGE.
  36 .\"
  37 .\"     @(#)strfile.8   8.1 (Berkeley) 6/9/93
  38 .\"
  39 .Dd June 9, 1993
  40 .Dt STRFILE 8
  41 .Os
  42 .Sh NAME
  43 .Nm strfile ,
  44 .Nm unstr
  45 .Nd "create a random access file for storing strings"
  46 .Sh SYNOPSIS
  47 .Nm strfile
  48 .Op Fl iorsx
  49 .Op Fl c Ar char
  50 .Ar source_file
  51 .Op Ar output_file
  52 .Nm unstr
  53 .Ar source_file
  54 .Sh DESCRIPTION
  55 .Nm Strfile
  56 reads a file containing groups of lines separated by a line containing
  57 a single percent
  58 .Ql \&%
  59 sign and creates a data file which contains
  60 a header structure and a table of file offsets for each group of lines.
  61 This allows random access of the strings.
  62 .Pp
  63 The output file, if not specified on the command line, is named
  64 .Ar source_file Ns Sy .out .
  65 .Pp
  66 The options are as follows:
  67 .Bl -tag -width "-c char"
  68 .It Fl c Ar char
  69 Change the delimiting character from the percent sign to
  70 .Ar char .
  71 .It Fl i
  72 Ignore case when ordering the strings.
  73 .It Fl o
  74 Order the strings in alphabetical order.
  75 The offset table will be sorted in the alphabetical order of the
  76 groups of lines referenced.
  77 Any initial non-alphanumeric characters are ignored.
  78 This option causes the
  79 .Dv STR_ORDERED
  80 bit in the header
  81 .Ar str_flags
  82 field to be set.
  83 .It Fl r
  84 Randomize access to the strings.
  85 Entries in the offset table will be randomly ordered.
  86 This option causes the
  87 .Dv STR_RANDOM
  88 bit in the header
  89 .Ar str_flags
  90 field to be set.
  91 .It Fl s
  92 Run silently; don't give a summary message when finished.
  93 .It Fl x
  94 Note that each alphabetic character in the groups of lines is rotated
  95 13 positions in a simple caesar cypher.
  96 This option causes the
  97 .Dv STR_ROTATED
  98 bit in the header
  99 .Ar str_flags
 100 field to be set.
 101 .El
 102 .Pp
 103 The format of the header is:
 104 .Bd -literal
 105 #define VERSION 1
 106 unsigned long   str_version;    /* version number */
 107 unsigned long   str_numstr;     /* # of strings in the file */
 108 unsigned long   str_longlen;    /* length of longest string */
 109 unsigned long   str_shortlen;   /* length of shortest string */
 110 #define STR_RANDOM      0x1     /* randomized pointers */
 111 #define STR_ORDERED     0x2     /* ordered pointers */
 112 #define STR_ROTATED     0x4     /* rot-13'd text */
 113 unsigned long   str_flags;      /* bit field for flags */
 114 char str_delim;                 /* delimiting character */
 115 .Ed
 116 .Pp
 117 All fields are written in big-endian byte order.
 118 .Pp
 119 The purpose of
 120 .Nm unstr
 121 is to undo the work of
 122 .Nm strfile .
 123 It prints out the strings contained in the file
 124 .Ar source_file
 125 in the order that they are listed in
 126 the header file
 127 .Ar source_file Ns Pa .dat
 128 to standard output.
 129 It is possible to create sorted versions of input files by using
 130 .Fl o
 131 when
 132 .Nm strfile
 133 is run and then using
 134 .Nm unstr
 135 to dump them out in the table order.
 136 .Sh SEE ALSO
 137 .Xr byteorder 3 ,
 138 .Xr fortune 6
 139 .Sh FILES
 140 .Bl -tag -width strfile.out -compact
 141 .It Pa strfile.out
 142 default output file.
 143 .El
 144 .Sh HISTORY
 145 The
 146 .Nm strfile
 147 utility first appeared in
 148 .Bx 4.4 .