1.\" Copyright (c) 1989, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\"
5.\" This code is derived from software contributed to Berkeley by
6.\" Ken Arnold.
7.\"
8.\" %sccs.include.redist.man%
9.\"
10.\"     @(#)strfile.8	8.1 (Berkeley) 06/09/93
11.\"
12.Dd
13.Dt STRFILE 8
14.Os BSD 4
15.Sh NAME
16.Nm strfile ,
17.Nm unstr
18.Nd "create a random access file for storing strings"
19.Sh SYNOPSIS
20.Nm strfile
21.Op Fl iorsx
22.Op Fl c Ar char
23.Ar source_file
24.Op Ar output_file
25.Nm unstr
26.Ar source_file
27.Sh DESCRIPTION
28.Nm Strfile
29reads a file containing groups of lines separated by a line containing
30a single percent
31.Ql \&%
32sign and creates a data file which contains
33a header structure and a table of file offsets for each group of lines.
34This allows random access of the strings.
35.Pp
36The output file, if not specified on the command line, is named
37.Ar source_file Ns Sy .out .
38.Pp
39The options are as follows:
40.Bl -tag -width "-c char"
41.It Fl c Ar char
42Change the delimiting character from the percent sign to
43.Ar char .
44.It Fl i
45Ignore case when ordering the strings.
46.It Fl o
47Order the strings in alphabetical order.
48The offset table will be sorted in the alphabetical order of the
49groups of lines referenced.
50Any initial non-alphanumeric characters are ignored.
51This option causes the
52.Dv STR_ORDERED
53bit in the header
54.Ar str_flags
55field to be set.
56.It Fl r
57Randomize access to the strings.
58Entries in the offset table will be randomly ordered.
59This option causes the
60.Dv STR_RANDOM
61bit in the header
62.Ar str_flags
63field to be set.
64.It Fl s
65Run silently; don't give a summary message when finished.
66.It Fl x
67Note that each alphabetic character in the groups of lines is rotated
6813 positions in a simple caesar cypher.
69This option causes the
70.Dv STR_ROTATED
71bit in the header
72.Ar str_flags
73field to be set.
74.El
75.Pp
76The format of the header is:
77.Bd -literal
78#define	VERSION	1
79unsigned long	str_version;	/* version number */
80unsigned long	str_numstr;	/* # of strings in the file */
81unsigned long	str_longlen;	/* length of longest string */
82unsigned long	str_shortlen;	/* length of shortest string */
83#define	STR_RANDOM	0x1	/* randomized pointers */
84#define	STR_ORDERED	0x2	/* ordered pointers */
85#define	STR_ROTATED	0x4	/* rot-13'd text */
86unsigned long	str_flags;	/* bit field for flags */
87char str_delim;			/* delimiting character */
88.Ed
89.Pp
90All fields are written in network byte order.
91.Pp
92The purpose of
93.Nm unstr
94is to undo the work of
95.Nm strfile .
96It prints out the strings contained in the file
97.Ar source_file
98in the order that they are listed in
99the header file
100.Ar source_file Ns Pa .dat
101to standard output.
102It is possible to create sorted versions of input files by using
103.Fl o
104when
105.Nm strfile
106is run and then using
107.Nm unstr
108to dump them out in the table order.
109.Sh SEE ALSO
110.Xr byteorder 3 ,
111.Xr fortune 6
112.Sh FILES
113.Bl -tag -width strfile.out -compact
114.It Pa strfile.out
115default output file.
116.El
117.Sh HISTORY
118The
119.Nm strfile
120utility first appeared in 4.4BSD.
121