|author||Mark Johnston <markj@FreeBSD.org>||2017-10-22 19:17:25 +0000|
|committer||Mark Johnston <markj@FreeBSD.org>||2017-10-22 19:17:25 +0000|
Address some miscellaneous issues in the CTF man page.
- Fix a number of typos. - Replace some illumos-specific references. - Note that a type definition of kind CTF_K_FUNCTION may be followed by a null type identifier in order to provide 4-byte alignment for the next type definition. MFC after: 2 weeks
Notes: svn path=/head/; revision=324865
Diffstat (limited to 'cddl/contrib/opensolaris/lib/libctf/common')
1 files changed, 39 insertions, 30 deletions
diff --git a/cddl/contrib/opensolaris/lib/libctf/common/ctf.5 b/cddl/contrib/opensolaris/lib/libctf/common/ctf.5
index 0778e7f5952f..5a90b0ef3121 100644
@@ -52,17 +52,15 @@ file itself, it may also be referred to as a
.Sy container .
-On illumos systems,
-data is consumed by multiple programs.
-It can be used by the modular debugger,
-.Xr mdb 1 ,
-as well as by
+data is consumed by
.Xr dtrace 1 .
Programmatic access to
-data can be obtained through
-.Xr libctf 3LIB .
+data can be obtained through libctf.
@@ -73,7 +71,7 @@ and
.Sy header ,
which describes the version of the
-file, links it has to other
+file, the links it has to other
files, and the sizes of the other sections.
The next section is the
@@ -84,7 +82,7 @@ which provides a way of identifying similar groups of
data across multiple files.
This is followed by the
-information section, which describes the type of global
+information section, which describes the types of global
The subsequent section is the
@@ -137,7 +135,9 @@ This documents version
-All applications and tools currently produce and operate on this version.
+All applications and tools on
+currently produce and operate on this version.
The file format can be summarized with the following image, the
following sections will cover this in more detail.
@@ -300,13 +300,13 @@ In version two of the
file format, the
-denotes whether whether or not this
+denotes whether or not this
file is the child of another
file and also indicates the size of the remaining sections.
The structure for the
-.Sy header ,
logically contains a copy of the
and the two have a combined size of 36 bytes.
@@ -534,7 +534,7 @@ files that corresponds with the particular build.
This ensures that if files on the system were to become mixed up from multiple
releases, that they are not used together by tools, particularly when a child
needs to refer to a type in the parent.
-Because they are linked used the type identifiers, if the wrong parent is used
+Because they are linked using the type identifiers, if the wrong parent is used
then the wrong type will be encountered.
Each label is encoded in the file format using the following eight byte
@@ -561,7 +561,7 @@ file.
Labels only refer to types in the current file, if the
file is a child, then it will have the same label as its parent;
-however, its label will only refer to its types, not its parents.
+however, its label will only refer to its types, not its parent's.
It is also possible, though rather uncommon, for a
@@ -585,8 +585,8 @@ in the ELF object that contains the
Not every object is included in this section.
-Specifically, when walking the symbol table.
-An entry is skipped if it matches any of the following conditions:
+Specifically, when walking the symbol table, an entry is skipped if it matches
+any of the following conditions:
.Bl -bullet -offset indent -compact
@@ -657,7 +657,7 @@ walk_symbols(uint16_t *objtoff, Elf_Data *symdata, Elf_Data *strdata,
The function section of the
file encodes the types of both the function's arguments and the function's
.Sx The Object Section ,
the function section encodes information for all symbols of type
@@ -790,14 +790,14 @@ is encoded as described in the section
The string that it points to is the name of the type.
If the identifier points to an empty string (one that consists solely of a null
terminator) then the type does not have a name, this is common with anonymous
-structures and unions that only have a typedef to name them, as well as,
+structures and unions that only have a typedef to name them, as well as
pointers and qualifiers.
The next member, the
.Em ctt_info ,
is encoded as described in the section
.Sx Type Encoding .
-The types kind tells us how to interpret the remaining data in the
+The type's kind tells us how to interpret the remaining data in the
and any variable length data that may exist.
The rest of this section will be broken down into the interpretation of the
@@ -904,7 +904,7 @@ This encoding can be expressed through the following macros:
(((encoding) << 24) | ((offset) << 16) | (bits))
-Where as the encoding for integers was a series of flags, the encoding for
+Where as the encoding for integers is a series of flags, the encoding for
floats maps to a specific kind of float.
It is not a flag-based value.
The kinds of floats correspond to both their size, and the encoding.
@@ -978,14 +978,18 @@ section.
If the function's last argument is of type varargs, then it is also written out,
but the type identifier is zero.
This is included in the count of the function's arguments.
+An extra type identifier may follow the argument and return type identifiers
+in order to maintain four-byte alignment for the following type definition.
+Such a type identifier is not included in the argument count and has a value
.Ss Encoding of Structures and Unions
Structures and Unions, which are encoded with
respectively, are very similar constructs in C.
-The main difference between them is the fact that every member of a structure
-follows one another, where as in a union, all members share the same memory.
+The main difference between them is the fact that members of a structure
+follow one another, where as in a union, all members share the same memory.
They are also very similar in terms of their encoding in
The variable length argument for structures and unions represents the number of
@@ -1032,12 +1036,12 @@ They are encoded as per the section
.Sx Type Identifiers .
The last piece of information that is present is the offset which describes the
-offset in memory that the member begins at.
-For unions, this value will always be zero because the start of unions in memory
-is always zero.
+offset in memory at which the member begins.
+For unions, this value will always be zero because each member of a union has
+an offset of zero.
For structures, this is the offset in
-that the member begins at.
+at which the member begins.
Note that a compiler may lay out a type with padding.
This means that the difference in offset between two consecutive members may be
larger than the size of the member.
@@ -1069,12 +1073,16 @@ In C, an enumeration is always equivalent to the intrinsic type
thus the value of the member
is always the size of an integer which is determined based on the current model.
-For illumos systems, this will always be 4, as an integer is always defined to
+systems, this will always be 4, as an integer is always defined to
be 4 bytes large in both
.Sy LP64 ,
regardless of the architecture.
+For further details, see
+.Xr arch 7 .
The enumerators encoded in an enumeration have the following structure in the
@@ -1154,7 +1162,7 @@ This section encodes all of the strings that appear throughout the other
It is laid out as a series of characters followed by a null terminator.
Generally, all names are written out in ASCII, as most C compilers do not allow
-and characters to appear in identifiers outside of a subset of ASCII.
+any characters to appear in identifiers outside of a subset of ASCII.
However, any extended characters sets should be written out as a series of UTF-8
@@ -1166,7 +1174,7 @@ Offsets that refer to something in this section should refer to the first byte
which begins a string.
Beyond the first byte in the section being the null terminator, the order of
strings is unimportant.
-.Sh Data Encoding and ELF Considerations
+.Ss Data Encoding and ELF Considerations
data is generally included in ELF objects which specify information to
identify the architecture and endianness of the file.
@@ -1212,4 +1220,5 @@ alignment must be 4.
.Xr elf 3 ,
.Xr gelf 3 ,
.Xr a.out 5 ,
-.Xr elf 5
+.Xr elf 5 ,
+.Xr arch 7