[src/trunk]: src/external/cddl/osnet/dist/lib/libctf/common Fix Dt. New sente...

[wiz <wiz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/7b1c9d0895fc
branches:  trunk
changeset: 340747:7b1c9d0895fc
user:      wiz <wiz%NetBSD.org@localhost>
date:      Mon Sep 28 22:00:26 2015 +0000

description:
Fix Dt. New sentence, new line. Fix xrefs.

Still leaves:
trailing Xref to mdb(1)
trailing Xref to libctf(3)

diffstat:

 external/cddl/osnet/dist/lib/libctf/common/ctf.5 |  430 +++++++++++++++-------
 1 files changed, 287 insertions(+), 143 deletions(-)

diffs (truncated from 915 to 300 lines):

diff -r 596c67f58ebe -r 7b1c9d0895fc external/cddl/osnet/dist/lib/libctf/common/ctf.5
--- a/external/cddl/osnet/dist/lib/libctf/common/ctf.5  Mon Sep 28 21:50:48 2015 +0000
+++ b/external/cddl/osnet/dist/lib/libctf/common/ctf.5  Mon Sep 28 22:00:26 2015 +0000
@@ -1,3 +1,4 @@
+.\" $NetBSD: ctf.5,v 1.2 2015/09/28 22:00:26 wiz Exp $
 .\"
 .\" This file and its contents are supplied under the terms of the
 .\" Common Development and Distribution License ("CDDL"), version 1.0.
@@ -11,7 +12,7 @@
 .\"
 .\" Copyright (c) 2014 Joyent, Inc.
 .\"
-.Dd Sep 26, 2014
+.Dd September 26, 2014
 .Dt CTF 5
 .Os
 .Sh NAME
@@ -39,7 +40,8 @@
 sizes of C types, including intrinsic types, enumerations, structures,
 typedefs, and unions, that are used by the corresponding
 .Sy ELF
-object. The
+object.
+The
 .Nm
 data may also include information about the types of global objects and
 the return type and arguments of functions in the symbol table.
@@ -53,19 +55,21 @@
 .Lp
 On illumos systems,
 .Nm
-data is consumed by multiple programs. It can be used by the modular
+data is consumed by multiple programs.
+It can be used by the modular
 debugger,
 .Xr mdb 1 ,
 as well as by
-.Xr dtrace 1M .
+.Xr dtrace 1 .
 Programmatic access to
 .Nm
 data can be obtained through
-.Xr libctf 3LIB .
+.Xr libctf 3 .
 .Lp
 The
 .Nm
-file format is broken down into seven different sections. The first
+file format is broken down into seven different sections.
+The first
 section is the
 .Sy preamble
 and
@@ -74,18 +78,22 @@
 .Nm
 file, links it has to other
 .Nm
-files, and the sizes of the other sections. The next section is the
+files, and the sizes of the other sections.
+The next section is the
 .Sy label
 section,
 which provides a way of identifying similar groups of
 .Nm
-data across multiple files. This is followed by the
+data across multiple files.
+This is followed by the
 .Sy object
 information section, which describes the type of global
-symbols. The subsequent section is the
+symbols.
+The subsequent section is the
 .Sy function
 information section, which describes the return
-types and arguments of functions. The next section is the
+types and arguments of functions.
+The next section is the
 .Sy type
 information section, which describes
 the format and layout of the C types themselves, and finally the last
@@ -106,28 +114,33 @@
 file may contain all of the type information that it requires, or it
 may optionally refer to another
 .Nm
-file which holds the remaining types. When a
+file which holds the remaining types.
+When a
 .Nm
 file refers to another file, it is called the
 .Sy child
 and the file it refers to is called the
 .Sy parent .
-A given file may only refer to one parent. This process is called
+A given file may only refer to one parent.
+This process is called
 .Em uniquification
 because it ensures each child only has type information that is
-unique to it. A common example of this is that most kernel modules in
+unique to it.
+A common example of this is that most kernel modules in
 illumos are uniquified against the kernel module
 .Sy genunix
 and the type information that comes from the
 .Sy IP
-module. This means that a module only has types that are unique to
+module.
+This means that a module only has types that are unique to
 itself and the most common types in the kernel are not duplicated.
 .Sh FILE FORMAT
 This documents version
 .Em two
 of the
 .Nm
-file format. All applications and tools currently produce and operate on
+file format.
+All applications and tools currently produce and operate on
 this version.
 .Lp
 The file format can be summarized with the following image, the
@@ -235,25 +248,31 @@
 .Sy preamble
 defines the version of the
 .Nm
-file which defines the format of the rest of the header. While the
+file which defines the format of the rest of the header.
+While the
 header may change in subsequent versions, the preamble will not change
 across versions, though the interpretation of its flags may change from
-version to version. The
+version to version.
+The
 .Em ctp_magic
 member defines the magic number for the
 .Nm
-file format. This must always be
+file format.
+This must always be
 .Li 0xcff1 .
 If another value is encountered, then the file should not be treated as
 a
 .Nm
-file. The
+file.
+The
 .Em ctp_version
 member defines the version of the
 .Nm
-file. The current version is
+file.
+The current version is
 .Li 2 .
-It is possible to encounter an unsupported version. In that case,
+It is possible to encounter an unsupported version.
+In that case,
 software should not try to parse the format, as it may have changed.
 Finally, the
 .Em ctp_flags
@@ -273,8 +292,10 @@
 .Sy zlib
 library and its
 .Sy deflate
-algorithm. If this flag is not present, then the body has not been
-compressed and no special action is needed to interpret it. All offsets
+algorithm.
+If this flag is not present, then the body has not been
+compressed and no special action is needed to interpret it.
+All offsets
 into the data as described by
 .Sy header ,
 always refer to the
@@ -289,7 +310,8 @@
 .Nm
 file is the child of another
 .Nm
-file and also indicates the size of the remaining sections. The
+file and also indicates the size of the remaining sections.
+The
 structure for the
 .Sy header ,
 logically contains a copy of the
@@ -315,37 +337,46 @@
 .Em cth_parlablel
 and
 .Em cth_parname ,
-are used to identify the parent. The value of both members are offsets
+are used to identify the parent.
+The value of both members are offsets
 into the
 .Sy string
-section which point to the start of a null-terminated string. For more
+section which point to the start of a null-terminated string.
+For more
 information on the encoding of strings, see the subsection on
 .Sx String Identifiers .
 If the value of either is zero, then there is no entry for that
-member. If the member
+member.
+If the member
 .Em cth_parlabel
 is set, then the
 .Em ctf_parname
 member must be set, otherwise it will not be possible to find the
-parent. If
+parent.
+If
 .Em ctf_parname
 is set, it is not necessary to define
 .Em cth_parlabel ,
-as the parent may not have a label. For more information on labels
+as the parent may not have a label.
+For more information on labels
 and their interpretation, see
 .Sx The Label Section .
 .Lp
 The remaining members (excepting
 .Em cth_strlen )
-describe the beginning of the corresponding sections. These offsets are
+describe the beginning of the corresponding sections.
+These offsets are
 relative to the end of the
 .Sy header .
 Therefore, something with an offset of 0 is at an offset of thirty-six
 bytes relative to the start of the
 .Nm
-file. The difference between members
-indicates the size of the section itself. Different offsets have
-different alignment requirements. The start of the
+file.
+The difference between members
+indicates the size of the section itself.
+Different offsets have
+different alignment requirements.
+The start of the
 .Em cth_objotoff
 and
 .Em cth_funcoff
@@ -353,12 +384,15 @@
 .Em cth_lbloff
 and
 .Em cth_typeoff
-must be four-byte aligned. The section
+must be four-byte aligned.
+The section
 .Em cth_stroff
-has no alignment requirements. To calculate the size of a given section,
+has no alignment requirements.
+To calculate the size of a given section,
 excepting the
 .Sy string
-section, one should subtract the offset of the section from the following one. For
+section, one should subtract the offset of the section from the following one.
+For
 example, the size of the
 .Sy types
 section can be calculated by subtracting
@@ -368,7 +402,8 @@
 .Lp
 Finally, the member
 .Em cth_strlen
-describes the length of the string section itself. From it, you can also
+describes the length of the string section itself.
+From it, you can also
 calculate the size of the entire
 .Nm
 file by adding together the size of the
@@ -380,9 +415,11 @@
 .Ss Type Identifiers
 Through the
 .Nm ctf
-data, types are referred to by identifiers. A given
+data, types are referred to by identifiers.
+A given
 .Nm
-file supports up to 32767 (0x7fff) types. The first valid type identifier is 0x1.
+file supports up to 32767 (0x7fff) types.
+The first valid type identifier is 0x1.
 When a given
 .Nm
 file is a child, indicated by a non-zero entry for the
@@ -403,16 +440,20 @@
 information may use larger or opaque identifiers.
 .Ss String Identifiers
 String identifiers are always encoded as four byte unsigned integers
-which are an offset into a string table. The
+which are an offset into a string table.
+The
 .Nm
 format supports two different string tables which have an identifier of
-zero or one. This identifier is stored in the high-order bit of the
-unsigned four byte offset. Therefore, the maximum supported offset into
+zero or one.
+This identifier is stored in the high-order bit of the
+unsigned four byte offset.
+Therefore, the maximum supported offset into
 one of these tables is 0x7ffffffff.
 .Lp
 Table identifier zero, always refers to the
 .Sy string
-section in the CTF file itself. String table identifier one refers to an
+section in the CTF file itself.