Helpers¶
The drgn.helpers
package contains subpackages which provide helpers for
working with particular types of programs. Currently, there are only helpers
for the Linux kernel. In the future, there may be helpers for, e.g., glibc and
libstdc++.
Parameter types and return types are drgn.Object
unless noted
otherwise. Many helpers include a C function signature indicating the expected
object types.
Generic Helpers¶
The top-level drgn.helpers
module provides generic helpers that may be
useful for scripts or for implementing other helpers.
-
drgn.helpers.
escape_ascii_character
(c, escape_single_quote=False, escape_double_quote=False, escape_backslash=False)¶ Format an ASCII byte value as a character, possibly escaping it. Non-printable characters are always escaped. Non-printable characters other than
\0
,\a
,\b
,\t
,\n
,\v
,\f
, and\r
are escaped in hexadecimal format (e.g.,\x7f
). By default, printable characters are never escaped.
-
drgn.helpers.
escape_ascii_string
(buffer, escape_single_quote=False, escape_double_quote=False, escape_backslash=False)¶ Escape an iterable of ASCII byte values (e.g.,
bytes
orbytearray
). Seeescape_ascii_character()
.
-
drgn.helpers.
enum_type_to_class
(type, name, exclude=(), prefix='')¶ Get an
enum.IntEnum
class from an enumerateddrgn.Type
.- Parameters
- Return type
Linux Kernel¶
The drgn.helpers.linux
package contains several modules for working with
data structures and subsystems in the Linux kernel. The helpers are available
from the individual modules in which they are defined and from this top-level
package. E.g., the following are both valid:
>>> from drgn.helpers.linux.list import list_for_each_entry
>>> from drgn.helpers.linux import list_for_each_entry
Iterator macros (for_each_foo
) are a common idiom in the Linux kernel. The
equivalent drgn helpers are implemented as Python generators. For example, the following code in C:
list_for_each(pos, head)
do_something_with(pos);
Translates to the following code in Python:
for pos in list_for_each(head):
do_something_with(pos)
Block Layer¶
The drgn.helpers.linux.block
module provides helpers for working with the
Linux block layer, including disks (struct gendisk
) and partitions.
Since Linux v5.11, partitions are represented by struct block_device
.
Before that, they were represented by struct hd_struct
.
-
drgn.helpers.linux.block.
disk_devt
(disk)¶ Get a disk’s device number.
- Parameters
disk (
drgn.Object
) –struct gendisk *
- Returns
dev_t
- Return type
-
drgn.helpers.linux.block.
disk_name
(disk)¶ Get the name of a disk (e.g.,
sda
).- Parameters
disk (
drgn.Object
) –struct gendisk *
- Return type
-
drgn.helpers.linux.block.
for_each_disk
(prog)¶ Iterate over all disks in the system.
- Returns
Iterator of
struct gendisk *
objects.- Return type
-
drgn.helpers.linux.block.
part_devt
(part)¶ Get a partition’s device number.
- Parameters
part (
drgn.Object
) –struct block_device *
orstruct hd_struct *
depending on the kernel version.- Returns
dev_t
- Return type
-
drgn.helpers.linux.block.
part_name
(part)¶ Get the name of a partition (e.g.,
sda1
).- Parameters
part (
drgn.Object
) –struct block_device *
orstruct hd_struct *
depending on the kernel version.- Return type
-
drgn.helpers.linux.block.
for_each_partition
(prog)¶ Iterate over all partitions in the system.
- Returns
Iterator of
struct block_device *
orstruct hd_struct *
objects depending on the kernel version.- Return type
Boot¶
The drgn.helpers.linux.boot
module provides helpers for inspecting the
Linux kernel boot configuration.
-
drgn.helpers.linux.boot.
kaslr_offset
(prog)¶ Get the kernel address space layout randomization offset (zero if it is disabled).
- Return type
BPF¶
The drgn.helpers.linux.bpf
module provides helpers for working with BPF
interface in include/linux/bpf.h, include/linux/bpf-cgroup.h,
etc.
-
drgn.helpers.linux.bpf.
bpf_map_for_each
(prog)¶ Iterate over all BPF maps.
- Returns
Iterator of
struct bpf_map *
objects.- Return type
-
drgn.helpers.linux.bpf.
bpf_prog_for_each
(prog)¶ Iterate over all BPF programs.
- Returns
Iterator of
struct bpf_prog *
objects.- Return type
-
drgn.helpers.linux.bpf.
cgroup_bpf_prog_for_each
(cgrp, bpf_attach_type)¶ Iterate over all cgroup BPF programs of the given attach type attached to the given cgroup.
- Parameters
cgrp (
drgn.Object
) –struct cgroup *
bpf_attach_type (
drgn.IntegerLike
) –enum bpf_attach_type
- Returns
Iterator of
struct bpf_prog *
objects.- Return type
-
drgn.helpers.linux.bpf.
cgroup_bpf_prog_for_each_effective
(cgrp, bpf_attach_type)¶ Iterate over all effective cgroup BPF programs of the given attach type for the given cgroup.
- Parameters
cgrp (
drgn.Object
) –struct cgroup *
bpf_attach_type (
drgn.IntegerLike
) –enum bpf_attach_type
- Returns
Iterator of
struct bpf_prog *
objects.- Return type
Cgroup¶
The drgn.helpers.linux.cgroup
module provides helpers for working with the
cgroup interface in include/linux/cgroup.h. Only cgroup v2 is
supported.
-
drgn.helpers.linux.cgroup.
sock_cgroup_ptr
(skcd)¶ Get the cgroup for a socket from the given
struct sock_cgroup_data *
(usually fromstruct sock::sk_cgrp_data
).- Parameters
skcd (
drgn.Object
) –struct sock_cgroup_data *
- Returns
struct cgroup *
- Return type
-
drgn.helpers.linux.cgroup.
cgroup_parent
(cgrp)¶ Return the parent cgroup of the given cgroup if it exists,
NULL
otherwise.- Parameters
cgrp (
drgn.Object
) –struct cgroup *
- Returns
struct cgroup *
- Return type
-
drgn.helpers.linux.cgroup.
cgroup_name
(cgrp)¶ Get the name of the given cgroup.
- Parameters
cgrp (
drgn.Object
) –struct cgroup *
- Return type
-
drgn.helpers.linux.cgroup.
cgroup_path
(cgrp)¶ Get the full path of the given cgroup.
- Parameters
cgrp (
drgn.Object
) –struct cgroup *
- Return type
-
drgn.helpers.linux.cgroup.
css_next_child
(pos, parent)¶ Get the next child (or
NULL
if there is none) of the given parent starting from the given position (NULL
to initiate traversal).- Parameters
pos (
drgn.Object
) –struct cgroup_subsys_state *
parent (
drgn.Object
) –struct cgroup_subsys_state *
- Returns
struct cgroup_subsys_state *
- Return type
-
drgn.helpers.linux.cgroup.
css_next_descendant_pre
(pos, root)¶ Get the next pre-order descendant (or
NULL
if there is none) of the given css root starting from the given position (NULL
to initiate traversal).- Parameters
pos (
drgn.Object
) –struct cgroup_subsys_state *
root (
drgn.Object
) –struct cgroup_subsys_state *
- Returns
struct cgroup_subsys_state *
- Return type
-
drgn.helpers.linux.cgroup.
css_for_each_child
(css)¶ Iterate through children of the given css.
- Parameters
css (
drgn.Object
) –struct cgroup_subsys_state *
- Returns
Iterator of
struct cgroup_subsys_state *
objects.- Return type
-
drgn.helpers.linux.cgroup.
css_for_each_descendant_pre
(css)¶ Iterate through the given css’s descendants in pre-order.
- Parameters
css (
drgn.Object
) –struct cgroup_subsys_state *
- Returns
Iterator of
struct cgroup_subsys_state *
objects.- Return type
CPU Masks¶
The drgn.helpers.linux.cpumask
module provides helpers for working with CPU
masks from include/linux/cpumask.h.
-
drgn.helpers.linux.cpumask.
for_each_cpu
(mask)¶ Iterate over all of the CPUs in the given mask.
- Parameters
mask (
drgn.Object
) –struct cpumask
- Return type
-
drgn.helpers.linux.cpumask.
for_each_online_cpu
(prog)¶ Iterate over all online CPUs.
-
drgn.helpers.linux.cpumask.
for_each_possible_cpu
(prog)¶ Iterate over all possible CPUs.
Devices¶
The drgn.helpers.linux.device
module provides helpers for working with
Linux devices, including the kernel encoding of dev_t
.
-
drgn.helpers.linux.device.
MAJOR
(dev)¶ Return the major ID of a kernel
dev_t
.- Parameters
dev (
drgn.IntegerLike
) –dev_t
object or :class:int
.- Return type
-
drgn.helpers.linux.device.
MINOR
(dev)¶ Return the minor ID of a kernel
dev_t
.- Parameters
dev (
drgn.IntegerLike
) –dev_t
object or :class:int
.- Return type
-
drgn.helpers.linux.device.
MKDEV
(major, minor)¶ Return a kernel
dev_t
from the major and minor IDs.- Parameters
major (
drgn.IntegerLike
) – Device major ID.minor (
drgn.IntegerLike
) – Device minor ID.
- Return type
Virtual Filesystem Layer¶
The drgn.helpers.linux.fs
module provides helpers for working with the
Linux virtual filesystem (VFS) layer, including mounts, dentries, and inodes.
-
drgn.helpers.linux.fs.
path_lookup
(prog_or_root, path, allow_negative=False)¶ Look up the given path name.
- Parameters
prog_or_root –
struct path *
object to use as root directory, orProgram
to use the initial root filesystem.path – Path to lookup.
allow_negative – Whether to allow returning a negative dentry (i.e., a dentry for a non-existent path).
- Returns
struct path
- Raises
Exception – if the dentry is negative and
allow_negative
isFalse
, or if the path is not present in the dcache. The latter does not necessarily mean that the path does not exist; it may be uncached. On a live system, you can make the kernel cache the path by accessing it (e.g., withopen()
oros.stat()
):
>>> path_lookup(prog, '/usr/include/stdlib.h') ... Exception: could not find '/usr/include/stdlib.h' in dcache >>> open('/usr/include/stdlib.h').close() >>> path_lookup(prog, '/usr/include/stdlib.h') (struct path){ .mnt = (struct vfsmount *)0xffff8b70413cdca0, .dentry = (struct dentry *)0xffff8b702ac2c480, }
- Return type
-
drgn.helpers.linux.fs.
d_path
(path)¶ Return the full path of a dentry given a
struct path
.- Parameters
path (
drgn.Object
) –struct path
orstruct path *
- Return type
-
drgn.helpers.linux.fs.
d_path
(vfsmnt, dentry) Return the full path of a dentry given a mount and dentry.
- Parameters
vfsmnt (
drgn.Object
) –struct vfsmount *
dentry (
drgn.Object
) –struct dentry *
- Return type
-
drgn.helpers.linux.fs.
dentry_path
(dentry)¶ Return the path of a dentry from the root of its filesystem.
- Parameters
dentry (
drgn.Object
) –struct dentry *
- Return type
-
drgn.helpers.linux.fs.
inode_path
(inode)¶ Return any path of an inode from the root of its filesystem.
- Parameters
inode (
drgn.Object
) –struct inode *
- Returns
Path, or
None
if the inode has no aliases.- Return type
-
drgn.helpers.linux.fs.
inode_paths
(inode)¶ Return an iterator over all of the paths of an inode from the root of its filesystem.
- Parameters
inode (
drgn.Object
) –struct inode *
- Return type
-
drgn.helpers.linux.fs.
mount_src
(mnt)¶ Get the source device name for a mount.
- Parameters
mnt (
drgn.Object
) –struct mount *
- Return type
-
drgn.helpers.linux.fs.
mount_dst
(mnt)¶ Get the path of a mount point.
- Parameters
mnt (
drgn.Object
) –struct mount *
- Return type
-
drgn.helpers.linux.fs.
mount_fstype
(mnt)¶ Get the filesystem type of a mount.
- Parameters
mnt (
drgn.Object
) –struct mount *
- Return type
-
drgn.helpers.linux.fs.
for_each_mount
(prog_or_ns, src=None, dst=None, fstype=None)¶ Iterate over all of the mounts in a given namespace.
- Parameters
prog_or_ns (
Union
[drgn.Program
,drgn.Object
]) –struct mnt_namespace *
to iterate over, orProgram
to iterate over initial mount namespace.src (
Optional
[drgn.Path
]) – Only include mounts with this source device name.dst (
Optional
[drgn.Path
]) – Only include mounts with this destination path.fstype (
Optional
[Union
[str
,bytes
]]) – Only include mounts with this filesystem type.
- Returns
Iterator of
struct mount *
objects.- Return type
-
drgn.helpers.linux.fs.
print_mounts
(prog_or_ns, src=None, dst=None, fstype=None)¶ Print the mount table of a given namespace. The arguments are the same as
for_each_mount()
. The output format is similar to/proc/mounts
but prints the value of eachstruct mount *
.- Return type
-
drgn.helpers.linux.fs.
fget
(task, fd)¶ Return the kernel file descriptor of the fd of a given task.
- Parameters
task (
drgn.Object
) –struct task_struct *
fd (
drgn.IntegerLike
) – File descriptor.
- Returns
struct file *
- Return type
-
drgn.helpers.linux.fs.
for_each_file
(task)¶ Iterate over all of the files open in a given task.
- Parameters
task (
drgn.Object
) –struct task_struct *
- Returns
Iterator of (fd,
struct file *
) tuples.- Return type
-
drgn.helpers.linux.fs.
print_files
(task)¶ Print the open files of a given task.
- Parameters
task (
drgn.Object
) –struct task_struct *
- Return type
IDR¶
The drgn.helpers.linux.idr
module provides helpers for working with the IDR
data structure in include/linux/idr.h. An IDR provides a mapping from
an ID to a pointer. This currently only supports Linux v4.11+; before this,
IDRs were not based on radix trees.
-
drgn.helpers.linux.idr.
idr_find
(idr, id)¶ Look up the entry with the given ID in an IDR.
- Parameters
idr (
drgn.Object
) –struct idr *
id (
drgn.IntegerLike
) – Entry ID.
- Returns
void *
found entry, orNULL
if not found.- Return type
-
drgn.helpers.linux.idr.
idr_for_each
(idr)¶ Iterate over all of the entries in an IDR.
- Parameters
idr (
drgn.Object
) –struct idr *
- Returns
Iterator of (index,
void *
) tuples.- Return type
Kconfig¶
The drgn.helpers.linux.kconfig
module provides helpers for reading the
Linux kernel build configuration.
-
drgn.helpers.linux.kconfig.
get_kconfig
(prog)¶ Get the kernel build configuration as a mapping from the option name to the value.
>>> get_kconfig(prog)['CONFIG_SMP'] 'y' >>> get_kconfig(prog)['CONFIG_HZ'] '300'
This is only supported if the kernel was compiled with
CONFIG_IKCONFIG
. Note that most Linux distributions do not enable this option.
Kernfs¶
The drgn.helpers.linux.kernfs
module provides helpers for working with the
kernfs pseudo filesystem interface in include/linux/kernfs.h.
-
drgn.helpers.linux.kernfs.
kernfs_name
(kn)¶ Get the name of the given kernfs node.
- Parameters
kn (
drgn.Object
) –struct kernfs_node *
- Return type
-
drgn.helpers.linux.kernfs.
kernfs_path
(kn)¶ Get full path of the given kernfs node.
- Parameters
kn (
drgn.Object
) –struct kernfs_node *
- Return type
Linked Lists¶
The drgn.helpers.linux.list
module provides helpers for working with the
doubly-linked list implementations (struct list_head
and struct
hlist_head
) in include/linux/list.h.
-
drgn.helpers.linux.list.
list_empty
(head)¶ Return whether a list is empty.
- Parameters
head (
drgn.Object
) –struct list_head *
- Return type
-
drgn.helpers.linux.list.
list_is_singular
(head)¶ Return whether a list has only one element.
- Parameters
head (
drgn.Object
) –struct list_head *
- Return type
-
drgn.helpers.linux.list.
list_first_entry
(head, type, member)¶ Return the first entry in a list.
The list is assumed to be non-empty.
See also
list_first_entry_or_null()
.- Parameters
head (
drgn.Object
) –struct list_head *
member (
str
) – Name of list node member in entry type.
- Returns
type *
- Return type
-
drgn.helpers.linux.list.
list_first_entry_or_null
(head, type, member)¶ Return the first entry in a list or
NULL
if the list is empty.See also
list_first_entry()
.- Parameters
head (
drgn.Object
) –struct list_head *
member (
str
) – Name of list node member in entry type.
- Returns
type *
- Return type
-
drgn.helpers.linux.list.
list_last_entry
(head, type, member)¶ Return the last entry in a list.
The list is assumed to be non-empty.
- Parameters
head (
drgn.Object
) –struct list_head *
member (
str
) – Name of list node member in entry type.
- Returns
type *
- Return type
-
drgn.helpers.linux.list.
list_next_entry
(pos, member)¶ Return the next entry in a list.
- Parameters
pos (
drgn.Object
) –type*
member (
str
) – Name of list node member in entry type.
- Returns
type *
- Return type
-
drgn.helpers.linux.list.
list_prev_entry
(pos, member)¶ Return the previous entry in a list.
- Parameters
pos (
drgn.Object
) –type*
member (
str
) – Name of list node member in entry type.
- Returns
type *
- Return type
-
drgn.helpers.linux.list.
list_for_each
(head)¶ Iterate over all of the nodes in a list.
- Parameters
head (
drgn.Object
) –struct list_head *
- Returns
Iterator of
struct list_head *
objects.- Return type
-
drgn.helpers.linux.list.
list_for_each_reverse
(head)¶ Iterate over all of the nodes in a list in reverse order.
- Parameters
head (
drgn.Object
) –struct list_head *
- Returns
Iterator of
struct list_head *
objects.- Return type
-
drgn.helpers.linux.list.
list_for_each_entry
(type, head, member)¶ Iterate over all of the entries in a list.
- Parameters
type (
str
) – Entry type.head (
drgn.Object
) –struct list_head *
member (
str
) – Name of list node member in entry type.
- Returns
Iterator of
type *
objects.- Return type
-
drgn.helpers.linux.list.
list_for_each_entry_reverse
(type, head, member)¶ Iterate over all of the entries in a list in reverse order.
- Parameters
type (
str
) – Entry type.head (
drgn.Object
) –struct list_head *
member (
str
) – Name of list node member in entry type.
- Returns
Iterator of
type *
objects.- Return type
-
drgn.helpers.linux.list.
hlist_empty
(head)¶ Return whether a hash list is empty.
- Parameters
head (
drgn.Object
) –struct hlist_head *
- Return type
-
drgn.helpers.linux.list.
hlist_for_each
(head)¶ Iterate over all of the nodes in a hash list.
- Parameters
head (
drgn.Object
) –struct hlist_head *
- Returns
Iterator of
struct hlist_node *
objects.- Return type
-
drgn.helpers.linux.list.
hlist_for_each_entry
(type, head, member)¶ Iterate over all of the entries in a hash list.
- Parameters
type (
str
) – Entry type.head (
drgn.Object
) –struct hlist_head *
member (
str
) – Name of list node member in entry type.
- Returns
Iterator of
type *
objects.- Return type
Nulls Lists¶
The drgn.helpers.linux.list_nulls
module provides helpers for working with
the special version of lists (struct hlist_nulls_head
and struct
hlist_nulls_node
) in include/linux/list_nulls.h where the end of
list is not a NULL
pointer, but a “nulls” marker.
-
drgn.helpers.linux.list_nulls.
is_a_nulls
(pos)¶ Return whether a a pointer is a nulls marker.
- Parameters
pos (
drgn.Object
) –struct hlist_nulls_node *
- Return type
-
drgn.helpers.linux.list_nulls.
hlist_nulls_empty
(head)¶ Return whether a nulls hash list is empty.
- Parameters
head (
drgn.Object
) –struct hlist_nulls_head *
- Return type
-
drgn.helpers.linux.list_nulls.
hlist_nulls_for_each_entry
(type, head, member)¶ Iterate over all the entries in a nulls hash list.
- Parameters
type (
str
) – Entry type.head (
drgn.Object
) –struct hlist_nulls_head *
member (
str
) – Name of list node member in entry type.
- Returns
Iterator of
type *
objects.- Return type
Memory Management¶
The drgn.helpers.linux.mm
module provides helpers for working with the
Linux memory management (MM) subsystem. Only x86-64 support is currently
implemented.
-
drgn.helpers.linux.mm.
for_each_page
(prog)¶ Iterate over all pages in the system.
- Returns
Iterator of
struct page *
objects.- Return type
-
drgn.helpers.linux.mm.
page_to_pfn
(page)¶ Get the page frame number (PFN) of a page.
- Parameters
page (
drgn.Object
) –struct page *
- Returns
unsigned long
- Return type
-
drgn.helpers.linux.mm.
pfn_to_page
(pfn)¶ Get the page with a page frame number (PFN) given as an
Object
.- Parameters
pfn (
drgn.Object
) –unsigned long
- Returns
struct page *
- Return type
-
drgn.helpers.linux.mm.
pfn_to_page
(prog, pfn) Get the page with a page frame number (PFN) given as a
Program
and an integer.- Parameters
pfn (
drgn.IntegerLike
) – Page frame number.- Returns
struct page *
- Return type
-
drgn.helpers.linux.mm.
virt_to_pfn
(addr)¶ Get the page frame number (PFN) of a directly mapped virtual address given as an
Object
.- Parameters
addr (
drgn.Object
) –void *
- Returns
unsigned long
- Return type
-
drgn.helpers.linux.mm.
virt_to_pfn
(prog, addr) Get the page frame number (PFN) of a directly mapped virtual address given as a
Program
and an integer.- Parameters
addr (
drgn.IntegerLike
) – Virtual address.- Returns
unsigned long
- Return type
-
drgn.helpers.linux.mm.
pfn_to_virt
(pfn)¶ Get the directly mapped virtual address of a page frame number (PFN) given as an
Object
.- Parameters
pfn (
drgn.Object
) –unsigned long
- Returns
void *
- Return type
-
drgn.helpers.linux.mm.
pfn_to_virt
(prog, pfn) Get the directly mapped virtual address of a page frame number (PFN) given as a
Program
and an integer.- Parameters
pfn (
drgn.IntegerLike
) – Page frame number.- Returns
void *
- Return type
-
drgn.helpers.linux.mm.
page_to_virt
(page)¶ Get the directly mapped virtual address of a page.
- Parameters
page (
drgn.Object
) –struct page *
- Returns
void *
- Return type
-
drgn.helpers.linux.mm.
virt_to_page
(addr)¶ Get the page containing a directly mapped virtual address given as an
Object
.- Parameters
addr (
drgn.Object
) –void *
- Returns
struct page *
- Return type
-
drgn.helpers.linux.mm.
virt_to_page
(prog, addr) Get the page containing a directly mapped virtual address given as a
Program
and an integer.- Parameters
addr (
drgn.IntegerLike
) – Virtual address.- Returns
struct page *
- Return type
-
drgn.helpers.linux.mm.
access_process_vm
(task, address, size)¶ Read memory from a task’s virtual address space.
>>> task = find_task(prog, 1490152) >>> access_process_vm(task, 0x7f8a62b56da0, 12) b'hello, world'
- Parameters
task (
drgn.Object
) –struct task_struct *
address (
drgn.IntegerLike
) – Starting address.size (
drgn.IntegerLike
) – Number of bytes to read.
- Return type
-
drgn.helpers.linux.mm.
access_remote_vm
(mm, address, size)¶ Read memory from a virtual address space. This is similar to
access_process_vm()
, but it takes astruct mm_struct *
instead of astruct task_struct *
.>>> task = find_task(prog, 1490152) >>> access_remote_vm(task.mm, 0x7f8a62b56da0, 12) b'hello, world'
- Parameters
mm (
drgn.Object
) –struct mm_struct *
address (
drgn.IntegerLike
) – Starting address.size (
drgn.IntegerLike
) – Number of bytes to read.
- Return type
-
drgn.helpers.linux.mm.
cmdline
(task)¶ Get the list of command line arguments of a task.
>>> cmdline(find_task(prog, 1495216)) [b'vim', b'drgn/helpers/linux/mm.py']
$ tr '\0' ' ' < /proc/1495216/cmdline vim drgn/helpers/linux/mm.py
- Parameters
task (
drgn.Object
) –struct task_struct *
- Return type
-
drgn.helpers.linux.mm.
environ
(task)¶ Get the list of environment variables of a task.
>>> environ(find_task(prog, 1497797)) [b'HOME=/root', b'PATH=/usr/local/sbin:/usr/local/bin:/usr/bin', b'LOGNAME=root']
$ tr '\0' '\n' < /proc/1497797/environ HOME=/root PATH=/usr/local/sbin:/usr/local/bin:/usr/bin LOGNAME=root
- Parameters
task (
drgn.Object
) –struct task_struct *
- Return type
Networking¶
The drgn.helpers.linux.net
module provides helpers for working with the
Linux kernel networking subsystem.
-
drgn.helpers.linux.net.
sk_fullsock
(sk)¶ Check whether a socket is a full socket, i.e., not a time-wait or request socket.
- Parameters
sk (
drgn.Object
) –struct sock *
- Return type
-
drgn.helpers.linux.net.
sk_nulls_for_each
(head)¶ Iterate over all the entries in a nulls hash list of sockets specified by
struct hlist_nulls_head
head.- Parameters
head (
drgn.Object
) –struct hlist_nulls_head *
- Returns
Iterator of
struct sock *
objects.- Return type
Per-CPU¶
The drgn.helpers.linux.percpu
module provides helpers for working with
per-CPU allocations from include/linux/percpu.h and per-CPU counters
from include/linux/percpu_counter.h.
-
drgn.helpers.linux.percpu.
per_cpu
(var, cpu)¶ Return the per-CPU variable for a given CPU.
>>> print(repr(prog["runqueues"])) Object(prog, 'struct rq', address=0x278c0) >>> per_cpu(prog["runqueues"], 6).curr.comm (char [16])"python3"
- Parameters
var (
drgn.Object
) – Per-CPU variable, i.e.,type __percpu
(not a pointer; useper_cpu_ptr()
for that).cpu (
drgn.IntegerLike
) – CPU number.
- Returns
type
object.- Return type
-
drgn.helpers.linux.percpu.
per_cpu_ptr
(ptr, cpu)¶ Return the per-CPU pointer for a given CPU.
>>> prog["init_net"].loopback_dev.pcpu_refcnt (int *)0x2c980 >>> per_cpu_ptr(prog["init_net"].loopback_dev.pcpu_refcnt, 7) *(int *)0xffff925e3ddec980 = 4
- Parameters
ptr (
drgn.Object
) – Per-CPU pointer, i.e.,type __percpu *
. For global variables, it’s usually easier to useper_cpu()
.cpu (
drgn.IntegerLike
) – CPU number.
- Returns
type *
object.- Return type
-
drgn.helpers.linux.percpu.
percpu_counter_sum
(fbc)¶ Return the sum of a per-CPU counter.
- Parameters
fbc (
drgn.Object
) –struct percpu_counter *
- Return type
Process IDS¶
The drgn.helpers.linux.pid
module provides helpers for looking up process
IDs and processes.
-
drgn.helpers.linux.pid.
find_pid
(prog_or_ns, pid)¶ Return the
struct pid *
for the given PID number.- Parameters
prog_or_ns (
Union
[drgn.Program
,drgn.Object
]) –struct pid_namespace *
object, orProgram
to use initial PID namespace.- Returns
struct pid *
- Return type
-
drgn.helpers.linux.pid.
find_task
(prog_or_ns, pid)¶ Return the task with the given PID.
- Parameters
prog_or_ns (
Union
[drgn.Program
,drgn.Object
]) –struct pid_namespace *
object, orProgram
to use initial PID namespace.- Returns
struct task_struct *
- Return type
-
drgn.helpers.linux.pid.
pid_task
(pid, pid_type)¶ Return the
struct task_struct *
containing the givenstruct pid *
of the given type.- Parameters
pid (
drgn.Object
) –struct pid *
pid_type (
drgn.IntegerLike
) –enum pid_type
- Returns
struct task_struct *
- Return type
-
drgn.helpers.linux.pid.
for_each_pid
(prog_or_ns)¶ Iterate over all PIDs in a namespace.
- Parameters
prog_or_ns (
Union
[drgn.Program
,drgn.Object
]) –struct pid_namespace *
to iterate over, orProgram
to iterate over initial PID namespace.- Returns
Iterator of
struct pid *
objects.- Return type
-
drgn.helpers.linux.pid.
for_each_task
(prog_or_ns)¶ Iterate over all of the tasks visible in a namespace.
- Parameters
prog_or_ns (
Union
[drgn.Program
,drgn.Object
]) –struct pid_namespace *
to iterate over, orProgram
to iterate over initial PID namespace.- Returns
Iterator of
struct task_struct *
objects.- Return type
Radix Trees¶
The drgn.helpers.linux.radixtree
module provides helpers for working with
radix trees from include/linux/radix-tree.h.
-
drgn.helpers.linux.radixtree.
radix_tree_lookup
(root, index)¶ Look up the entry at a given index in a radix tree.
- Parameters
root (
drgn.Object
) –struct radix_tree_root *
index (
drgn.IntegerLike
) – Entry index.
- Returns
void *
found entry, orNULL
if not found.- Return type
-
drgn.helpers.linux.radixtree.
radix_tree_for_each
(root)¶ Iterate over all of the entries in a radix tree.
- Parameters
root (
drgn.Object
) –struct radix_tree_root *
- Returns
Iterator of (index,
void *
) tuples.- Return type
Red-Black Trees¶
The drgn.helpers.linux.rbtree
module provides helpers for working with
red-black trees from include/linux/rbtree.h.
-
drgn.helpers.linux.rbtree.
RB_EMPTY_NODE
(node)¶ Return whether a red-black tree node is empty, i.e., not inserted in a tree.
- Parameters
node (
drgn.Object
) –struct rb_node *
- Return type
-
drgn.helpers.linux.rbtree.
rb_parent
(node)¶ Return the parent node of a red-black tree node.
- Parameters
node (
drgn.Object
) –struct rb_node *
- Returns
struct rb_node *
- Return type
-
drgn.helpers.linux.rbtree.
rb_first
(root)¶ Return the first node (in sort order) in a red-black tree, or
NULL
if the tree is empty.- Parameters
root (
drgn.Object
) –struct rb_root *
- Returns
struct rb_node *
- Return type
-
drgn.helpers.linux.rbtree.
rb_last
(root)¶ Return the last node (in sort order) in a red-black tree, or
NULL
if the tree is empty.- Parameters
root (
drgn.Object
) –struct rb_root *
- Returns
struct rb_node *
- Return type
-
drgn.helpers.linux.rbtree.
rb_next
(node)¶ Return the next node (in sort order) after a red-black node, or
NULL
if the node is the last node in the tree or is empty.- Parameters
node (
drgn.Object
) –struct rb_node *
- Returns
struct rb_node *
- Return type
-
drgn.helpers.linux.rbtree.
rb_prev
(node)¶ Return the previous node (in sort order) before a red-black node, or
NULL
if the node is the first node in the tree or is empty.- Parameters
node (
drgn.Object
) –struct rb_node *
- Returns
struct rb_node *
- Return type
-
drgn.helpers.linux.rbtree.
rbtree_inorder_for_each
(root)¶ Iterate over all of the nodes in a red-black tree, in sort order.
- Parameters
root (
drgn.Object
) –struct rb_root *
- Returns
Iterator of
struct rb_node *
objects.- Return type
-
drgn.helpers.linux.rbtree.
rbtree_inorder_for_each_entry
(type, root, member)¶ Iterate over all of the entries in a red-black tree in sorted order.
- Parameters
type (
str
) – Entry type.root (
drgn.Object
) –struct rb_root *
member (
str
) – Name of red-black node member in entry type.
- Returns
Iterator of
type *
objects.- Return type
-
drgn.helpers.linux.rbtree.
rb_find
(type, root, member, key, cmp)¶ Find an entry in a red-black tree given a key and a comparator function.
Note that this function does not have an analogue in the Linux kernel source code, as tree searches are all open-coded.
- Parameters
type (
str
) – Entry type.root (
drgn.Object
) –struct rb_root *
member (
str
) – Name of red-black node member in entry type.key (
KeyType
) – Key to find.cmp (
Callable
[[KeyType
,drgn.Object
],int
]) – Callback taking key and entry that returns < 0 if the key is less than the entry, > 0 if the key is greater than the entry, and 0 if the key matches the entry.
- Returns
type *
found entry, orNULL
if not found.- Return type
CPU Scheduler¶
The drgn.helpers.linux.sched
module provides helpers for working with the
Linux CPU scheduler.
-
drgn.helpers.linux.sched.
task_state_to_char
(task)¶ Get the state of the task as a character (e.g.,
'R'
for running). See ps(1) for a description of the process state codes.- Parameters
task (
drgn.Object
) –struct task_struct *
- Return type
TCP¶
The drgn.helpers.linux.tcp
module provides helpers for working with the TCP
protocol in the Linux kernel.
-
drgn.helpers.linux.tcp.
sk_tcpstate
(sk)¶ Return the TCP protocol state of a socket.
- Parameters
sk (
drgn.Object
) –struct sock *
- Returns
TCP state enum value.
- Return type
Users¶
The drgn.helpers.linux.user
module provides helpers for working with users
in the Linux kernel.
-
drgn.helpers.linux.user.
find_user
(prog, uid)¶ Return the user structure with the given UID.
- Parameters
uid (
Union
[drgn.Object
,drgn.IntegerLike
]) –kuid_t
object or integer.- Returns
struct user_state *
- Return type
-
drgn.helpers.linux.user.
for_each_user
(prog)¶ Iterate over all users in the system.
- Returns
Iterator of
struct user_struct *
objects.- Return type