[Lldb-commits] [lldb] 11e2922 - [lldb][docs] Document SBType
Raphael Isemann via lldb-commits
lldb-commits at lists.llvm.org
Mon Jun 14 04:19:41 PDT 2021
Author: Raphael Isemann
Date: 2021-06-14T13:19:19+02:00
New Revision: 11e2922bb7adbbca17c3a0f44779aa87dbc64b42
URL: https://github.com/llvm/llvm-project/commit/11e2922bb7adbbca17c3a0f44779aa87dbc64b42
DIFF: https://github.com/llvm/llvm-project/commit/11e2922bb7adbbca17c3a0f44779aa87dbc64b42.diff
LOG: [lldb][docs] Document SBType
This documents the behaviour of the different SBType functions with notes for
the language-specific behaviour for C/C++/Objective-C. All of this reflects the
current behaviour of LLDB (even though that also means some functions behave
kinda weird but at least they are now documented to be weird)
Reviewed By: #lldb, mib
Differential Revision: https://reviews.llvm.org/D103454
Added:
Modified:
lldb/bindings/interface/SBType.i
Removed:
################################################################################
diff --git a/lldb/bindings/interface/SBType.i b/lldb/bindings/interface/SBType.i
index e7b3fd11e3380..500bc99ca8cd4 100644
--- a/lldb/bindings/interface/SBType.i
+++ b/lldb/bindings/interface/SBType.i
@@ -111,8 +111,24 @@ protected:
};
%feature("docstring",
-"Represents a data type in lldb. The FindFirstType() method of SBTarget/SBModule
-returns a SBType.
+"Represents a data type in lldb.
+
+The actual characteristics of each type are defined by the semantics of the
+programming language and the specific language implementation that was used
+to compile the target program. See the language-specific notes in the
+documentation of each method.
+
+SBType instances can be obtained by a variety of methods.
+`SBTarget.FindFirstType` and `SBModule.FindFirstType` can be used to create
+`SBType` representations of types in executables/libraries with debug
+information. For some languages such as C, C++ and Objective-C it is possible
+to create new types by evaluating expressions that define a new type.
+
+Note that most `SBType` properties are computed independently of any runtime
+information so for dynamic languages the functionality can be very limited.
+`SBValue` can be used to represent runtime values which then can be more
+accurately queried for certain information such as byte size.
+
SBType supports the eq/ne operator. For example,::
@@ -181,7 +197,7 @@ SBType supports the eq/ne operator. For example,::
# id_type and int_type should be the same type!
self.assertTrue(id_type == int_type)
-...") SBType;
+") SBType;
class SBType
{
public:
@@ -196,132 +212,649 @@ public:
explicit operator bool() const;
+
+ %feature("docstring",
+ "Returns the number of bytes a variable with the given types occupies in memory.
+
+ Returns ``0`` if the size can't be determined.
+
+ If a type occupies ``N`` bytes + ``M`` bits in memory, this function returns
+ the rounded up amount of bytes (i.e., if ``M`` is ``0``,
+ this function returns ``N`` and otherwise ``N + 1``).
+
+ Language-specific behaviour:
+
+ * C: The output is expected to match the value of ``sizeof(Type)``. If
+ ``sizeof(Type)`` is not a valid expression for the given type, the
+ function returns ``0``.
+ * C++: Same as in C.
+ * Objective-C: Same as in C. For Objective-C classes this always returns
+ `0`` as the actual size depends on runtime information.
+ ") GetByteSize;
uint64_t
GetByteSize();
+
+ %feature("docstring",
+ "Returns true if this type is a pointer type.
+
+ Language-specific behaviour:
+
+ * C: Returns true for C pointer types (or typedefs of these types).
+ * C++: Pointer types include the C pointer types as well as pointers to data
+ mebers or member functions.
+ * Objective-C: Pointer types include the C pointer types. ``id``, ``Class``
+ and pointers to blocks are also considered pointer types.
+ ") IsPointerType;
bool
IsPointerType();
+ %feature("docstring",
+ "Returns true if this type is a reference type.
+
+ Language-specific behaviour:
+
+ * C: Returns false for all types.
+ * C++: Both l-value and r-value references are considered reference types.
+ * Objective-C: Returns false for all types.
+ ") IsReferenceType;
bool
IsReferenceType();
+ %feature("docstring",
+ "Returns true if this type is a function type.
+
+ Language-specific behaviour:
+
+ * C: Returns true for types that represent functions. Note that function
+ pointers are not function types (but their `GetPointeeType()` are function
+ types).
+ * C++: Same as in C.
+ * Objective-C: Returns false for all types.
+ ") IsPolymorphicClass;
bool
IsFunctionType ();
+ %feature("docstring",
+ "Returns true if this type is a polymorphic type.
+
+ Language-specific behaviour:
+
+ * C: Returns false for all types.
+ * C++: Returns true if the type is a class type that contains at least one
+ virtual member function or if at least one of its base classes is
+ considered a polymorphic type.
+ * Objective-C: Returns false for all types.
+ ") IsPolymorphicClass;
bool
IsPolymorphicClass ();
+ %feature("docstring",
+ "Returns true if this type is an array type.
+
+ Language-specific behaviour:
+
+ * C: Returns true if the types is an array type. This includes incomplete
+ array types ``T[]`` and array types with integer (``T[1]``) or variable
+ length (``T[some_variable]``). Pointer types are not considered arrays.
+ * C++: Includes C's array types and dependent array types (i.e., array types
+ in templates which size depends on template arguments).
+ * Objective-C: Same as in C.
+ ") IsArrayType;
bool
IsArrayType ();
+ %feature("docstring",
+ "Returns true if this type is a vector type.
+
+ Language-specific behaviour:
+
+ * C: Returns true if the types is a vector type created with
+ GCC's ``vector_size`` or Clang's ``ext_vector_type`` feature.
+ * C++: Same as in C.
+ * Objective-C: Same as in C.
+ ") IsVectorType;
bool
IsVectorType ();
+ %feature("docstring",
+ "Returns true if this type is a typedef.
+
+ Language-specific behaviour:
+
+ * C: Returns true if the type is a C typedef.
+ * C++: Same as in C. Also treats type aliases as typedefs.
+ * Objective-C: Same as in C.
+ ") IsTypedefType;
bool
IsTypedefType ();
+ %feature("docstring",
+ "Returns true if this type is an anonymous type.
+
+ Language-specific behaviour:
+
+ * C: Returns true for anonymous unions. Also returns true for
+ anonymous structs (which are a GNU language extension).
+ * C++: Same as in C.
+ * Objective-C: Same as in C.
+ ") IsAnonymousType;
bool
IsAnonymousType ();
+ %feature("docstring",
+ "Returns true if this type is a scoped enum.
+
+ Language-specific behaviour:
+
+ * C: Returns false for all types.
+ * C++: Return true only for C++11 scoped enums.
+ * Objective-C: Returns false for all types.
+ ") IsScopedEnumerationType;
bool
IsScopedEnumerationType ();
+ %feature("docstring",
+ "Returns a type that represents a pointer to this type.
+
+ If the type system of the current language can't represent a pointer to this
+ type or this type is invalid, an invalid `SBType` is returned.
+
+ Language-specific behaviour:
+
+ * C: Returns the pointer type of this type.
+ * C++: Same as in C.
+ * Objective-C: Same as in C.
+ ") GetPointerType;
lldb::SBType
GetPointerType();
+ %feature("docstring",
+ "Returns the underlying pointee type.
+
+ If this type is a pointer type as specified by `IsPointerType` then this
+ returns the underlying type. If this is not a pointer type or an invalid
+ `SBType` then this returns an invalid `SBType`.
+
+ Language-specific behaviour:
+
+ * C: Returns the underlying type for for C pointer types or typedefs of
+ these types). For example, ``int *`` will return ``int``.
+ * C++: Same as in C. Returns an `SBType` representation for data members/
+ member functions in case the `SBType` is a pointer to data member or
+ pointer to member function.
+ * Objective-C: Same as in C. The pointee type of ``id`` and ``Class`` is
+ an invalid `SBType`. The pointee type of pointers Objective-C types is an
+ `SBType` for the non-pointer type of the respective type. For example,
+ ``NSString *`` will return ``NSString`` as a pointee type.
+ ") GetPointeeType;
lldb::SBType
GetPointeeType();
+ %feature("docstring",
+ "Returns a type that represents a reference to this type.
+
+ If the type system of the current language can't represent a reference to
+ this type, an invalid `SBType` is returned.
+
+ Language-specific behaviour:
+
+ * C: Currently assumes the type system is C++ and returns an l-value
+ reference type. For example, ``int`` will return ``int&``. This behavior
+ is likely to change in the future and shouldn't be relied on.
+ * C++: Same as in C.
+ * Objective-C: Same as in C.
+ ") GetReferenceType;
lldb::SBType
GetReferenceType();
+ %feature("docstring",
+ "Returns the underlying type of a typedef.
+
+ If this type is a typedef as designated by `IsTypedefType`, then the
+ underlying type is being returned. Otherwise an invalid `SBType` is
+ returned.
+
+ Language-specific behaviour:
+
+ * C: Returns the underlying type of a typedef type.
+ * C++: Same as in C. For type aliases, the underlying type is returned.
+ * Objective-C: Same as in C.
+ ") GetTypedefedType;
lldb::SBType
SBType::GetTypedefedType();
+ %feature("docstring",
+ "Returns the underlying type of a reference type.
+
+ If this type is a reference as designated by `IsReferenceType`, then the
+ underlying type is being returned. Otherwise an invalid `SBType` is
+ returned.
+
+ Language-specific behaviour:
+
+ * C: Always returns an invalid type.
+ * C++: For l-value and r-value references the underlying type is returned.
+ For example, ``int &`` will return ``int``.
+ * Objective-C: Same as in C.
+ ") GetDereferencedType;
lldb::SBType
GetDereferencedType();
+ %feature("docstring",
+ "Returns the unqualified version of this type.
+
+ Language-specific behaviour:
+
+ * C: If this type with any const or volatile specifier removed.
+ * C++: Same as in C.
+ * Objective-C: Same as in C.
+ ") GetUnqualifiedType;
lldb::SBType
GetUnqualifiedType();
lldb::SBType
GetCanonicalType();
+ %feature("docstring",
+ "Returns the underlying integer type if this is an enumeration type.
+
+ If this type is an invalid `SBType` or not an enumeration type an invalid
+ `SBType` is returned.
+
+ Language-specific behaviour:
+
+ * C: Returns the underlying type for enums.
+ * C++: Same as in C but also returns the underlying type for scoped enums.
+ * Objective-C: Same as in C.
+ ") GetEnumerationIntegerType;
lldb::SBType
GetEnumerationIntegerType();
+ %feature("docstring",
+ "Returns the array element type if this type is an array type.
+
+ Otherwise returns an invalid `SBType` if this type is invalid or not an
+ array type.
+
+ Language-specific behaviour:
+
+ * C: If this is an array type (see `IsArrayType`) such as ``T[]``, returns
+ the element type.
+ * C++: Same as in C.
+ * Objective-C: Same as in C.
+
+ See also `IsArrayType`.
+ ") GetArrayElementType;
lldb::SBType
GetArrayElementType ();
+ %feature("docstring",
+ "Returns the array type with the given constant size.
+
+ Language-specific behaviour:
+
+ * C: Returns a constant-size array `T[size]` for any non-void type.
+ * C++: Same as in C.
+ * Objective-C: Same as in C.
+
+ See also `IsArrayType` and `GetArrayElementType`.
+ ") GetArrayType;
lldb::SBType
GetArrayType (uint64_t size);
+ %feature("docstring",
+ "Returns the vector element type if this type is a vector type.
+
+ Otherwise returns an invalid `SBType` if this type is invalid or not a
+ vector type.
+
+ Language-specific behaviour:
+
+ * C: If this is a vector type (see `IsVectorType`), returns the element
+ type.
+ * C++: Same as in C.
+ * Objective-C: Same as in C.
+
+ See also `IsVectorType`.
+ ") GetVectorElementType;
lldb::SBType
GetVectorElementType ();
+ %feature("docstring",
+ "Returns the `BasicType` value that is most appropriate to this type.
+
+ Returns `eBasicTypeInvalid` if no appropriate `BasicType` was found or this
+ type is invalid. See the `BasicType` documentation for the language-specific m
+ aning of each `BasicType` value.
+
+ **Overload behaviour:** When called with a `BasicType` parameter, the
+ following behaviour applies:
+
+ Returns the `SBType` that represents the passed `BasicType` value. Returns
+ an invalid `SBType` if no fitting `SBType` could be created.
+
+ Language-specific behaviour:
+
+ * C: Returns the respective builtin type. Note that some types
+ (e.g. ``__uint128_t``) might even be successfully created even if they are
+ not available on the target platform. C++ and Objective-C specific types
+ might also be created even if the target program is not written in C++ or
+ Objective-C.
+ * C++: Same as in C.
+ * Objective-C: Same as in C.
+ ");
lldb::BasicType
GetBasicType();
lldb::SBType
GetBasicType (lldb::BasicType type);
+ %feature("docstring",
+ "Returns the number of fields of this type.
+
+ Returns ``0`` if this type does not have fields.
+
+ Language-specific behaviour:
+
+ * C: Returns the number of fields if the type is a struct. If the type
+ contains an anonymous struct/union it only counts as a single field (even
+ if the struct/union contains several fields).
+ * C++: Returns the number of non-static fields if the type is a
+ struct/class. If the type contains an anonymous struct/union it only
+ counts as a single field (even if the struct/union contains several
+ fields). The fields of any base classes are not included in the count.
+ * Objective-C: Same as in C for structs. For Objective-C classes the number
+ of ivars is returned.
+
+ See also `GetFieldAtIndex`.
+ ") GetNumberOfFields;
uint32_t
GetNumberOfFields ();
+ %feature("docstring",
+ "Returns the number of base/parent classes of this type.
+
+ Returns ``0`` if this type doesn't have any base classes.
+
+ Language-specific behaviour:
+
+ * C: Returns always ``0``.
+ * C++: The number of direct non-virtual base classes if this type is
+ a class.
+ * Objective-C: The number of super classes for Objective-C classes.
+ As Objective-C doesn't have multiple inheritance this is usually returns 1
+ except for NSObject.
+ ") GetNumberOfDirectBaseClasses;
uint32_t
GetNumberOfDirectBaseClasses ();
+ %feature("docstring",
+ "Returns the number of virtual base/parent classes of this type
+
+ Returns ``0`` if this type doesn't have any base classes.
+
+ Language-specific behaviour:
+
+ * C: Returns always ``0``.
+ * C++: The number of direct virtual base classes if this type is a
+ class.
+ * Objective-C: Returns always ``0``.
+ ") GetNumberOfVirtualBaseClasses;
uint32_t
GetNumberOfVirtualBaseClasses ();
+ %feature("docstring",
+ "Returns the field at the given index.
+
+ Returns an invalid `SBType` if the index is out of range or the current
+ type doesn't have any fields.
+
+ Language-specific behaviour:
+
+ * C: Returns the field with the given index for struct types. Fields are
+ ordered/indexed starting from ``0`` for the first field in a struct (as
+ declared in the definition).
+ * C++: Returns the non-static field with the given index for struct types.
+ Fields are ordered/indexed starting from ``0`` for the first field in a
+ struct (as declared in the definition).
+ * Objective-C: Same as in C for structs. For Objective-C classes the ivar
+ with the given index is returned. ivars are indexed starting from ``0``.
+ ") GetFieldAtIndex;
lldb::SBTypeMember
GetFieldAtIndex (uint32_t idx);
+ %feature("docstring",
+ "Returns the direct base class as indexed by `GetNumberOfDirectBaseClasses`.
+
+ Returns an invalid SBTypeMember if the index is invalid or this SBType is
+ invalid.
+ ") GetDirectBaseClassAtIndex;
lldb::SBTypeMember
GetDirectBaseClassAtIndex (uint32_t idx);
+ %feature("docstring",
+ "Returns the virtual base class as indexed by
+ `GetNumberOfVirtualBaseClasses`.
+
+ Returns an invalid SBTypeMember if the index is invalid or this SBType is
+ invalid.
+ ") GetVirtualBaseClassAtIndex;
lldb::SBTypeMember
GetVirtualBaseClassAtIndex (uint32_t idx);
lldb::SBTypeEnumMemberList
GetEnumMembers();
+ %feature("docstring",
+ "Returns the `SBModule` this `SBType` belongs to.
+ Returns no `SBModule` if this type does not belong to any specific
+ `SBModule` or this `SBType` is invalid. An invalid `SBModule` might also
+ indicate that once came from an `SBModule` but LLDB could no longer
+ determine the original module.
+ ") GetModule;
lldb::SBModule
GetModule();
+ %feature("autodoc", "GetName() -> string") GetName;
+ %feature("docstring",
+ "Returns the name of this type.
+
+ Returns an empty string if an error occurred or this type is invalid.
+
+ Use this function when trying to match a specific type by name in a script.
+ The names returned by this function try to uniquely identify a name but
+ conflicts can occur (for example, if a C++ program contains two
diff erent
+ classes with the same name in
diff erent translation units. `GetName` can
+ return the same name for both class types.)
+
+
+ Language-specific behaviour:
+
+ * C: The name of the type. For structs the ``struct`` prefix is omitted.
+ * C++: Returns the qualified name of the type (including anonymous/inline
+ namespaces and all template arguments).
+ * Objective-C: Same as in C.
+ ") GetName;
const char*
GetName();
+ %feature("autodoc", "GetDisplayTypeName() -> string") GetDisplayTypeName;
+ %feature("docstring",
+ "Returns the name of this type in a user-friendly format.
+
+ Returns an empty string if an error occurred or this type is invalid.
+
+ Use this function when displaying a type name to the user.
+
+ Language-specific behaviour:
+
+ * C: Returns the type name. For structs the ``struct`` prefix is omitted.
+ * C++: Returns the qualified name. Anonymous/inline namespaces are omitted.
+ Template arguments that match their default value might also be hidden
+ (this functionality depends on whether LLDB can determine the template's
+ default arguments).
+ * Objective-C: Same as in C.
+ ") GetDisplayTypeName;
const char *
GetDisplayTypeName ();
+ %feature("autodoc", "GetTypeClass() -> TypeClass") GetTypeClass;
+ %feature("docstring",
+ "Returns the `TypeClass` for this type.
+
+ Returns an `eTypeClassInvalid` if this `SBType` is invalid.
+
+ See `TypeClass` for the language-specific meaning of each `TypeClass` value.
+ ") GetTypeClass;
lldb::TypeClass
GetTypeClass ();
+ %feature("docstring",
+ "Returns the number of template arguments of this type.
+
+ Returns ``0`` if this type is not a template.
+
+ Language-specific behaviour:
+
+ * C: Always returns ``0``.
+ * C++: If this type is a class template instantiation then this returns the
+ number of template parameters that were used in this instantiation. This i
+ cludes both explicit and implicit template parameters.
+ * Objective-C: Always returns ``0``.
+ ") GetNumberOfTemplateArguments;
uint32_t
GetNumberOfTemplateArguments ();
+ %feature("docstring",
+ "Returns the type of the template argument with the given index.
+
+ Returns an invalid `SBType` if there is no template argument with the given
+ index or this type is not a template. The first template argument has the
+ index ``0``.
+
+ Language-specific behaviour:
+
+ * C: Always returns an invalid SBType.
+ * C++: If this type is a class template instantiation and the template
+ parameter with the given index is a type template parameter, then this
+ returns the type of that parameter. Otherwise returns an invalid `SBType`.
+ * Objective-C: Always returns an invalid SBType.
+ ") GetTemplateArgumentType;
lldb::SBType
GetTemplateArgumentType (uint32_t idx);
+ %feature("docstring",
+ "Returns the kind of the template argument with the given index.
+
+ Returns `eTemplateArgumentKindNull` if there is no template argument
+ with the given index or this type is not a template. The first template
+ argument has the index ``0``.
+
+ Language-specific behaviour:
+
+ * C: Always returns `eTemplateArgumentKindNull`.
+ * C++: If this type is a class template instantiation then this returns
+ the appropriate `TemplateArgument` value for the parameter with the given
+ index. See the documentation of `TemplateArgument` for how certain C++
+ template parameter kinds are mapped to `TemplateArgument` values.
+ * Objective-C: Always returns `eTemplateArgumentKindNull`.
+ ") GetTemplateArgumentKind;
lldb::TemplateArgumentKind
GetTemplateArgumentKind (uint32_t idx);
+ %feature("docstring",
+ "Returns the return type if this type represents a function.
+
+ Returns an invalid `SBType` if this type is not a function type or invalid.
+
+ Language-specific behaviour:
+
+ * C: For functions return the return type. Returns an invalid `SBType` if
+ this type is a function pointer type.
+ * C++: Same as in C for functions and instantiated template functions.
+ Member functions are also considered functions. For functions that have
+ their return type specified by a placeholder type specifier (``auto``)
+ this returns the deduced return type.
+ * Objective-C: Same as in C for functions. For Objective-C methods this
+ returns the return type of the method.
+ ") GetFunctionReturnType;
lldb::SBType
GetFunctionReturnType ();
+ %feature("docstring",
+ "Returns the list of argument types if this type represents a function.
+
+ Returns an invalid `SBType` if this type is not a function type or invalid.
+
+ Language-specific behaviour:
+
+ * C: For functions return the types of each parameter. Returns an invalid
+ `SBType` if this type is a function pointer. For variadic functions this
+ just returns the list of parameters before the variadic arguments.
+ * C++: Same as in C for functions and instantiated template functions.
+ Member functions are also considered functions.
+ * Objective-C: Always returns an invalid SBType for Objective-C methods.
+ ") GetFunctionArgumentTypes;
lldb::SBTypeList
GetFunctionArgumentTypes ();
+ %feature("docstring",
+ "Returns the number of member functions of this type.
+
+ Returns ``0`` if an error occurred or this type is invalid.
+
+ Language-specific behaviour:
+
+ * C: Always returns ``0``.
+ * C++: If this type represents a struct/class, then the number of
+ member functions (static and non-static) is returned. The count includes
+ constructors and destructors (both explicit and implicit). Member
+ functions of base classes are not included in the count.
+ * Objective-C: If this type represents a struct/class, then the
+ number of methods is returned. Methods in categories or super classes
+ are not counted.
+ ") GetNumberOfMemberFunctions;
uint32_t
GetNumberOfMemberFunctions ();
+ %feature("docstring",
+ "Returns the member function of this type with the given index.
+
+ Returns an invalid `SBTypeMemberFunction` if the index is invalid or this
+ type is invalid.
+
+ Language-specific behaviour:
+
+ * C: Always returns an invalid `SBTypeMemberFunction`.
+ * C++: Returns the member function or constructor/destructor with the given
+ index.
+ * Objective-C: Returns the method with the given index.
+
+ See `GetNumberOfMemberFunctions` for what functions can be queried by this
+ function.
+ ") GetMemberFunctionAtIndex;
lldb::SBTypeMemberFunction
GetMemberFunctionAtIndex (uint32_t idx);
bool
IsTypeComplete ();
+ %feature("docstring",
+ "Returns the `TypeFlags` values for this type.
+
+ See the respective `TypeFlags` values for what values can be set. Returns an
+ integer in which each `TypeFlags` value is represented by a bit. Specific
+ flags can be checked via Python's bitwise operators. For example, the
+ `eTypeIsInteger` flag can be checked like this:
+
+ ``(an_sb_type.GetTypeFlags() & lldb.eTypeIsInteger) != 0``
+
+ If this type is invalid this returns ``0``.
+
+ See the
diff erent values for `TypeFlags` for the language-specific meanings
+ of each `TypeFlags` value.
+ ") GetTypeFlags;
uint32_t
GetTypeFlags ();
More information about the lldb-commits
mailing list