1.\" $OpenBSD: dbm_dump.1,v 1.1 2016/07/30 10:56:13 schwarze 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 30 2016 $ 18.Dt DBM_DUMP 1 19.Os 20.Sh NAME 21.Nm dbm_dump 22.Nd dump a mandoc.db(5) file 23.Sh SYNOPSIS 24.Nm dbm_dump 25.Ar file 26.Sh DESCRIPTION 27The 28.Nm 29utility reads a 30.Xr mandoc_db 5 31database from the given 32.Ar file 33and dumps it to the standard output in a format that is suitable for 34.Xr diff 1 . 35.Pp 36Offsets are given in bytes, zero-based, and printed in hexadecimal numbers. 37Counts are printed in decimal numbers. 38.Pp 39Each non-empty table - the PAGES table, the MACROS table, and any 40MACRO table - is preceded and followed by a line beginning with 41three equal signs 42.Pq Sq === . 43Empty tables produce no output. 44.Pp 45In the PAGES table, an entry may produce four or five lines of output, 46depending on whether an 47.Fa arch 48value is present. 49Each 50.Fa name 51value is preceded by one or more attributes in square brackets, 52telling what kind of a name it is: 53.Pp 54.Bl -tag -width 1n -compact -offset indent 55.It Sy f 56a file name 57.It Sy h 58a header line name taken from a 59.Ic \&Dt 60or 61.Ic \&TH 62macro 63.It Sy 1 64the name from the first 65.Ic \&Nm 66macro in the NAME section 67.It Sy t 68a title name: a name from any 69.Ic \&Nm 70macro in the NAME section 71.It Sy s 72any name from a 73.Ic \&Nm 74macro in the SYNOPSIS section 75.El 76.Pp 77In each MACRO table, macro values are followed by the primary name 78of each page in which they occur. 79This does not uniquely identify the pages because several pages 80may share the same primary name. 81.Sh FILES 82The header files 83.Qq Pa mansearch.h , 84.Qq Pa dbm_map.h , 85and 86.Qq Pa dbm.h 87and the object files 88.Pa dbm_map.o 89and 90.Pa dbm.o 91from the 92.Xr mandoc 1 93build are required to compile and link 94.Nm . 95.Sh EXIT STATUS 96.Ex -std 97It fails when no argument or more than one argument is given or when 98.Fn dbm_open 99fails. 100The pointer jumps described below 101.Sx DIAGNOSTICS 102do not imply failure. 103.Sh EXAMPLES 104Several examples of 105.Nm 106output can be found in the directory 107.Pa /usr/src/regress/usr.bin/mandoc/db/out/ . 108Standard output is saved in files with the extension 109.Pa *.dout , 110standard error is collected in the file 111.Pa all.derr . 112.Sh DIAGNOSTICS 113The function 114.Fn dbm_open 115detects various kinds of issues with the file format 116and reports them on the standard error output. 117.Pp 118Otherwise, the 119.Nm 120utility checks that the input file contains no holes 121and that no pointers point backwards. 122For each violation, the following message is printed: 123.Pp 124.D1 Ar pointer Sy jumps from Ar expected Sy to Ar specified 125.Pp 126Here, 127.Ar pointer 128specifies what the dubious pointer is supposed to point to: 129.Pp 130.Bl -tag -width macros -compact 131.It Sy name0 132the primary name of the first page 133.It Sy name 134the primary name of another page 135.It Sy sect0 136the first section of the first page 137.It Sy sect 138the first section of another page 139.It Sy arch0 140the first architecture of the first architecture-specific page 141.It Sy arch 142the first architecture of another page 143.It Sy desc0 144the one-line description of the first page 145.It Sy desc 146the one-line description of another page 147.It Sy file0 148the first filename of the first page 149.It Sy file 150the first filename of another page 151.It Sy macros 152the number of macro tables 153.It Sy macro0 154the number of entries in the first macro table 155.It Sy macro 156the number of entries in another macro table 157.It Sy value0 158the first value of a macro 159.It Sy value 160another value of a macro 161.It Sy pages0 162the list of pointers to pages mentioning the first macro value 163.It Sy pages 164the list of pointers to pages mentioning another macro value 165.It Sy end 166the final magic 167.El 168.Pp 169The hexadecimal 32-bit integers 170.Ar expected 171and 172.Ar specified 173give the byte offset of a specific data element in the file; 174respectively, the one 175.Ar expected 176from the end of the preceding data in the file and the one actually 177.Ar found 178when reading the location where the pointer ought to be. 179If 180.Ar found 181is greater than 182.Ar expected , 183there is a hole, and the file could theoretically still be usable, 184even though it is not likely to be correct. 185If 186.Ar found 187is less than 188.Ar expected , 189the file is corrupt because it contains a backward pointer. 190.Sh AUTHORS 191.An Ingo Schwarze Aq Mt schwarze@openbsd.org 192