dissect.cstruct.types

Submodules

• dissect.cstruct.types.base
• dissect.cstruct.types.char
• dissect.cstruct.types.enum
• dissect.cstruct.types.flag
• dissect.cstruct.types.int
• dissect.cstruct.types.leb128
• dissect.cstruct.types.packed
• dissect.cstruct.types.pointer
• dissect.cstruct.types.structure
• dissect.cstruct.types.void
• dissect.cstruct.types.wchar

Package Contents

Classes

Array	Built-in mutable sequence.
BaseArray	Implements a fixed or dynamically sized array type.
BaseType	Base class for cstruct type classes.
MetaType	Base metaclass for cstruct type classes.
Char	Character type for reading and writing bytes.
CharArray	Character array type for reading and writing byte strings.
Enum	Enum type supercharged with cstruct functionality.
Flag	Flag type supercharged with cstruct functionality.
Int	Integer type that can span an arbitrary amount of bytes.
LEB128	Variable-length code compression to store an arbitrarily large integer in a small number of bytes.
Packed	Packed type for Python struct (un)packing.
Pointer	Pointer to some other type.
Field	Structure field.
Structure	Base class for cstruct structure type classes.
Union	Base class for cstruct union type classes.
Void	Void type.
VoidArray	Array type representing void elements, primarily used for no-op reading and writing operations.
Wchar	Wide-character type for reading and writing UTF-16 characters.
WcharArray	Wide-character array type for reading and writing UTF-16 strings.

class dissect.cstruct.types.Array

Bases: list[T], BaseArray

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

class dissect.cstruct.types.BaseArray

Bases: BaseType

Implements a fixed or dynamically sized array type.

Example

When using the default C-style parser, the following syntax is supported:

x[3] -> 3 -> static length. x[] -> None -> null-terminated. x[expr] -> expr -> dynamic length.

type: ClassVar[BaseArray.type[BaseType]]

num_entries: ClassVar[int | dissect.cstruct.expression.Expression | None]

null_terminated: ClassVar[bool]

classmethod __default__() → BaseType

class dissect.cstruct.types.BaseType

Base class for cstruct type classes.

dumps

write

__len__() → int

Return the byte size of the type.

class dissect.cstruct.types.MetaType

Bases: type

Base metaclass for cstruct type classes.

cs: dissect.cstruct.cstruct.cstruct

The cstruct instance this type class belongs to.

size: int | None

The size of the type in bytes. Can be None for dynamic sized types.

dynamic: bool

Whether or not the type is dynamically sized.

alignment: int | None

The alignment of the type in bytes. A value of None will be treated as 1-byte aligned.

ArrayType: type[BaseArray] = 'Array'

The array type for this type class.

__call__(*args, **kwargs) → typing_extensions.Self

Adds support for TypeClass(bytes | file-like object) parsing syntax.

__getitem__(num_entries: int | dissect.cstruct.expression.Expression | None) → type[BaseArray]

Create a new array with the given number of entries.

__bool__() → bool

Type class is always truthy.

__len__() → int

Return the byte size of the type.

__default__() → typing_extensions.Self

Return the default value of this type.

reads(data: bytes | memoryview | bytearray) → typing_extensions.Self

Parse the given data from a bytes-like object.

Parameters:

data – Bytes-like object to parse.

Returns:

The parsed value of this type.

read(obj: BinaryIO | bytes | memoryview | bytearray) → typing_extensions.Self

Parse the given data.

Parameters:

obj – Data to parse. Can be a bytes-like object or a file-like object.

Returns:

The parsed value of this type.

write(stream: BinaryIO, value: Any) → int

Write a value to a writable file-like object.

Parameters:

• stream – File-like objects that supports writing.

• value – Value to write.

Returns:

The amount of bytes written.

dumps(value: Any) → bytes

Dump a value to a byte string.

Parameters:

value – Value to dump.

Returns:

The raw bytes of this type.

class dissect.cstruct.types.Char

Bases: bytes, dissect.cstruct.types.base.BaseType

Character type for reading and writing bytes.

ArrayType

classmethod __default__() → typing_extensions.Self

class dissect.cstruct.types.CharArray

Bases: bytes, dissect.cstruct.types.base.BaseArray

Character array type for reading and writing byte strings.

classmethod __default__() → typing_extensions.Self

class dissect.cstruct.types.Enum

Bases: dissect.cstruct.types.base.BaseType, enum.IntEnum

Enum type supercharged with cstruct functionality.

Enums are (mostly) compatible with the Python 3 standard library IntEnum with some notable differences:

• Duplicate members are their own unique member instead of being an alias

• Non-existing values are allowed and handled similarly to IntFlag: <Enum: 0>

• Enum members are only considered equal if the enum class is the same

Enums can be made using any integer type.

Example

When using the default C-style parser, the following syntax is supported:

enum <name> [: <type>] {
    <values>
};

For example, an enum that has A=1, B=5 and C=6 could be written like so:

enum Test : uint16 {
    A, B=5, C
};

__repr__() → str

Return repr(self).

__eq__(other: int | Enum) → bool

Return self==value.

__ne__(value: int | Enum) → bool

Return self!=value.

__hash__() → int

Return hash(self).

class dissect.cstruct.types.Flag

Bases: dissect.cstruct.types.base.BaseType, enum.IntFlag

Flag type supercharged with cstruct functionality.

Flags are (mostly) compatible with the Python 3 standard library IntFlag with some notable differences:

• Flag members are only considered equal if the flag class is the same

Flags can be made using any integer type.

Example

When using the default C-style parser, the following syntax is supported:

flag <name> [: <type>] {
    <values>
};

For example, a flag that has A=1, B=4 and C=8 could be written like so:

flag Test : uint16 {
    A, B=4, C
};

__repr__() → str

Return repr(self).

__str__() → str

Return str(self).

__eq__(other: int | Flag) → bool

Return self==value.

__ne__(value: int | Flag) → bool

Return self!=value.

__hash__() → int

Return hash(self).

class dissect.cstruct.types.Int

Bases: int, dissect.cstruct.types.base.BaseType

Integer type that can span an arbitrary amount of bytes.

signed: bool

class dissect.cstruct.types.LEB128

Bases: int, dissect.cstruct.types.base.BaseType

Variable-length code compression to store an arbitrarily large integer in a small number of bytes.

See https://en.wikipedia.org/wiki/LEB128 for more information and an explanation of the algorithm.

signed: bool

class dissect.cstruct.types.Packed

Bases: dissect.cstruct.types.base.BaseType, Generic[T]

Packed type for Python struct (un)packing.

packchar: str

class dissect.cstruct.types.Pointer

Bases: int, dissect.cstruct.types.base.BaseType, Generic[T]

Pointer to some other type.

type: Pointer.type[T]

__repr__() → str

Return repr(self).

__str__() → str

Return str(self).

__getattr__(attr: str) → Any

__add__(other: int) → typing_extensions.Self

Return self+value.

__sub__(other: int) → typing_extensions.Self

Return self-value.

__mul__(other: int) → typing_extensions.Self

Return self*value.

__floordiv__(other: int) → typing_extensions.Self

Return self//value.

__mod__(other: int) → typing_extensions.Self

Return self%value.

__pow__(other: int) → typing_extensions.Self

Return pow(self, value, mod).

__lshift__(other: int) → typing_extensions.Self

Return self<<value.

__rshift__(other: int) → typing_extensions.Self

Return self>>value.

__and__(other: int) → typing_extensions.Self

Return self&value.

__xor__(other: int) → typing_extensions.Self

Return self^value.

__or__(other: int) → typing_extensions.Self

Return self|value.

classmethod __default__() → typing_extensions.Self

dereference() → T

class dissect.cstruct.types.Field(name: str | None, type_: type[dissect.cstruct.types.base.BaseType], bits: int | None = None, offset: int | None = None)

Structure field.

name

type

bits = None

offset = None

alignment

__repr__() → str

class dissect.cstruct.types.Structure

Bases: dissect.cstruct.types.base.BaseType

Base class for cstruct structure type classes.

Note that setting attributes which do not correspond to a field in the structure results in undefined behavior. For performance reasons, the structure does not check if the field exists when writing to an attribute.

__dynamic_sizes__: dict[str, int]

__len__() → int

Return the byte size of the type.

__bytes__() → bytes

__getitem__(item: str) → Any

__repr__() → str

property __values__: collections.abc.MutableMapping[str, Any]

property __sizes__: collections.abc.Mapping[str, int | None]

class dissect.cstruct.types.Union

Bases: Structure

Base class for cstruct union type classes.

__eq__(other: object) → bool

__setattr__(attr: str, value: Any) → None

class dissect.cstruct.types.Void

Bases: dissect.cstruct.types.base.BaseType

Void type.

ArrayType

__bool__() → bool

__eq__(value: object) → bool

class dissect.cstruct.types.VoidArray

Bases: list, dissect.cstruct.types.base.BaseArray

Array type representing void elements, primarily used for no-op reading and writing operations.

classmethod __default__() → typing_extensions.Self

class dissect.cstruct.types.Wchar

Bases: str, dissect.cstruct.types.base.BaseType

Wide-character type for reading and writing UTF-16 characters.

ArrayType

__slots__ = ()

__encoding_map__: ClassVar[dict[str, str]]

classmethod __default__() → Wchar

class dissect.cstruct.types.WcharArray

Bases: str, dissect.cstruct.types.base.BaseArray

Wide-character array type for reading and writing UTF-16 strings.

__slots__ = ()

classmethod __default__() → WcharArray