Debian Codegraph @

upstream/debian-unstable/man1/strfile.1

raw
1 .\" $NetBSD: strfile.8,v 1.3 1995/03/23 08:28:45 cgd Exp $
2 .\"
3 .\" Copyright (c) 1989, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\"
7 .\" This code is derived from software contributed to Berkeley by
8 .\" Ken Arnold.
9 .\"
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
12 .\" are met:
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
18 .\" 3. All advertising materials mentioning features or use of this software
19 .\" must display the following acknowledgement:
20 .\" This product includes software developed by the University of
21 .\" California, Berkeley and its contributors.
22 .\" 4. Neither the name of the University nor the names of its contributors
23 .\" may be used to endorse or promote products derived from this software
24 .\" without specific prior written permission.
25 .\"
26 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
27 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
29 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
30 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
35 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .\" SUCH DAMAGE.
37 .\"
38 .\" @(#)strfile.8 8.1 (Berkeley) 6/9/93
39 .\"
40 .\" This man page has been heavily modified, like the files it refers
41 .\" to, by Amy Lewis. Changes to command line, and a different style of
42 .\" macros for Linux systems.
43 .\"
44 .TH STRFILE 1 "June 9, 1993 [Apr. '97]" "4th Berkeley Distribution" "UNIX System Manager's Manual"
45 .SH NAME
46 strfile \- create a random access file for storing strings
47 .br
48 unstr \- dump strings in pointer order
49 .SH SYNOPSIS
50 .BR strfile " [" \-iorsx "] [" \-c
51 .IR char "] " sourcefile " [" outputfile ]
52 .br
53 .BR unstr " [" \-c
54 .IR char "] " datafile [ .ext ]
55 .RI [ outputfile ]
56 .SH DESCRIPTION
57 .B strfile
58 reads a file containing groups of lines separated by a line containing
59 a single percent `%' sign (or other specified delimiter character) and
60 creates a data file which contains a header structure and a table of
61 file offsets for each group of lines. This allows random access of the
62 strings.
63 .PP
64 The output file, if not specified on the command line, is named
65 .IR sourcefile.dat .
66 .PP
67 The purpose of
68 .B unstr
69 is to undo the work of
70 .BR strfile .
71 It prints out the strings contained in the sourcefile, which is
72 .I datafile.ext
73 without its extension, or
74 .I datafile
75 if no extension is specified (in this case, the extension
76 .I .dat
77 is added to the name of the datafile) in the order
78 that they are listed in the header file
79 .IR datafile .
80 If no
81 .I outputfile
82 is specified, it prints to standard output; otherwise it prints
83 to the file specified.
84 .B unstr
85 can also universally change the delimiter character in a strings file.
86 It is possible to create sorted versions of input files by using
87 .B strfile \-o
88 and then using
89 .B unstr
90 to dump them out in the table order.
91 .SS Options
92 The options are as follows:
93 .TP
94 .BI "\-c " char
95 Change the delimiting character from the percent sign to
96 .IR char .
97 This option is available for both
98 .BR strfile " and " unstr .
99 .TP
100 .B \-i
101 Ignore case when ordering the strings.
102 .TP
103 .B \-o
104 Order the strings in alphabetical order. The offset table will be
105 sorted in the alphabetical order of the groups of lines referenced.
106 Any initial non-alphanumeric characters are ignored. This option
107 causes the STR_ORDERED bit in the header
108 .I str_flags
109 field to be set. (It also now really does sort! It didn't used to).
110 .TP
111 .B \-r
112 Randomize access to the strings. Entries in the offset table will be
113 randomly ordered. This option causes the STR_RANDOM bit in the header
114 .I str_flags
115 field to be set. (And really does randomize)
116 .TP
117 .B \-s
118 Run silently; don't give a summary message when finished.
119 .TP
120 .B \-x
121 Note that each alphabetic character in the groups of lines is rotated
122 13 positions in a simple caesar cypher. This option causes the
123 STR_ROTATED bit in the header
124 .I str_flags
125 field to be set. Note that it
126 .B does not
127 rotate the strings--that operation must be performed separately.
128 .SS Header
129 The format of the header is:
130 .PP
131 #define VERSION 1
132 .br
133 unsigned long str_version; /* version number */
134 .br
135 unsigned long str_numstr; /* # of strings in the file */
136 .br
137 unsigned long str_longlen; /* length of longest string */
138 .br
139 unsigned long str_shortlen; /* shortest string length */
140 .br
141 #define STR_RANDOM 0x1 /* randomized pointers */
142 .br
143 #define STR_ORDERED 0x2 /* ordered pointers */
144 .br
145 #define STR_ROTATED 0x4 /* rot-13'd text */
146 .br
147 unsigned long str_flags; /* bit field for flags */
148 .br
149 char str_delim; /* delimiting character */
150 .PP
151 All fields are written in network byte order.
152 .SH BUGS
153 Fewer now, one hopes. However, fortunes (text strings) beginning with a
154 blank line appear to be sorted between random letters. This includes
155 ASCII art that contains no letters, and first lines that are solely
156 non-alphanumeric, apparently. I've no idea why this should be.
157 .SH OTHER USES
158 What can you do with this besides printing sarcastic and obscene messages
159 to the screens of lusers at login or logout?
160 .PP
161 There
162 .B are
163 some other possibilities. Source code for a sample program,
164 .BR randstr ,
165 is included with this distribution: randstr splits the difference between
166 .BR unstr " and " fortune .
167 It reads a single, specified file, and randomly selects a single text
168 string.
169 .IP 1
170 Include
171 .I strfile.h
172 into a news reading/posting program, to generate random signatures.
173 .BR Tin (1)
174 does something similar, in a much more complex manner.
175 .IP 2
176 Include it in a game. While strfile doesn't support 'fields' or
177 \&'records', there's no reason that the text strings can't be consistent:
178 first line, a die roll; second line, a score; third and subsequent lines,
179 a text message.
180 .IP 3
181 Use it to store your address book. Hell, some of the guys I know
182 would be as well off using it to decide who to call on Friday nights (and
183 for some, it wouldn't matter whether there were phone numbers in it or not).
184 .IP 4
185 Use it in 'lottery' situations. If you're an ISP, write a script to
186 store login names and GECOS from
187 .I /etc/passwd
188 in strfile format, write another to send 'congratulations, you've won'
189 to the lucky login selected. The prize might be a month's free service,
190 or if you're AOL, a month free on a real service provider.
191 .SH SEE ALSO
192 .BR byteorder "(3), " fortune (6)
193 .SH HISTORY
194 The
195 .B strfile
196 utility first appeared in 4.4BSD. This version was heavily modified,
197 much of it in ways peculiar to Linux. Work has since been done to make
198 the code more generic, and has so far been tested to work with SunOS
199 4.x. More platforms are expected to be supported as work continues.