Added link.5 man page and updated a.out.5 manpage to reflect the new

code.

Obtained from: NetBSD

3 files changed, 656 insertions, 29 deletions

diff --git a/share/man/man5/Makefile b/share/man/man5/Makefile
index 55a3bd7f0fbd..0a37bb6889f4 100644
--- a/share/man/man5/Makefile
+++ b/share/man/man5/Makefile
@@ -2,9 +2,9 @@
 
 #MISSING: dump.5 plot.5
 MAN5=	a.out.5 acct.5 core.5 dir.5 disktab.5 fs.5 fbtab.5 fstab.5 \
-	group.5 hosts.5 networks.5 passwd.5 phones.5 printcap.5 procfs.5 \
-	protocols.5 remote.5 resolver.5 services.5 shells.5 stab.5 types.5 \
-	utmp.5
+	group.5 hosts.5 link.5 networks.5 passwd.5 phones.5 printcap.5 \
+	procfs.5 protocols.5 remote.5 resolver.5 services.5 shells.5 \
+	stab.5 types.5 utmp.5
 MLINKS=	fs.5 inode.5 utmp.5 wtmp.5
 
 clean depend lint tags:
diff --git a/share/man/man5/a.out.5 b/share/man/man5/a.out.5
index 9ad2876572db..f1869995895a 100644
--- a/share/man/man5/a.out.5
+++ b/share/man/man5/a.out.5
@@ -33,6 +33,7 @@
 .\" SUCH DAMAGE.
 .\"
 .\"	@(#)a.out.5	8.1 (Berkeley) 6/5/93
+.\"	$Id$
 .\"
 .Dd June 5, 1993
 .Dt A.OUT 5
@@ -86,8 +87,7 @@ Every binary file begins with an
 structure:
 .Bd -literal -offset indent
 struct exec {
-	unsigned short	a_mid;
-	unsigned short	a_magic;
+	unsigned long	a_midmag;
 	unsigned long	a_text;
 	unsigned long	a_data;
 	unsigned long	a_bss;
@@ -100,25 +100,43 @@ struct exec {
 .Pp
 The fields have the following functions:
 .Bl -tag -width a_trsize
-.It Fa a_mid
-Contains a bit pattern that
-identifies binaries that were built for
-certain sub-classes of an architecture
-.Pq Sq machine IDs
-or variants of the operating system on a given architecture.
-The kernel may not support all machine IDs
-on a given architecture.
-The
-.Fa a_mid
-field is not present on some architectures;
-in this case, the
-.Fa a_magic
-field has type
-.Em unsigned long .
-.It Fa a_magic
-Contains a bit pattern
-.Pq Sq magic number
-that uniquely identifies binary files
+.It Fa a_midmag
+This field is stored in host byte-order.
+It has a number of sub-components accessed by the macros
+.Dv N_GETFLAG() ,
+.Dv N_GETMID() , and
+.Dv N_GETMAGIC() ,
+and set by the macro
+.Dv N_SETMAGIC().
+.Pp
+The macro
+.Dv N_GETFLAG()
+returns a few flags:
+.Bl -tag -width EX_DYNAMIC
+.It Dv EX_DYNAMIC
+indicates that the executable requires the services of the run-time link editor.
+.It Dv EX_PIC
+indicates that the object contains position independent code. This flag is
+set by
+.Xr as 1
+when given the
+.Sq -k
+flag and is preserved by
+.Xr ld 1
+if necessary.
+.El
+.Pp
+If both EX_DYNAMIC and EX_PIC are set, the object file is a position indendent
+executable image (eg. a shared library), which is to be loaded into the
+process address space by the run-time link editor.
+.Pp
+The macro
+.Dv N_GETMID()
+returns the machine-id.
+This indicates which machine(s) the binary is intended to run on.
+.Pp
+.Dv N_GETMAGIC()
+specifies the magic number, which uniquely identifies binary files
 and distinguishes different loading conventions.
 The field must contain one of the following values:
 .Bl -tag -width ZMAGIC
@@ -194,7 +212,10 @@ struct relocation_info {
 			r_pcrel : 1,
 			r_length : 2,
 			r_extern : 1,
-			: 4;
+			r_baserel : 1,
+			r_jmptable : 1,
+			r_relative : 1,
+			r_copy : 1;
 };
 .Ed
 .Pp
@@ -237,7 +258,9 @@ bit is clear, the relocation is
 .Sq local ;
 the link editor updates the pointer to reflect
 changes in the load addresses of the various segments,
-rather than changes in the value of a symbol.
+rather than changes in the value of a symbol (except when
+.Fa r_baserel
+is also set (see below).
 In this case, the content of the
 .Fa r_symbolnum
 field is an
@@ -245,6 +268,26 @@ field is an
 value (see below);
 this type field tells the link editor
 what segment the relocated pointer points into.
+.It Fa r_baserel
+If set, the symbol, as identified by the
+.Fa r_symbolnum
+field, is to be relocated to an offset into the Global Offset Table.
+At run-time, the entry in the Global Offset Table at this offset is set to
+be the address of the symbol.
+.It Fa r_jmptable
+If set, the symbol, as identified by the
+.Fa r_symbolnum
+field, is to be relocated to an offset into the Procedure Linkage Table.
+.It Fa r_relative
+If set, this relocation is relative to the (run-time) load address of the
+image this object file is going to be a part of. This type of relocation
+only occurs in shared objects.
+.It Fa r_copy
+If set, this relocation record identifies a symbol whose contents should
+be copied to the location given in
+.Fa r_address.
+The copying is done by the run-time link-editor from a suitable data
+item in a shared object.
 .El
 .Pp
 Symbols map names to addresses (or more generally, strings to values).
@@ -346,7 +389,28 @@ such as
 the values are described in
 .Xr stab 5 .
 .It Fa n_other
-This field is currently unused.
+This field provides information on the nature of the symbol independent of
+the symbol's location in terms of segments as determined by the
+.Fa n_type
+field. Currently, the lower 4 bits of the
+.Fa n_other
+field hold one of two values:
+.Dv AUX_FUNC
+and
+.Dv AUX_OBJECT
+.Po
+see
+.Aq Pa link.h
+for their definitions
+.Pc .
+.Dv AUX_FUNC
+associates the symbol with a callable function, while
+.Dv AUX_OBJECT
+associates the symbol with data, irrespective of their locations in
+either the text or the data segment.
+This field is intended to be used by
+.Xr ld 1
+for the construction of dynamic executables.
 .It Fa n_desc
 Reserved for use by debuggers; passed untouched by the link editor.
 Different debuggers use this field for different purposes.
@@ -364,12 +428,16 @@ The length represents the size of the entire table in bytes,
 so its minimum value (or the offset of the first string)
 is always 4 on 32-bit machines.
 .Sh SEE ALSO
+.Xr as 1 ,
+.Xr gdb 1 ,
 .Xr ld 1 ,
+.Xr brk 2 ,
 .Xr execve 2 ,
 .Xr nlist 3 ,
 .Xr core 5 ,
 .Xr dbx 5 ,
-.Xr stab 5
+.Xr stab 5 ,
+.Xr link 5
 .Sh HISTORY
 The
 .Pa a.out.h
@@ -377,7 +445,7 @@ include file appeared in
 .At v7 .
 .Sh BUGS
 Since not all of the supported architectures use the
-.Fa a_mid
+.Fa a_midmag
 field,
 it can be difficult to determine what
 architecture a binary will execute on
diff --git a/share/man/man5/link.5 b/share/man/man5/link.5
new file mode 100644
index 000000000000..b67cf9e05098
--- /dev/null
+++ b/share/man/man5/link.5
@@ -0,0 +1,559 @@
+.\" Copyright (c) 1993 Paul Kranenburg
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"      This product includes software developed by Paul Kranenburg.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\"	$Id$
+.\"
+.Dd October 23, 1993
+.Dt LINK 5
+.Os
+.Sh NAME
+.Nm link
+.Nd dynamic loader and link editor interface
+.Sh SYNOPSIS
+.Fd #include <link.h>
+.Sh DESCRIPTION
+The include file
+.Aq Pa link.h
+declares several structures that are present in dynamically linked
+programs and libraries.
+The structures define the interface between several components of the
+link-editor and loader mechanism. The layout of a number of these
+structures within the binaries resembles the a.out format in many places
+as it serves such similar functions as symbol definitions (including the
+accompanying string table) and relocation records needed to resolve
+references to external entities. It also records a number of data structures
+unique to the dynamic loading and linking process. These include references
+to other objects that are required to complete the link-editing process and
+indirection tables to facilitate
+.Em Position Independent Code
+(PIC for short) to improve sharing of code pages among different processes.
+The collection of data structures described here will be refered to as the
+.Em Run-time Relocation Section (RRS)
+and is embedded in the standard text and data segments of the dynamically
+linked program or shared object image as the existing
+.Xr a.out
+format offers no room for it elsewhere.
+.Pp
+Several utilities cooperate to ensure that the task of getting a program
+ready to run can complete successfully in a way that optimizes the use
+of system resources. The compiler emits PIC code from which shared libraries
+can be build by
+.Xr ld 1.
+The compiler also includes size information of any initialized data items
+through the .size assembler directive. PIC code differs from conventional code
+in that it accesses data variables through an indirection table, the
+Global Offset Table, by convention accessable by the reserved name
+.Em _GLOBAL_OFFSET_TABLE_.
+The exact mechanism used for this is machine dependent, usually a machine
+register is reserved for the purpose. The rational behind this construct
+is to generate code that is independent of the actual load address. Only
+the values contained in the Global Offset Table may need updating at run-time
+depending on the load addresses of the various shared objects in the address
+space.
+.Pp
+Likewise, procedure calls to globally defined functions are redirected through
+the Procedure Linkage Table (PLT) residing in the data segment of the core
+image. Again, this is done to avoid run-time modifications to the text segment.
+.Pp
+The linker-editor allocates the Global Offset Table and Procedure Linkage Table
+when combining PIC object files into an image suitable for mapping into the
+process address space. It also collects all symbols that may be needed by the
+run-time link-editor and stores these along with the image's text and data bits.
+Another reserved symbol,
+.Em _DYNAMIC
+is used to indicate the presence of the run-time linker structures. Whenever
+_DYNAMIC is relocated to 0, there is no need to invoke the run-time
+link-editor. If this symbol is non-zero, it points at a data structure from
+which the location of the necessary relocation- and symbol information can
+be derived. This is most notably used by the start-up module,
+.Em crt0.
+The _DYNAMIC structure is conventionally located at the start of the data
+segment of the image to which it pertains.
+.Pp
+.Sh DATA STRUCTURES
+The data structures supporting dynamic linking and run-time relocation
+reside both in the text and data segments of the image they apply to.
+The text segments contain read-only data such as symbols descriptions and
+names, while the data segments contain the tables that need to be modified by
+during the relocation process.
+.Pp
+The _DYNAMIC symbol references a
+.Fa _dynamic
+structure:
+.Bd -literal -offset indent
+struct	_dynamic {
+	int	d_version;
+	struct 	so_debug *d_debug;
+	union {
+		struct section_dispatch_table *d_sdt;
+	} d_un;
+	struct  ld_entry *d_entry;
+};
+.Ed
+.Bl -tag -width d_version
+.It Fa d_version
+This field provides for different versions of the dynamic linking
+implementation. The current version numbers understood by ld and ld.so are
+.Em LD_VERSION_SUN (3),
+which is used by the SunOS 4.x releases, and
+.Em LD_VERSION_BSD (8),
+which is currently in use by FreeBSD since release 1.1.
+.It Fa d_un
+Refers to a
+.Em d_version
+dependent data structure.
+.It Fa so_debug
+this field provides debuggers with a hook to access symbol tables of shared
+objects loaded as a result of the actions of the run-time link-editor.
+.El
+.Pp
+The
+.Fa section_dispatch_table
+structure is the main
+.Dq dispatcher
+table, containing offsets into the image's segments where various symbol
+and relocation information is located.
+.Bd -literal -offset indent
+struct section_dispatch_table {
+	struct	so_map *sdt_loaded;
+	long	sdt_sods;
+	long	sdt_filler1;
+	long	sdt_got;
+	long	sdt_plt;
+	long	sdt_rel;
+	long	sdt_hash;
+	long	sdt_nzlist;
+	long	sdt_filler2;
+	long	sdt_buckets;
+	long	sdt_strings;
+	long	sdt_str_sz;
+	long	sdt_text_sz;
+	long	sdt_plt_sz;
+};
+.Ed
+.Pp
+.Bl -tag -width sdt_filler1
+.It Fa sdt_loaded
+A pointer to the first link map loaded (see below). This field is set by
+.Xr ld.so.
+.It Fa sdt_sods
+The start of a (linked) list of shared object descriptors needed by
+.Em this
+object.
+.It Fa sdt_filler1
+Depricated (used by SunOS to specify library search rules).
+.It Fa sdt_got
+The location of the Global Offset Table within this image.
+.It Fa sdt_plt
+The location of the Procedure Linkage Table within this image.
+.It Fa sdt_rel
+The location of an array of
+.Fa relocation_info
+structures
+.Po
+see
+.Xr a.out 5
+.Pc
+specifying run-time relocations.
+.It Fa sdt_hash
+The location of the hash table for fast symbol lookup in this object's
+symbol table.
+.It Fa sdt_nzlist
+The location of the symbol table.
+.It Fa sdt_filler2
+Currently unused.
+.It Fa sdt_buckets
+The number of buckets in
+.Fa sdt_hash
+.It Fa sdt_strings
+The location of the symbol string table that goes with
+.Fa sdt_nzlist.
+.It Fa sdt_str_sz
+The size of the string table.
+.It Fa sdt_text_sz
+The size of the object's text segment.
+.It Fa sdt_plt_sz
+The size of the Procedure Linkage Table.
+.El
+.Pp
+A
+.Fa sod
+structure descibes a shared object that is needed
+to complete the link edit process of the object containing it.
+A list of such objects
+.Po
+chained through
+.Fa sod_next
+.Pc
+is pointed at
+by the
+.Fa sdt_sods
+in the section_dispatch_table structure.
+.Bd -literal -offset indent
+struct sod {
+	long	sod_name;
+	u_int	sod_library : 1,
+		sod_unused : 31;
+	short	sod_major;
+	short	sod_minor;
+	long	sod_next;
+};
+.Ed
+.Pp
+.Bl -tag -width sod_library
+.It Fa sod_name
+The offset in the text segment of a string describing this link object.
+.It Fa sod_library
+If set,
+.Fa sod_name
+specifies a library that is to be searched for by ld.so. The path name
+is obtained by searching a set of directories
+.Po
+see also
+.Xr ldconfig 8
+.Pc
+for a shared object matching
+.Em lib\&<sod_name>\&.so.n.m.
+If not set,
+.Fa sod_name
+should point at a full path name for the desired shared object.
+.It Fa sod_major
+Specifies the major version number of the shared object to load.
+.It Fa sod_minor
+Specifies the prefered minor version number of the shared object to load.
+.El
+.Pp
+The run-time link-editor maintains a list of structures called
+.Em link maps
+to keep track of all shared objects loaded into a process' address space.
+These structures are only used at run-time and do not occur within
+the text or data segment of an executable or shared library.
+.Bd -literal -offset indent
+struct so_map {
+	caddr_t	som_addr;
+	char 	*som_path;
+	struct	so_map *som_next;
+	struct	sod *som_sod;
+	caddr_t som_sodbase;
+	u_int	som_write : 1;
+	struct	_dynamic *som_dynamic;
+	caddr_t	som_spd;
+};
+.Ed
+.Bl -tag -width som_dynamic
+.It Fa som_addr
+The address at which the shared object associated with this link map has
+been loaded.
+.It Fa som_path
+The full path name of the loaded object.
+.It Fa som_next
+Pointer to the next link map.
+.It Fa som_sod
+The
+.Fa sod
+structure that was responsible for loading this shared object.
+.It Fa som_sodbase
+Tossed in later versions the run-time linker.
+.It Fa som_write
+Set if (some portion of) this object's text segment is currently writable.
+.It Fa som_dynamic
+Pointer to this object's
+.Fa _dynamic
+structure.
+.It Fa som_spd
+Hook for attaching private data maintained by the run-time link-editor.
+.El
+.Pp
+Symbol description with size. This is simply an
+.Fa nlist
+structure with one field
+.Pq Fa nz_size
+added. Used to convey size information on items in the data segment
+of shared objects. An array of these lives in the shared object's
+text segment and is addressed by the
+.Fa sdt_nzlist
+field of
+.Fa section_dispatch_table.
+.Bd -literal -offset indent
+struct nzlist {
+	struct nlist	nlist;
+	u_long		nz_size;
+#define nz_un		nlist.n_un
+#define nz_strx		nlist.n_un.n_strx
+#define nz_name		nlist.n_un.n_name
+#define nz_type		nlist.n_type
+#define nz_value	nlist.n_value
+#define nz_desc		nlist.n_desc
+#define nz_other	nlist.n_other
+};
+.Ed
+.Bl -tag -width nz_size
+.It Fa nlist
+.Po
+see
+.Xr nlist 5
+.Pc .
+.It Fa nz_size
+The size of the data represented by this symbol.
+.El
+.Pp
+A hash table is included within the text segment of shared object to
+to facilitate quick lookup of symbols during run-time link-editing.
+The
+.Fa sdt_hash
+field of the
+.Fa section_dispatch_table
+structure points at an array of
+.Fa rrs_hash
+structures:
+.Bd -literal -offset indent
+struct rrs_hash {
+	int	rh_symbolnum;		/* symbol number */
+	int	rh_next;		/* next hash entry */
+};
+.Ed
+.Pp
+.Bl -tag -width rh_symbolnum
+.It Fa rh_symbolnum
+The index of the symbol in the shared object's symbol table (as given by the
+.Fa ld_symbols
+field).
+.It Fa rh_next
+In case of collisions, this field is the offset of the next entry in this
+hash table bucket. It is zero for the last bucket element.
+.El
+The
+.Fa rt_symbol
+structure is used to keep track of run-time allocated commons
+and data items copied from shared objects. These items are kept on linked list
+and is exported through the
+.Fa dd_cc
+field in the
+.Fa so_debug
+structure (see below) for use by debuggers.
+.Bd -literal -offset indent
+struct rt_symbol {
+	struct nzlist		*rt_sp;
+	struct rt_symbol	*rt_next;
+	struct rt_symbol	*rt_link;
+	caddr_t			rt_srcaddr;
+	struct so_map		*rt_smp;
+};
+.Ed
+.Pp
+.Bl -tag -width rt_scraddr
+.It Fa rt_sp
+The symbol description.
+.It Fa rt_next
+Virtual address of next rt_symbol.
+.It Fa rt_link
+Next in hash bucket. Used by internally by ld.so.
+.It Fa rt_srcaddr
+Location of the source of initialized data within a shared object.
+.It Fa rt_smp
+The shared object which is the original source of the data that this
+run-time symbol describes.
+.El
+.Pp
+The
+.Fa so_debug
+structure is used by debuggers to gain knowledge of any shared objects
+that have been loaded in the process's address space as a result of run-time
+link-editing. Since the run-time link-editor runs as a part of process
+initialization, a debugger that wishes to access symbols from shared objects
+can only do so after the link-editor has been called from crt0.
+A dynamically linked binary contains a
+.Fa so_debug
+structure which can be located by means of the
+.Fa d_debug
+field in
+.Fa _dynamic.
+.Bd -literal -offset indent
+struct 	so_debug {
+	int	dd_version;
+	int	dd_in_debugger;
+	int	dd_sym_loaded;
+	char    *dd_bpt_addr;
+	int	dd_bpt_shadow;
+	struct rt_symbol *dd_cc;
+};
+.Ed
+.Pp
+.Bl -tag -width dd_in_debugger
+.It Fa dd_version
+Version number of this interface.
+.It Fa dd_in_debugger
+Set by the debugger to indicate to the run-time linker that the program is
+run under control of a debugger.
+.It Fa dd_sym_loaded
+Set by the run-time linker whenever it adds symbols by loading shared objects.
+.It Fa dd_bpt_addr
+The address were a breakpoint will be set by the the run-time linker to
+divert control to the debugger. This address is determined by the start-up
+module,
+.Em crt0.o,
+to be some convenient place before the call to _main.<.It Fa dd_bpt_shadow
+Contains the original instruction that was at
+.Fa dd_bpt_addr.
+The debugger is expected to put this instruction back before continuing the
+program.
+.It Fa dd_cc
+A pointer to the linked list of run-time allocated symbols that the debugger
+may be interested in.
+.El
+.Pp
+The
+.Em ld_entry
+structure defines a set of service routines within ld.so. See
+.Xr libdl.a
+for more information.
+.Bd -literal -offset indent
+struct ld_entry {
+	void	*(*dlopen)(char *, int);
+	int	(*dlclose)(void *);
+	void	*(*dlsym)(void *, char *);
+	int	(*dlctl)(void *, int, void *);
+};
+.Ed
+
+The
+.Fa crt_ldso
+structure defines the interface between the start-up code in crt0 and ld.so.
+.Bd -literal -offset indent
+struct crt_ldso {
+	int		crt_ba;
+	int		crt_dzfd;
+	int		crt_ldfd;
+	struct _dynamic	*crt_dp;
+	char		**crt_ep;
+	caddr_t		crt_bp;
+	char		*crt_prog;
+	char		*crt_ldso;
+};
+#define CRT_VERSION_SUN		1
+#define CRT_VERSION_BSD2	2
+#define CRT_VERSION_BSD3	3
+.Ed
+.Bl -tag -width crt_dzfd
+.It Fa crt_ba
+The virtual address at which ld.so was loaded by crt0.
+.It Fa crt_dzfd
+On SunOS systems, this field contains an open file descriptor to
+.Dq /dev/zero
+used to get demand paged zeroed pages. On FreeBSD systems it contains -1.
+.It Fa crt_ldfd
+Contains an open file descriptor that was used by crt0 to load ld.so.
+.It Fa crt_dp
+A pointer to main's
+.Fa _dynamic
+structure.
+.It Fa crt_ep
+A pointer to the environment strings.
+.It Fa crt_bp
+The address at which a breakpoint will be placed by the run-time linker
+if the main program is run by a debugger.
+See
+.Fa so_debug
+.It Fa crt_prog
+The name of the main program as determined by crt0 (CRT_VERSION_BSD3 only).
+.It Fa crt_ldso
+The path of the run-time linker as mapped by crt0 (CRT_VERSION_BSD4 only).
+.El
+.Pp
+The
+.Fa hints_header
+and
+.Fa hints_bucket
+structures define the layout of the library hints, normally found in
+.Dq /var/run/ld.so.hints,
+which is used by ld.so to quickly locate the shared object images in the
+filesystem.
+The organization of the hints file is not unlike that of an
+.Dq a.out
+object file, in that it contains a header determining the offset and size
+of a table of fixed sized hash buckets and a common string pool.
+.Bd -literal -offset indent
+struct hints_header {
+	long		hh_magic;
+#define HH_MAGIC	011421044151
+	long		hh_version;
+#define LD_HINTS_VERSION_1	1
+	long		hh_hashtab;
+	long		hh_nbucket;
+	long		hh_strtab;
+	long		hh_strtab_sz;
+	long		hh_ehints;
+};
+.Ed
+.Bl -tag -width hh_strtab_sz
+.It Fa hh_magic
+Hints file magic number.
+.It Fa hh_version
+Interface version number.
+.It Fa hh_hashtab
+Offset of hash table.
+.It Fa hh_strtab
+Offset of string table.
+.It Fa hh_strtab_sz
+Size of strings.
+.It Fa hh_ehints
+Maximum usable offset in hints file.
+.El
+.Pp
+.Bd -literal -offset indent
+/*
+ * Hash table element in hints file.
+ */
+struct hints_bucket {
+	int		hi_namex;
+	int		hi_pathx;
+	int		hi_dewey[MAXDEWEY];
+	int		hi_ndewey;
+#define hi_major hi_dewey[0]
+#define hi_minor hi_dewey[1]
+	int		hi_next;
+};
+.Ed
+.Bl -tag -width hi_ndewey
+.It Fa hi_namex
+Index of the string identifying the library.
+.It Fa hi_pathx
+Index of the string representing the full path name of the library.
+.It Fa hi_dewey
+The version numbers of the shared library.
+.It Fa hi_ndewey
+The number of valid entries in
+.Fa hi_dewey.
+.It Fa hi_next
+Next bucket in case of hashing collisions.
+.El
+
+.Sh CAVEATS
+Only the (GNU) C compiler currently supports the creation of shared libraries.
+Other programming languages can not be used.
+