[DTrace-devel] [PATCH 12/20] doc: Fix anchor links for reference/
eugene.loh at oracle.com
eugene.loh at oracle.com
Fri Sep 26 19:05:49 UTC 2025
From: Eugene Loh <eugene.loh at oracle.com>
Signed-off-by: Eugene Loh <eugene.loh at oracle.com>
---
doc/userguide/index.md | 74 +++++++++----------
doc/userguide/reference/aggregation.md | 6 +-
.../dtrace-ref-DTraceSupportforStrings.md | 10 +--
.../dtrace-ref-PointersandScalarArrays.md | 12 +--
.../reference/dtrace-ref-StructsandUnions.md | 10 +--
...dtrace-ref-TypesOperatorsandExpressions.md | 34 ++++-----
.../reference/dtrace-ref-Variables.md | 2 +-
7 files changed, 74 insertions(+), 74 deletions(-)
diff --git a/doc/userguide/index.md b/doc/userguide/index.md
index 72a9bf16e..f3d96a4d6 100644
--- a/doc/userguide/index.md
+++ b/doc/userguide/index.md
@@ -26,48 +26,48 @@
- [D Program Syntax Reference](reference/d_program_syntax_reference.md)
- [Program Structure](reference/d_program_syntax_reference_program_structure.md)
- [Types, Operators, and Expressions](reference/dtrace-ref-TypesOperatorsandExpressions.md)
- - [Identifier Names and Keywords](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_ident_dlang)
- - [Data Types and Sizes](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_dtypes_dlang)
- - [Constants](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_consts_dlang)
- - [Arithmetic Operators](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_arithops_dlang)
- - [Relational Operators](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_relatops_dlang)
- - [Logical Operators](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_logicops_dlang)
- - [Bitwise Operators](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_bitwiseops_dlang)
- - [Assignment Operators](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_assignops_dlang)
- - [Increment and Decrement Operators](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_incdecops_dlang)
- - [Conditional Expressions](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_condexp_dlang)
- - [Type Conversions](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_typeconv_dlang)
- - [Operator Precedence](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_preced_dlang)
- - [Type and Constant Definitions](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_typcondef_dlang)
- - [typedefs](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_typedefs_dlang)
- - [Enumerations](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_enums_dlang)
- - [Inlines](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_inlines_dlang)
- - [Type Namespaces](reference/dtrace-ref-TypesOperatorsandExpressions.md#dt_typens_dlang)
+ - [Identifier Names and Keywords](reference/dtrace-ref-TypesOperatorsandExpressions.md#identifier-names-and-keywords)
+ - [Data Types and Sizes](reference/dtrace-ref-TypesOperatorsandExpressions.md#data-types-and-sizes)
+ - [Constants](reference/dtrace-ref-TypesOperatorsandExpressions.md#constants)
+ - [Arithmetic Operators](reference/dtrace-ref-TypesOperatorsandExpressions.md#arithmetic-operators)
+ - [Relational Operators](reference/dtrace-ref-TypesOperatorsandExpressions.md#relational-operators)
+ - [Logical Operators](reference/dtrace-ref-TypesOperatorsandExpressions.md#logical-operators)
+ - [Bitwise Operators](reference/dtrace-ref-TypesOperatorsandExpressions.md#bitwise-operators)
+ - [Assignment Operators](reference/dtrace-ref-TypesOperatorsandExpressions.md#assignment-operators)
+ - [Increment and Decrement Operators](reference/dtrace-ref-TypesOperatorsandExpressions.md#increment-and-decrement-operators)
+ - [Conditional Expressions](reference/dtrace-ref-TypesOperatorsandExpressions.md#conditional-expressions)
+ - [Type Conversions](reference/dtrace-ref-TypesOperatorsandExpressions.md#type-conversions)
+ - [Operator Precedence](reference/dtrace-ref-TypesOperatorsandExpressions.md#operator-precedence)
+ - [Type and Constant Definitions](reference/dtrace-ref-TypesOperatorsandExpressions.md#type-and-constant-definitions)
+ - [typedefs](reference/dtrace-ref-TypesOperatorsandExpressions.md#typedefs)
+ - [Enumerations](reference/dtrace-ref-TypesOperatorsandExpressions.md#enumerations)
+ - [Inlines](reference/dtrace-ref-TypesOperatorsandExpressions.md#inlines)
+ - [Type Namespaces](reference/dtrace-ref-TypesOperatorsandExpressions.md#type-namespaces)
- [Variables](reference/dtrace-ref-Variables.md)
- - [Variable Scope](reference/dtrace-ref-Variables.md#dt_vscope_dlang)
+ - [Variable Scope](reference/dtrace-ref-Variables.md#variable-scope)
- [Pointers](reference/dtrace-ref-PointersandScalarArrays.md)
- - [Pointer Safety](reference/dtrace-ref-PointersandScalarArrays.md#dt_ptrsafety_dlang)
- - [Pointer and Array Relationship](reference/dtrace-ref-PointersandScalarArrays.md#dt_ptrarel_dlang)
- - [Pointer Arithmetic](reference/dtrace-ref-PointersandScalarArrays.md#dt_ptrarith_dlang)
- - [Generic Pointers](reference/dtrace-ref-PointersandScalarArrays.md#dt_genptr_dlang)
- - [Pointers to DTrace Objects](reference/dtrace-ref-PointersandScalarArrays.md#dt_ptrobj_dlang)
- - [Pointers and Address Spaces](reference/dtrace-ref-PointersandScalarArrays.md#dt_ptraddrsp_dlang)
+ - [Pointer Safety](reference/dtrace-ref-PointersandScalarArrays.md#pointer-safety)
+ - [Pointer and Array Relationship](reference/dtrace-ref-PointersandScalarArrays.md#pointer-and-array-relationship)
+ - [Pointer Arithmetic](reference/dtrace-ref-PointersandScalarArrays.md#pointer-arithmetic)
+ - [Generic Pointers](reference/dtrace-ref-PointersandScalarArrays.md#generic-pointers)
+ - [Pointers to DTrace Objects](reference/dtrace-ref-PointersandScalarArrays.md#pointers-to-dtrace-objects)
+ - [Pointers and Address Spaces](reference/dtrace-ref-PointersandScalarArrays.md#pointers-and-address-spaces)
- [Structs and Unions](reference/dtrace-ref-StructsandUnions.md)
- - [Structs](reference/dtrace-ref-StructsandUnions.md#dt_structs_dlang)
- - [Pointers to Structs](reference/dtrace-ref-StructsandUnions.md#dt_ptrstructs_dlang)
- - [Unions](reference/dtrace-ref-StructsandUnions.md#dt_unions_dlang)
- - [Member Sizes and Offsets](reference/dtrace-ref-StructsandUnions.md#dt_memsz_dlang)
- - [Bit-Fields](reference/dtrace-ref-StructsandUnions.md#dt_bitflds_dlang)
+ - [Structs](reference/dtrace-ref-StructsandUnions.md#structs)
+ - [Pointers to Structs](reference/dtrace-ref-StructsandUnions.md#pointers-to-structs)
+ - [Unions](reference/dtrace-ref-StructsandUnions.md#unions)
+ - [Member Sizes and Offsets](reference/dtrace-ref-StructsandUnions.md#member-sizes-and-offsets)
+ - [Bit-Fields](reference/dtrace-ref-StructsandUnions.md#bit-fields)
- [DTrace String Processing](reference/dtrace-ref-DTraceSupportforStrings.md)
- - [String Representation](reference/dtrace-ref-DTraceSupportforStrings.md#dt_strrep_dlang)
- - [String Constants](reference/dtrace-ref-DTraceSupportforStrings.md#dt_strcon_dlang)
- - [String Assignment](reference/dtrace-ref-DTraceSupportforStrings.md#dt_strasg_dlang)
- - [String Conversion](reference/dtrace-ref-DTraceSupportforStrings.md#dt_strconv_dlang)
- - [String Comparison](reference/dtrace-ref-DTraceSupportforStrings.md#dt_strcomp_dlang)
+ - [String Representation](reference/dtrace-ref-DTraceSupportforStrings.md#string-representation)
+ - [String Constants](reference/dtrace-ref-DTraceSupportforStrings.md#string-constants)
+ - [String Assignment](reference/dtrace-ref-DTraceSupportforStrings.md#string-assignment)
+ - [String Conversion](reference/dtrace-ref-DTraceSupportforStrings.md#string-conversion)
+ - [String Comparison](reference/dtrace-ref-DTraceSupportforStrings.md#string-comparison)
- [Aggregations](reference/aggregation.md)
- - [Aggregation Functions](reference/aggregation.md#dt_ref_aggr_funcs)
- - [Printing Aggregations](reference/aggregation.md#dt_ref_aggr_print)
- - [Data Normalization](reference/aggregation.md#dt_ref_aggr_dnorm)
+ - [Aggregation Functions](reference/aggregation.md#aggregation-functions)
+ - [Printing Aggregations](reference/aggregation.md#printing-aggregations)
+ - [Data Normalization](reference/aggregation.md#data-normalization)
- [Speculation](reference/dtrace-ref-speculation.md)
- [DTrace Runtime and Compile-time Options Reference](reference/dtrace_runtime_options.md)
- [Setting DTrace Compile-time and Runtime Options](reference/setting_dtrace_compiler_and_runtime_options.md)
diff --git a/doc/userguide/reference/aggregation.md b/doc/userguide/reference/aggregation.md
index 0114d26f3..d1411aab5 100644
--- a/doc/userguide/reference/aggregation.md
+++ b/doc/userguide/reference/aggregation.md
@@ -13,7 +13,7 @@ Aggregations can be regular or indexed. Indexed aggregations use keys, where *ke
The *aggfunc* is one of the DTrace aggregating functions, and *args* is a comma-separated list of arguments appropriate to that function. Most aggregating functions take a single argument that represents the new datum.
-## Aggregation Functions {#dt_ref_aggr_funcs}
+## Aggregation Functions
The following functions are aggregating functions that can be used in a program to collect data and present it in a meaningful way.
@@ -36,7 +36,7 @@ The following functions are aggregating functions that can be used in a program
- `[llquantize](aggregation_llquantize.md)`: Stores the log-linear frequency distribution in an aggregation.
-## Printing Aggregations {#dt_ref_aggr_print}
+## Printing Aggregations
By default, several aggregations are displayed in the order in which they're introduced in the D program. You can override this behavior by using the `[printa](function_printa.md)` function to print the aggregations. The `printa` function also lets you precisely format the aggregation data by using a format string.
@@ -44,7 +44,7 @@ If an aggregation isn't formatted with a `printa` statement in a D program, the
The default output format for the `avg`, `count`, `min`, `max`, `stddev`, and `sum` aggregating functions displays an integer decimal value corresponding to the aggregated value for each tuple. The default output format for the `quantize`, `lquantize`, and `llquantize` aggregating functions displays an ASCII histogram with the results. Aggregation tuples are printed as though `trace` had been applied to each tuple element.
-## Data Normalization {#dt_ref_aggr_dnorm}
+## Data Normalization
When aggregating data over some period, you might want to normalize the data based on some constant factor. This technique lets you compare disjointed data more easily. For example, when aggregating system calls, you might want to output system calls as a per-second rate instead of as an absolute value over the course of the run. The DTrace `[normalize](function_normalize.md)` function lets you normalize data in this way. The parameters to `normalize` are an aggregation and a normalization factor. The output of the aggregation shows each value divided by the normalization factor.
diff --git a/doc/userguide/reference/dtrace-ref-DTraceSupportforStrings.md b/doc/userguide/reference/dtrace-ref-DTraceSupportforStrings.md
index 367d9b133..38ddc4c08 100644
--- a/doc/userguide/reference/dtrace-ref-DTraceSupportforStrings.md
+++ b/doc/userguide/reference/dtrace-ref-DTraceSupportforStrings.md
@@ -5,7 +5,7 @@ DTrace provides facilities for tracing and manipulating strings. This section de
**Parent topic:**[D Program Syntax Reference](../reference/d_program_syntax_reference.md)
-## String Representation {#dt_strrep_dlang}
+## String Representation
In DTrace, strings are represented as an array of characters ending in a null byte, which is a byte with a value of zero, usually written as `'\0'`. The visible part of the string is of variable length, depending on the location of the null byte, but DTrace stores each string in a fixed-size array so that each probe traces a consistent amount of data. Strings cannot exceed the length of the predefined string limit. However, the limit can be modified in your D program or on the `dtrace` command line by tuning the `strsize` option. The default string limit is 256 bytes.
@@ -33,13 +33,13 @@ trace(s);
You can also perform lexical comparison of expressions of type string. See [String Comparison](dtrace-ref-DTraceSupportforStrings.md).
-## String Constants {#dt_strcon_dlang}
+## String Constants
String constants are enclosed in pairs of double quotes \(`""`\) and are automatically assigned the type `string` by the D compiler. You can define string constants of any length, limited only by the amount of memory DTrace is permitted to consume on the system and by whatever limit you have set for the `strsize` DTrace runtime option. The terminating null byte \(`\0`\) is added automatically by the D compiler to any string constants that you declare. The size of a string constant object is the number of bytes associated with the string, plus one additional byte for the terminating null byte.
A string constant can't contain a literal newline character. To create strings containing newlines, use the `\n` escape sequence instead of a literal newline. String constants can also contain any of the special character escape sequences that are defined for character constants.
-## String Assignment {#dt_strasg_dlang}
+## String Assignment
Unlike the assignment of `char *` variables, strings are copied by value and not by reference. The string assignment operator `=` copies the actual bytes of the string from the source operand up to and including the null byte to the variable on the left-hand side, which must be of type `string`.
@@ -63,7 +63,7 @@ String assignment is analogous to the C library function `strcpy()`, with the ex
You can also assign to a string variable an expression of a type that's compatible with strings. In this case, the D compiler automatically promotes the source expression to the string type and performs a string assignment. The D compiler permits any expression of type `char *` or of type `char[n]`, a scalar array of `char` of any size, to be promoted to a string.
-## String Conversion {#dt_strconv_dlang}
+## String Conversion
Expressions of other types can be explicitly converted to type `string` by using a cast expression or by applying the special `stringof` operator, which are equivalent in the following meaning:
@@ -78,7 +78,7 @@ The `stringof` operator binds very tightly to the operand on its right-hand side
Scalar type expressions, such as a pointer or integer, or a scalar array address can be converted to strings, in that the scalar is interpreted as an address to a char type. Expressions of other types such as `void` may not be converted to `string`. If you erroneously convert an invalid address to a string, the DTrace safety features prevents you from damaging the system or DTrace, but you might end up tracing a sequence of undecipherable characters.
-## String Comparison {#dt_strcomp_dlang}
+## String Comparison
D overloads the binary relational operators and permits them to be used for string comparisons, as well as integer comparisons. The relational operators perform string comparison whenever both operands are of type `string` or when one operand is of type `string` and the other operand can be promoted to type `string`. See [String Assignment](dtrace-ref-DTraceSupportforStrings.md) for a detailed description. See also [Table 1](dtrace-ref-DTraceSupportforStrings.md#dt_t14_dlang), which lists the relational operators that can be used to compare strings.
diff --git a/doc/userguide/reference/dtrace-ref-PointersandScalarArrays.md b/doc/userguide/reference/dtrace-ref-PointersandScalarArrays.md
index 035f5ed15..651751dbe 100644
--- a/doc/userguide/reference/dtrace-ref-PointersandScalarArrays.md
+++ b/doc/userguide/reference/dtrace-ref-PointersandScalarArrays.md
@@ -29,7 +29,7 @@ In this example, the first fragment creates a D global variable pointer `q`. Bec
**Parent topic:**[D Program Syntax Reference](../reference/d_program_syntax_reference.md)
-## Pointer Safety {#dt_ptrsafety_dlang}
+## Pointer Safety
DTrace is a robust, safe environment for running D programs. You might write a buggy D program, but invalid D pointer accesses don't cause DTrace or the OS kernel to fail or crash in any way. Instead, the DTrace software detects any invalid pointer accesses, and returns a `BADADDR` fault; the current clause execution quits, an ERROR probe fires, and tracing continues unless the program called `[exit](function_exit.md)` for the ERROR probe.
@@ -55,7 +55,7 @@ dtrace: error on enabled probe ID 2 (ID 1: dtrace:::BEGIN): invalid address (0x0
Notice that the D program moves past the error and continues to run; the system and all observed processes remain unperturbed. You can also add an `ERROR` probe to any script to handle D errors. For details about the DTrace error mechanism, see [ERROR Probe](dtrace_providers_dtrace.md).
-## Pointer and Array Relationship {#dt_ptrarel_dlang}
+## Pointer and Array Relationship
A scalar array is represented by a variable that's associated with the address of its first storage location. A pointer is also the address of a storage location with a defined type. Thus, D permits the use of the array `[]` index notation with both pointer variables and array variables. For example, the following two D fragments are equivalent in meaning:
@@ -71,7 +71,7 @@ The difference between pointers and arrays is that a pointer variable refers to
This difference is manifested in the D syntax if you try to assign pointers and scalar arrays. If `x` and `y` are pointer variables, the expression `x = y` is legal; it copies the pointer address in `y` to the storage location that's named by `x`. If `x` and `y` are scalar array variables, the expression `x = y` isn't legal. Arrays can't be assigned as a whole in D. If `p` is a pointer and `a` is a scalar array, the statement `p = a` is permitted. This statement is equivalent to the statement `p = &a[0]`.
-## Pointer Arithmetic {#dt_ptrarith_dlang}
+## Pointer Arithmetic
As in C, pointer arithmetic in D isn't identical to integer arithmetic. Pointer arithmetic implicitly adjusts the underlying address by multiplying or dividing the operands by the size of the type referenced by the pointer.
@@ -106,17 +106,17 @@ BEGIN
}
```
-## Generic Pointers {#dt_genptr_dlang}
+## Generic Pointers
Sometimes it's useful to represent or manipulate a generic pointer address in a D program without specifying the type of data referred to by the pointer. Generic pointers can be specified by using the type `void *`, where the keyword `void` represents the absence of specific type information, or by using the built-in type alias `uintptr_t`, which is aliased to an unsigned integer type of size that's appropriate for a pointer in the current data model. You can't apply pointer arithmetic to an object of type `void *`, and these pointers can't be dereferenced without casting them to another type first. You can cast a pointer to the `uintptr_t` type when you need to perform integer arithmetic on the pointer value.
Pointers to `void` can be used in any context where a pointer to another data type is required, such as an associative array tuple expression or the right-hand side of an assignment statement. Similarly, a pointer to any data type can be used in a context where a pointer to `void` is required. To use a pointer to a non-`void` type in place of another non-`void` pointer type, an explicit cast is required. You must always use explicit casts to convert pointers to integer types, such as `uintptr_t`, or to convert these integers back to the appropriate pointer type.
-## Pointers to DTrace Objects {#dt_ptrobj_dlang}
+## Pointers to DTrace Objects
The D compiler prohibits you from using the `&` operator to obtain pointers to DTrace objects such as associative arrays, built-in functions, and variables. You're prohibited from obtaining the address of these variables so that the DTrace runtime environment is free to relocate them as needed between probe firings . In this way, DTrace can more efficiently manage the memory required for programs. If you create composite structures, it's possible to construct expressions that retrieve the kernel address of DTrace object storage. Avoid creating such expressions in D programs. If you need to use such an expression, don't rely on the address being the same across probe firings.
-## Pointers and Address Spaces {#dt_ptraddrsp_dlang}
+## Pointers and Address Spaces
A pointer is an address that provides a translation within some *virtual address space* to a piece of physical memory. DTrace runs D programs within the address space of the OS kernel itself. The Linux system manages many address spaces: one for the OS kernel itself, and one for each user process. Because each address space provides the illusion that it can access all the memory on the system, the same virtual address pointer value can be reused across address spaces, but translate to different physical memory. Therefore, when writing D programs that use pointers, you must be aware of the address space corresponding to the pointers you intend to use.
diff --git a/doc/userguide/reference/dtrace-ref-StructsandUnions.md b/doc/userguide/reference/dtrace-ref-StructsandUnions.md
index 79115e362..fcd07320f 100644
--- a/doc/userguide/reference/dtrace-ref-StructsandUnions.md
+++ b/doc/userguide/reference/dtrace-ref-StructsandUnions.md
@@ -5,7 +5,7 @@ Collections of related variables can be grouped together into composite data obj
**Parent topic:**[D Program Syntax Reference](../reference/d_program_syntax_reference.md)
-## Structs {#dt_structs_dlang}
+## Structs
The D keyword `struct`, short for *structure*, is used to introduce a new type that's composed of a group of other types. The new `struct` type can be used as the type for D variables and arrays, enabling you to define groups of related variables under a single name. D structs are the same as the corresponding construct in C and C++. If you have programmed in the Java programming language, think of a D struct as a class that contains only data members and no methods.
@@ -122,7 +122,7 @@ The `date` program runs and is traced until it exits and fires the `END` probe w
write 1 29 9817
```
-## Pointers to Structs {#dt_ptrstructs_dlang}
+## Pointers to Structs
Referring to structs by using pointers is common in C and D. You can use the operator `->` to access struct members through a pointer. If `struct s` has a member `m`, and you have a pointer to this struct named `sp`, where `sp` is a variable of type `struct s *`, you can either use the `*` operator to first dereference the `sp` pointer to access the member:
@@ -217,11 +217,11 @@ date -R run by UID 500
Complex data structures are used often in C programs, so the ability to describe and reference structs from D also provides a powerful capability for observing the inner workings of the Linux kernel and its system interfaces.
-## Unions {#dt_unions_dlang}
+## Unions
Unions are another kind of composite type available in ANSI C and D and are related to structs. A union is a composite type where a set of members of different types are defined and the member objects all occupy the same region of storage. A union is therefore an object of variant type, where only one member is valid at any particular time, depending on how the union has been assigned. Typically, some other variable, or piece of state is used to indicate which union member is currently valid. The size of a union is the size of its largest member. The memory alignment that's used for the union is the maximum alignment required by the union members.
-## Member Sizes and Offsets {#dt_memsz_dlang}
+## Member Sizes and Offsets
You can determine the size in bytes of any D type or expression, including a `struct` or `union`, by using the `sizeof` operator. The `sizeof` operator can be applied either to an expression or to the name of a type surrounded by parentheses, as illustrated in the following two examples:
@@ -240,7 +240,7 @@ offsetof (*type-name*, *member-name*)
Here, *type-name* is the name of any `struct` or `union` type or type alias, and *member-name* is the identifier naming a member of that struct or union. Similar to `sizeof`, `offsetof` returns a `size_t` and you can use it anywhere in a D program that an integer constant can be used.
-## Bit-Fields {#dt_bitflds_dlang}
+## Bit-Fields
D also permits the definition of integer struct and union members of arbitrary numbers of bits, known as *bit-fields*. A bit-field is declared by specifying a signed or unsigned integer base type, a member name, and a suffix indicating the number of bits to be assigned for the field, as shown in the following example:
diff --git a/doc/userguide/reference/dtrace-ref-TypesOperatorsandExpressions.md b/doc/userguide/reference/dtrace-ref-TypesOperatorsandExpressions.md
index 013989706..2d7172366 100644
--- a/doc/userguide/reference/dtrace-ref-TypesOperatorsandExpressions.md
+++ b/doc/userguide/reference/dtrace-ref-TypesOperatorsandExpressions.md
@@ -5,7 +5,7 @@ D provides the ability to access and manipulate various data objects: variables
**Parent topic:**[D Program Syntax Reference](../reference/d_program_syntax_reference.md)
-## Identifier Names and Keywords {#dt_ident_dlang}
+## Identifier Names and Keywords
D identifier names are composed of uppercase and lowercase letters, digits, and underscores, where the first character must be a letter or underscore. All identifier names beginning with an underscore \(`_`\) are reserved for use by the D system libraries. Avoid using these names in D programs. By convention, D programmers typically use mixed-case names for variables and all uppercase names for constants.
@@ -203,7 +203,7 @@ D language keywords are special identifiers that are reserved for use in the pro
</td></tr><tbody></table>
D reserves for use as keywords a superset of the ANSI C keywords. The keywords reserved for future use by the D language are marked with `*`. The D compiler produces a syntax error if you try to use a keyword that's reserved for future use. The keywords that are defined by D but not defined by ANSI C are marked with `+`. D provides the complete set of types and operators found in ANSI C. The major difference in D programming is the absence of control-flow constructs. Note that keywords associated with control-flow in ANSI C are reserved for future use in D.
-## Data Types and Sizes {#dt_dtypes_dlang}
+## Data Types and Sizes
D provides fundamental data types for integers and floating-point constants. Arithmetic can only be performed on integers in D programs. Floating-point constants can be used to initialize data structures, but floating-point arithmetic isn't permitted in D. D provides a 64-bit data model for use in writing programs.
@@ -392,7 +392,7 @@ Type Name
</td></tr><tbody></table>
D also provides the special type `string` to represent ASCII strings. Strings are discussed in more detail in [DTrace String Processing](dtrace-ref-DTraceSupportforStrings.md).
-## Constants {#dt_consts_dlang}
+## Constants
Integer constants can be written in decimal \(`12345`\), octal \(`012345`\), or hexadecimal `(0x12345`\) format. Octal \(base 8\) constants must be prefixed with a leading zero. Hexadecimal \(base 16\) constants must be prefixed with either `0x` or `0X`. Integer constants are assigned the smallest type among `int`, `long`, and `long long` that can represent their value. If the value is negative, the signed version of the type is used. If the value is positive and too large to fit in the signed type representation, the unsigned type representation is used. You can apply one of the suffixes listed in the following table to any integer constant to explicitly specify its D type.
@@ -607,7 +607,7 @@ You can include more than one character specifier inside single quotes to create
Strings constants of any length can be composed by enclosing them in a pair of double quotes \(`"hello"`\). A string constant can't contain a literal newline character. To create strings containing newlines, use the `\n` escape sequence instead of a literal newline. String constants can contain any of the special character escape sequences that are shown for character constants before. Similar to ANSI C, strings are represented as arrays of characters that end with a null character \(`\0`\) that's implicitly added to each string constant you declare. String constants are assigned the special D type `string`. The D compiler provides a set of special features for comparing and tracing character arrays that are declared as strings.
-## Arithmetic Operators {#dt_arithops_dlang}
+## Arithmetic Operators
Binary arithmetic operators are described in the following table. These operators all have the same meaning for integers that they do in ANSI C.
@@ -666,7 +666,7 @@ However, the DTrace execution environment does automatically check for and repor
In addition to these binary operators, the `+` and `-` operators can also be used as unary operators, and these operators have higher precedence than any of the binary arithmetic operators. The order of precedence and associativity properties for all D operators is presented in [Operator Precedence](dtrace-ref-TypesOperatorsandExpressions.md). You can control precedence by grouping expressions in parentheses \(`()`\).
-## Relational Operators {#dt_relatops_dlang}
+## Relational Operators
Binary relational operators are described in the following table. These operators all have the same meaning that they do in ANSI C.
@@ -766,7 +766,7 @@ Returns 0 \(`false`\)
</td></tr><tbody></table>
Relational operators can also be used to compare a data object associated with an enumeration type with any of the enumerator tags defined by the enumeration.
-## Logical Operators {#dt_logicops_dlang}
+## Logical Operators
Binary logical operators are listed in the following table. The first two operators are equivalent to the corresponding ANSI C operators.
@@ -809,7 +809,7 @@ In addition to the binary logical operators, the unary `!` operator can be used
The logical operators can be applied to operands of integer or pointer types. The logical operators interpret pointer operands as unsigned integer values. As with all logical and relational operators in D, operands are true if they have a non-zero integer value and false if they have a zero integer value.
-## Bitwise Operators {#dt_bitwiseops_dlang}
+## Bitwise Operators
D provides the bitwise operators that are listed in the following table for manipulating individual bits inside integer operands. These operators all have the same meaning as in ANSI C.
@@ -874,7 +874,7 @@ The shift operators are used to move bits left or right in a particular integer
Shifting an integer value by a negative number of bits or by a number of bits larger than the number of bits in the left-hand operand itself produces an undefined result. The D compiler produces an error message if the compiler can detect this condition when you compile the D program.
-## Assignment Operators {#dt_assignops_dlang}
+## Assignment Operators
Binary assignment operators are listed in the following table. You can only modify D variables and arrays. Kernel data objects and constants can not be modified using the D assignment operators. The assignment operators have the same meaning as they do in ANSI C.
@@ -979,7 +979,7 @@ Aside from the assignment operator `=`, the other assignment operators are provi
The result of any assignment operator is an expression equal to the new value of the left-hand expression. You can use the assignment operators or any of the operators described thus far in combination to form expressions of arbitrary complexity. You can use parentheses `()` to group terms in complex expressions.
-## Increment and Decrement Operators {#dt_incdecops_dlang}
+## Increment and Decrement Operators
D provides the special unary `++` and `--` operators for incrementing and decrementing pointers and integers. These operators have the same meaning as they do in ANSI C. These operators can be applied to variables and to the individual elements of a struct, union, or array. The operators can be applied either before or after the variable name. If the operator appears before the variable name, the variable is first changed and then the resulting expression is equal to the new value of the variable. For example, the following two code fragments produce identical results:
@@ -1012,7 +1012,7 @@ foo[1]++;
The increment and decrement operators can be applied to integer or pointer variables. When applied to integer variables, the operators increment, or decrement the corresponding value by one. When applied to pointer variables, the operators increment, or decrement the pointer address by the size of the data type that's referenced by the pointer.
-## Conditional Expressions {#dt_condexp_dlang}
+## Conditional Expressions
D doesn't provide the facility to use `if-then-else` constructs. Instead, conditional expressions, by using the ternary operator \(`?:`\), can be used to approximate some of this functionality. The ternary operator associates a triplet of expressions, where the first expression is used to conditionally evaluate one of the other two.
@@ -1032,7 +1032,7 @@ hexval = (c >= '0' && c <= '9') ? c - '0' : (c >= 'a' && c <= 'f') ? c + 10 - 'a
To be evaluated for its truth value, the first expression that's used with `?:` must be a pointer or integer. The second and third expressions can be of any compatible types. You can't construct a conditional expression where, for example, one path returns a string and another path returns an integer. The second and third expressions must be true expressions that have a value. Therefore, data reporting functions can't be used in these expressions because those functions don't return a value. To conditionally trace data, use a predicate instead.
-## Type Conversions {#dt_typeconv_dlang}
+## Type Conversions
When expressions are constructed by using operands of different but compatible types, type conversions are performed to determine the type of the resulting expression. The D rules for type conversions are the same as the arithmetic conversion rules for integers in ANSI C. These rules are sometimes referred to as the *usual arithmetic conversions*.
@@ -1052,7 +1052,7 @@ In this example, the destination type is within parentheses and used to prefix t
Because D doesn't include floating-point arithmetic, no floating-point operand conversion or casting is permitted and no rules for implicit floating-point conversion are defined.
-## Operator Precedence {#dt_preced_dlang}
+## Operator Precedence
D includes complex rules for operator precedence and associativity. The rules provide precise compatibility with the ANSI C operator precedence rules. The entries in the following table are in order from highest precedence to lowest precedence.
@@ -1268,11 +1268,11 @@ Dereferences a pointer to an object.
Accesses a member of a structure or union type.
</td></tr><tbody></table>
-## Type and Constant Definitions {#dt_typcondef_dlang}
+## Type and Constant Definitions
This section describes how to declare type aliases and named constants in D. It also discusses D type and namespace management for program and OS types and identifiers.
-### typedefs {#dt_typedefs_dlang}
+### typedefs
The `typedef` keyword is used to declare an identifier as an alias for an existing type. The `typedef` declaration is used outside of probe clauses in the following form:
@@ -1297,7 +1297,7 @@ typedef struct foo {
In the previous example, `struct foo` is defined using the same type as its alias, `foo_t`. Linux C system headers often use the suffix `_t` to denote a `typedef` alias.
-### Enumerations {#dt_enums_dlang}
+### Enumerations
Defining symbolic names for constants in a program eases readability and simplifies the process of maintaining the program in the future. One method is to define an *enumeration*, which associates a set of integers with a set of identifiers called enumerators that the compiler recognizes and replaces with the corresponding integer value. An enumeration is defined by using a declaration such as the following:
@@ -1329,7 +1329,7 @@ The D enumeration syntax is the same as the corresponding syntax in ANSI C. D al
-### Inlines {#dt_inlines_dlang}
+### Inlines
D named constants can also be defined by using `inline` directives, which provide a more general means of creating identifiers that are replaced by predefined values or expressions during compilation. Inline directives are a more powerful form of lexical replacement than the `#define` directive provided by the C preprocessor because the replacement is assigned an actual type and is performed by using the compiled syntax tree and not a set of lexical tokens. An `inline` directive is specified by using a declaration of the following form:
@@ -1371,7 +1371,7 @@ These inline definitions provide you with access to the current set of Linux sig
By default, the D compiler includes all the provided D library files automatically so that you can use these definitions in any D program.
-### Type Namespaces {#dt_typens_dlang}
+### Type Namespaces
In traditional languages such as ANSI C, type visibility is determined by whether a type is nested inside a function or other declaration. Types declared at the outer scope of a C program are associated with a single global namespace and are visible throughout the entire program. Types that are defined in C header files are typically included in this outer scope. Unlike these languages, D provides access to types from several outer scopes.
diff --git a/doc/userguide/reference/dtrace-ref-Variables.md b/doc/userguide/reference/dtrace-ref-Variables.md
index c4d7c4014..28ffa693d 100644
--- a/doc/userguide/reference/dtrace-ref-Variables.md
+++ b/doc/userguide/reference/dtrace-ref-Variables.md
@@ -80,7 +80,7 @@ D provides several variable types: scalar variables, associative arrays, scalar
**Parent topic:**[D Program Syntax Reference](../reference/d_program_syntax_reference.md)
-## Variable Scope {#dt_vscope_dlang}
+## Variable Scope
Variable scoping is used to define where variable names are valid within a program and to avoid variable naming collisions. By using scoped variables you can control the availability of the variable instance to the whole program, a particular thread, or a specific clause.
--
2.47.3
More information about the DTrace-devel
mailing list