diff --git a/_drgn.pyi b/_drgn.pyi index 8c43c41b..3781d98a 100644 --- a/_drgn.pyi +++ b/_drgn.pyi @@ -1203,6 +1203,9 @@ class Object: """ Implement ``self.name``. + This corresponds to both the member access (``.``) and member access + through pointer (``->``) operators in C. + If *name* is an attribute of the :class:`Object` class, then this returns that attribute. Otherwise, it is equivalent to :meth:`member_()`. @@ -1217,8 +1220,16 @@ class Object: """ Implement ``self[idx]``. Get the array element at the given index. - >>> print(prog['init_task'].comm[0]) - (char)115 + >>> print(prog['init_task'].comm[1]) + (char)119 + + ``[0]`` is also the equivalent of the pointer dereference (``*``) + operator in C: + + >>> ptr_to_ptr + *(void **)0xffff9b86801e2968 = 0xffff9b86801e2460 + >>> print(ptr_to_ptr[0]) + (void *)0xffff9b86801e2460 This is only valid for pointers and arrays. @@ -1280,11 +1291,13 @@ class Object: """ Get a member of this object. - This is valid for structures, unions, and pointers to either. + This is valid for structures, unions, classes, and pointers to any of + those. If the object is a pointer, it is automatically dereferenced + first. - Normally the dot operator (``.``) can be used to accomplish the same - thing, but this method can be used if there is a name conflict with an - Object member or method. + Normally the dot operator (:meth:`. <__getattribute__>`) can be used to + accomplish the same thing, but this method can be used if there is a + name conflict with an ``Object`` member or method. :param name: Name of the member. :raises TypeError: if this object is not a structure, union, class, or diff --git a/docs/user_guide.rst b/docs/user_guide.rst index a8e23383..9f8561be 100644 --- a/docs/user_guide.rst +++ b/docs/user_guide.rst @@ -74,6 +74,16 @@ compared:: >>> prog['init_task'].nsproxy.mnt_ns.pending_mounts > 0 False +Python doesn't have all of the operators that C or C++ do, so some +substitutions are necessary: + +* Instead of ``*ptr``, dereference a pointer with :meth:`ptr[0] + `. +* Instead of ``ptr->member``, access a member through a pointer with + :meth:`ptr.member `. +* Instead of ``&var``, get the address of a variable with + :meth:`var.address_of_() `. + A common use case is converting a ``drgn.Object`` to a Python value so it can be used by a standard Python library. There are a few ways to do this: