1.\"	$OpenBSD: mlinks.1,v 1.4 2017/07/07 23:55:21 bluhm Exp $
2.\"
3.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: July 7 2017 $
18.Dt MLINKS 1
19.Os
20.Sh NAME
21.Nm mlinks
22.Nd extract desired mlinks from a mandoc.db(5) file
23.Sh SYNOPSIS
24.Nm mlinks
25.Ar file
26.Sh DESCRIPTION
27The
28.Nm
29utility reads a
30.Xr mandoc_db 5
31database from the given
32.Ar file .
33For each manual page name that does not agree with the filename,
34it writes one line to the standard output, containing:
35.Pp
36.Bl -dash -compact
37.It
38the filename
39.It
40a comma
41.It
42the other name
43.It
44a period
45.It
46the section number
47.El
48.Pp
49This format is useful for portable software intended to run on
50operating systems that require multiple file system entries
51for pages having multiple names.
52.Pp
53For example, it is used to generate MLINKS for portable LibreSSL.
54.Sh FILES
55The header files
56.Qq Pa dbm_map.h
57and
58.Qq Pa dbm.h
59and the object files
60.Pa dbm_map.o
61and
62.Pa dbm.o
63from the
64.Xr mandoc 1
65build are required to compile and link
66.Nm .
67.Sh EXIT STATUS
68.Ex -std
69It fails when no argument or more than one argument is given, when
70.Fn dbm_open
71fails, or when database corruption is detected.
72.Sh EXAMPLES
73Typical usage looks like this:
74.Bd -literal -offset indent
75cd /usr/src/usr.bin/mandoc/
76make obj
77make
78cd /usr/src/regress/usr.bin/mandoc/db/mlinks/
79make obj
80make
81makewhatis -a /usr/src/lib/libssl/man
82\&./obj/mlinks /usr/src/lib/libssl/man/mandoc.db > ssl.mlinks
83.Ed
84.Sh AUTHORS
85.An Ingo Schwarze Aq Mt schwarze@openbsd.org
86.Sh CAVEATS
87The
88.Nm
89utility only partially validates the database format.
90For complete validation, use the
91.Xr dbm_dump 1
92utility found in
93.Pa /usr/src/regress/usr.bin/mandoc/db/dbm_dump/ .
94