/* struct module -- pack values into and (out of) bytes objects */
/* New version supporting byte order, alignment and size options,
character strings, and unsigned numbers */
#define PY_SSIZE_T_CLEAN
#include "Python.h"
#include "structmember.h"
#include
/*[clinic input]
class Struct "PyStructObject *" "&PyStructType"
[clinic start generated code]*/
/*[clinic end generated code: output=da39a3ee5e6b4b0d input=9b032058a83ed7c3]*/
static PyTypeObject PyStructType;
/* The translation function for each format character is table driven */
typedef struct _formatdef {
char format;
Py_ssize_t size;
Py_ssize_t alignment;
PyObject* (*unpack)(const char *,
const struct _formatdef *);
int (*pack)(char *, PyObject *,
const struct _formatdef *);
} formatdef;
typedef struct _formatcode {
const struct _formatdef *fmtdef;
Py_ssize_t offset;
Py_ssize_t size;
Py_ssize_t repeat;
} formatcode;
/* Struct object interface */
typedef struct {
PyObject_HEAD
Py_ssize_t s_size;
Py_ssize_t s_len;
formatcode *s_codes;
PyObject *s_format;
PyObject *weakreflist; /* List of weak references */
} PyStructObject;
#define PyStruct_Check(op) PyObject_TypeCheck(op, &PyStructType)
#define PyStruct_CheckExact(op) Py_TYPE_IS((op), &PyStructType)
/* Exception */
static PyObject *StructError;
/* Define various structs to figure out the alignments of types */
typedef struct { char c; short x; } st_short;
typedef struct { char c; int x; } st_int;
typedef struct { char c; long x; } st_long;
typedef struct { char c; float x; } st_float;
typedef struct { char c; double x; } st_double;
typedef struct { char c; void *x; } st_void_p;
typedef struct { char c; size_t x; } st_size_t;
typedef struct { char c; _Bool x; } st_bool;
#define SHORT_ALIGN (sizeof(st_short) - sizeof(short))
#define INT_ALIGN (sizeof(st_int) - sizeof(int))
#define LONG_ALIGN (sizeof(st_long) - sizeof(long))
#define FLOAT_ALIGN (sizeof(st_float) - sizeof(float))
#define DOUBLE_ALIGN (sizeof(st_double) - sizeof(double))
#define VOID_P_ALIGN (sizeof(st_void_p) - sizeof(void *))
#define SIZE_T_ALIGN (sizeof(st_size_t) - sizeof(size_t))
#define BOOL_ALIGN (sizeof(st_bool) - sizeof(_Bool))
/* We can't support q and Q in native mode unless the compiler does;
in std mode, they're 8 bytes on all platforms. */
typedef struct { char c; long long x; } s_long_long;
#define LONG_LONG_ALIGN (sizeof(s_long_long) - sizeof(long long))
#ifdef __powerc
#pragma options align=reset
#endif
/*[python input]
class cache_struct_converter(CConverter):
type = 'PyStructObject *'
converter = 'cache_struct_converter'
c_default = "NULL"
def cleanup(self):
return "Py_XDECREF(%s);\n" % self.name
[python start generated code]*/
/*[python end generated code: output=da39a3ee5e6b4b0d input=49957cca130ffb63]*/
static int cache_struct_converter(PyObject *, PyObject **);
#include "clinic/_struct.c.h"
/* Helper for integer format codes: converts an arbitrary Python object to a
PyLongObject if possible, otherwise fails. Caller should decref. */
static PyObject *
get_pylong(PyObject *v)
{
assert(v != NULL);
if (!PyLong_Check(v)) {
/* Not an integer; try to use __index__ to convert. */
if (PyIndex_Check(v)) {
v = PyNumber_Index(v);
if (v == NULL)
return NULL;
}
else {
PyErr_SetString(StructError,
"required argument is not an integer");
return NULL;
}
}
else
Py_INCREF(v);
assert(PyLong_Check(v));
return v;
}
/* Helper routine to get a C long and raise the appropriate error if it isn't
one */
static int
get_long(PyObject *v, long *p)
{
long x;
v = get_pylong(v);
if (v == NULL)
return -1;
assert(PyLong_Check(v));
x = PyLong_AsLong(v);
Py_DECREF(v);
if (x == (long)-1 && PyErr_Occurred()) {
if (PyErr_ExceptionMatches(PyExc_OverflowError))
PyErr_SetString(StructError,
"argument out of range");
return -1;
}
*p = x;
return 0;
}
/* Same, but handling unsigned long */
static int
get_ulong(PyObject *v, unsigned long *p)
{
unsigned long x;
v = get_pylong(v);
if (v == NULL)
return -1;
assert(PyLong_Check(v));
x = PyLong_AsUnsignedLong(v);
Py_DECREF(v);
if (x == (unsigned long)-1 && PyErr_Occurred()) {
if (PyErr_ExceptionMatches(PyExc_OverflowError))
PyErr_SetString(StructError,
"argument out of range");
return -1;
}
*p = x;
return 0;
}
/* Same, but handling native long long. */
static int
get_longlong(PyObject *v, long long *p)
{
long long x;
v = get_pylong(v);
if (v == NULL)
return -1;
assert(PyLong_Check(v));
x = PyLong_AsLongLong(v);
Py_DECREF(v);
if (x == (long long)-1 && PyErr_Occurred()) {
if (PyErr_ExceptionMatches(PyExc_OverflowError))
PyErr_SetString(StructError,
"argument out of range");
return -1;
}
*p = x;
return 0;
}
/* Same, but handling native unsigned long long. */
static int
get_ulonglong(PyObject *v, unsigned long long *p)
{
unsigned long long x;
v = get_pylong(v);
if (v == NULL)
return -1;
assert(PyLong_Check(v));
x = PyLong_AsUnsignedLongLong(v);
Py_DECREF(v);
if (x == (unsigned long long)-1 && PyErr_Occurred()) {
if (PyErr_ExceptionMatches(PyExc_OverflowError))
PyErr_SetString(StructError,
"argument out of range");
return -1;
}
*p = x;
return 0;
}
/* Same, but handling Py_ssize_t */
static int
get_ssize_t(PyObject *v, Py_ssize_t *p)
{
Py_ssize_t x;
v = get_pylong(v);
if (v == NULL)
return -1;
assert(PyLong_Check(v));
x = PyLong_AsSsize_t(v);
Py_DECREF(v);
if (x == (Py_ssize_t)-1 && PyErr_Occurred()) {
if (PyErr_ExceptionMatches(PyExc_OverflowError))
PyErr_SetString(StructError,
"argument out of range");
return -1;
}
*p = x;
return 0;
}
/* Same, but handling size_t */
static int
get_size_t(PyObject *v, size_t *p)
{
size_t x;
v = get_pylong(v);
if (v == NULL)
return -1;
assert(PyLong_Check(v));
x = PyLong_AsSize_t(v);
Py_DECREF(v);
if (x == (size_t)-1 && PyErr_Occurred()) {
if (PyErr_ExceptionMatches(PyExc_OverflowError))
PyErr_SetString(StructError,
"argument out of range");
return -1;
}
*p = x;
return 0;
}
#define RANGE_ERROR(x, f, flag, mask) return _range_error(f, flag)
/* Floating point helpers */
static PyObject *
unpack_halffloat(const char *p, /* start of 2-byte string */
int le) /* true for little-endian, false for big-endian */
{
double x;
x = _PyFloat_Unpack2((unsigned char *)p, le);
if (x == -1.0 && PyErr_Occurred()) {
return NULL;
}
return PyFloat_FromDouble(x);
}
static int
pack_halffloat(char *p, /* start of 2-byte string */
PyObject *v, /* value to pack */
int le) /* true for little-endian, false for big-endian */
{
double x = PyFloat_AsDouble(v);
if (x == -1.0 && PyErr_Occurred()) {
PyErr_SetString(StructError,
"required argument is not a float");
return -1;
}
return _PyFloat_Pack2(x, (unsigned char *)p, le);
}
static PyObject *
unpack_float(const char *p, /* start of 4-byte string */
int le) /* true for little-endian, false for big-endian */
{
double x;
x = _PyFloat_Unpack4((unsigned char *)p, le);
if (x == -1.0 && PyErr_Occurred())
return NULL;
return PyFloat_FromDouble(x);
}
static PyObject *
unpack_double(const char *p, /* start of 8-byte string */
int le) /* true for little-endian, false for big-endian */
{
double x;
x = _PyFloat_Unpack8((unsigned char *)p, le);
if (x == -1.0 && PyErr_Occurred())
return NULL;
return PyFloat_FromDouble(x);
}
/* Helper to format the range error exceptions */
static int
_range_error(const formatdef *f, int is_unsigned)
{
/* ulargest is the largest unsigned value with f->size bytes.
* Note that the simpler:
* ((size_t)1 size * 8)) - 1
* doesn't work when f->size == sizeof(size_t) because C doesn't
* define what happens when a left shift count is >= the number of
* bits in the integer being shifted; e.g., on some boxes it doesn't
* shift at all when they're equal.
*/
const size_t ulargest = (size_t)-1 >> ((SIZEOF_SIZE_T - f->size)*8);
assert(f->size >= 1 && f->size format,
ulargest);
else {
const Py_ssize_t largest = (Py_ssize_t)(ulargest >> 1);
PyErr_Format(StructError,
"'%c' format requires %zd bytes\n\
\n\
Return a bytes object containing values v1, v2, ... packed according\n\
to the format string S.format. See help(struct) for more on format\n\
strings.");
static PyObject *
s_pack(PyObject *self, PyObject *const *args, Py_ssize_t nargs)
{
PyStructObject *soself;
PyObject *result;
/* Validate arguments. */
soself = (PyStructObject *)self;
assert(PyStruct_Check(self));
assert(soself->s_codes != NULL);
if (nargs != soself->s_len)
{
PyErr_Format(StructError,
"pack expected %zd items for packing (got %zd)", soself->s_len, nargs);
return NULL;
}
/* Allocate a new buffer */
result = PyBytes_FromStringAndSize((char *)NULL, soself->s_size);
if (result == NULL)
return NULL;
/* Call the guts */
if ( s_pack_internal(soself, args, 0, PyBytes_AS_STRING(result)) != 0 ) {
Py_DECREF(result);
return NULL;
}
return result;
}
PyDoc_STRVAR(s_pack_into__doc__,
"S.pack_into(buffer, offset, v1, v2, ...)\n\
\n\
Pack the values v1, v2, ... according to the format string S.format\n\
and write the packed bytes into the writable buffer buf starting at\n\
offset. Note that the offset is a required argument. See\n\
help(struct) for more on format strings.");
static PyObject *
s_pack_into(PyObject *self, PyObject *const *args, Py_ssize_t nargs)
{
PyStructObject *soself;
Py_buffer buffer;
Py_ssize_t offset;
/* Validate arguments. +1 is for the first arg as buffer. */
soself = (PyStructObject *)self;
assert(PyStruct_Check(self));
assert(soself->s_codes != NULL);
if (nargs != (soself->s_len + 2))
{
if (nargs == 0) {
PyErr_Format(StructError,
"pack_into expected buffer argument");
}
else if (nargs == 1) {
PyErr_Format(StructError,
"pack_into expected offset argument");
}
else {
PyErr_Format(StructError,
"pack_into expected %zd items for packing (got %zd)",
soself->s_len, (nargs - 2));
}
return NULL;
}
/* Extract a writable memory buffer from the first argument */
if (!PyArg_Parse(args[0], "w*", &buffer))
return NULL;
assert(buffer.len >= 0);
/* Extract the offset from the first argument */
offset = PyNumber_AsSsize_t(args[1], PyExc_IndexError);
if (offset == -1 && PyErr_Occurred()) {
PyBuffer_Release(&buffer);
return NULL;
}
/* Support negative offsets. */
if (offset < 0) {
/* Check that negative offset is low enough to fit data */
if (offset + soself->s_size > 0) {
PyErr_Format(StructError,
"no space to pack %zd bytes at offset %zd",
soself->s_size,
offset);
PyBuffer_Release(&buffer);
return NULL;
}
/* Check that negative offset is not crossing buffer boundary */
if (offset + buffer.len < 0) {
PyErr_Format(StructError,
"offset %zd out of range for %zd-byte buffer",
offset,
buffer.len);
PyBuffer_Release(&buffer);
return NULL;
}
offset += buffer.len;
}
/* Check boundaries */
if ((buffer.len - offset) < soself->s_size) {
assert(offset >= 0);
assert(soself->s_size >= 0);
PyErr_Format(StructError,
"pack_into requires a buffer of at least %zu bytes for "
"packing %zd bytes at offset %zd "
"(actual buffer size is %zd)",
(size_t)soself->s_size + (size_t)offset,
soself->s_size,
offset,
buffer.len);
PyBuffer_Release(&buffer);
return NULL;
}
/* Call the guts */
if (s_pack_internal(soself, args, 2, (char*)buffer.buf + offset) != 0) {
PyBuffer_Release(&buffer);
return NULL;
}
PyBuffer_Release(&buffer);
Py_RETURN_NONE;
}
static PyObject *
s_get_format(PyStructObject *self, void *unused)
{
return PyUnicode_FromStringAndSize(PyBytes_AS_STRING(self->s_format),
PyBytes_GET_SIZE(self->s_format));
}
static PyObject *
s_get_size(PyStructObject *self, void *unused)
{
return PyLong_FromSsize_t(self->s_size);
}
PyDoc_STRVAR(s_sizeof__doc__,
"S.__sizeof__() -> size of S in memory, in bytes");
static PyObject *
s_sizeof(PyStructObject *self, void *unused)
{
Py_ssize_t size;
formatcode *code;
PyTypeObject *type = Py_GetType(self);
size = _PyObject_SIZE(type) + sizeof(formatcode);
Py_DECREF(type);
for (code = self->s_codes; code->fmtdef != NULL; code++)
size += sizeof(formatcode);
return PyLong_FromSsize_t(size);
}
/* List of functions */
static struct PyMethodDef s_methods[] = {
STRUCT_ITER_UNPACK_METHODDEF
{"pack", (PyCFunction)s_pack, METH_FASTCALL, s_pack__doc__},
{"pack_into", (PyCFunction)s_pack_into, METH_FASTCALL, s_pack_into__doc__},
STRUCT_UNPACK_METHODDEF
STRUCT_UNPACK_FROM_METHODDEF
{"__sizeof__", (PyCFunction)s_sizeof, METH_NOARGS, s_sizeof__doc__},
{NULL, NULL} /* sentinel */
};
#define OFF(x) offsetof(PyStructObject, x)
static PyGetSetDef s_getsetlist[] = {
{"format", (getter)s_get_format, (setter)NULL, "struct format string", NULL},
{"size", (getter)s_get_size, (setter)NULL, "struct size in bytes", NULL},
{NULL} /* sentinel */
};
static
PyTypeObject PyStructType = {
PyVarObject_HEAD_INIT(NULL, 0)
"Struct",
sizeof(PyStructObject),
0,
(destructor)s_dealloc, /* tp_dealloc */
0, /* tp_print */
0, /* tp_getattr */
0, /* tp_setattr */
0, /* tp_reserved */
0, /* tp_repr */
0, /* tp_as_number */
0, /* tp_as_sequence */
0, /* tp_as_mapping */
0, /* tp_hash */
0, /* tp_call */
0, /* tp_str */
PyObject_GenericGetAttr, /* tp_getattro */
PyObject_GenericSetAttr, /* tp_setattro */
0, /* tp_as_buffer */
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
Struct___init____doc__, /* tp_doc */
0, /* tp_traverse */
0, /* tp_clear */
0, /* tp_richcompare */
offsetof(PyStructObject, weakreflist), /* tp_weaklistoffset */
0, /* tp_iter */
0, /* tp_iternext */
s_methods, /* tp_methods */
NULL, /* tp_members */
s_getsetlist, /* tp_getset */
0, /* tp_base */
0, /* tp_dict */
0, /* tp_descr_get */
0, /* tp_descr_set */
0, /* tp_dictoffset */
Struct___init__, /* tp_init */
PyType_GenericAlloc, /* tp_alloc */
s_new, /* tp_new */
PyObject_Del, /* tp_free */
};
/* ---- Standalone functions ---- */
#define MAXCACHE 100
static PyObject *cache = NULL;
static int
cache_struct_converter(PyObject *fmt, PyObject **ptr)
{
PyObject * s_object;
if (fmt == NULL) {
Py_DECREF(*ptr);
*ptr = NULL;
return 1;
}
if (cache == NULL) {
cache = PyDict_New();
if (cache == NULL)
return 0;
}
s_object = PyDict_GetItemRef(cache, fmt);
if (s_object != NULL) {
*ptr = s_object;
return Py_CLEANUP_SUPPORTED;
}
s_object = PyObject_CallFunctionObjArgs((PyObject *)(&PyStructType), fmt, NULL);
if (s_object != NULL) {
if (PyDict_GET_SIZE(cache) >= MAXCACHE)
PyDict_Clear(cache);
/* Attempt to cache the result */
if (PyDict_SetItem(cache, fmt, s_object) == -1)
PyErr_Clear();
*ptr = s_object;
return Py_CLEANUP_SUPPORTED;
}
return 0;
}
/*[clinic input]
_clearcache
Clear the internal cache.
[clinic start generated code]*/
static PyObject *
_clearcache_impl(PyObject *module)
/*[clinic end generated code: output=ce4fb8a7bf7cb523 input=463eaae04bab3211]*/
{
Py_CLEAR(cache);
Py_RETURN_NONE;
}
/*[clinic input]
calcsize -> Py_ssize_t
format as s_object: cache_struct
/
Return size in bytes of the struct described by the format string.
[clinic start generated code]*/
static Py_ssize_t
calcsize_impl(PyObject *module, PyStructObject *s_object)
/*[clinic end generated code: output=db7d23d09c6932c4 input=96a6a590c7717ecd]*/
{
return s_object->s_size;
}
PyDoc_STRVAR(pack_doc,
"pack(format, v1, v2, ...) -> bytes\n\
\n\
Return a bytes object containing the values v1, v2, ... packed according\n\
to the format string. See help(struct) for more on format strings.");
static PyObject *
pack(PyObject *self, PyObject *const *args, Py_ssize_t nargs)
{
PyObject *s_object = NULL;
PyObject *format, *result;
if (nargs == 0) {
PyErr_SetString(PyExc_TypeError, "missing format argument");
return NULL;
}
format = args[0];
if (!cache_struct_converter(format, &s_object)) {
return NULL;
}
result = s_pack(s_object, args + 1, nargs - 1);
Py_DECREF(s_object);
return result;
}
PyDoc_STRVAR(pack_into_doc,
"pack_into(format, buffer, offset, v1, v2, ...)\n\
\n\
Pack the values v1, v2, ... according to the format string and write\n\
the packed bytes into the writable buffer buf starting at offset. Note\n\
that the offset is a required argument. See help(struct) for more\n\
on format strings.");
static PyObject *
pack_into(PyObject *self, PyObject *const *args, Py_ssize_t nargs)
{
PyObject *s_object = NULL;
PyObject *format, *result;
if (nargs == 0) {
PyErr_SetString(PyExc_TypeError, "missing format argument");
return NULL;
}
format = args[0];
if (!cache_struct_converter(format, &s_object)) {
return NULL;
}
result = s_pack_into(s_object, args + 1, nargs - 1);
Py_DECREF(s_object);
return result;
}
/*[clinic input]
unpack
format as s_object: cache_struct
buffer: Py_buffer
/
Return a tuple containing values unpacked according to the format string.
The buffer's size in bytes must be calcsize(format).
See help(struct) for more on format strings.
[clinic start generated code]*/
static PyObject *
unpack_impl(PyObject *module, PyStructObject *s_object, Py_buffer *buffer)
/*[clinic end generated code: output=48ddd4d88eca8551 input=05fa3b91678da727]*/
{
return Struct_unpack_impl(s_object, buffer);
}
/*[clinic input]
unpack_from
format as s_object: cache_struct
/
buffer: Py_buffer
offset: Py_ssize_t = 0
Return a tuple containing values unpacked according to the format string.
The buffer's size, minus offset, must be at least calcsize(format).
See help(struct) for more on format strings.
[clinic start generated code]*/
static PyObject *
unpack_from_impl(PyObject *module, PyStructObject *s_object,
Py_buffer *buffer, Py_ssize_t offset)
/*[clinic end generated code: output=1042631674c6e0d3 input=6e80a5398e985025]*/
{
return Struct_unpack_from_impl(s_object, buffer, offset);
}
/*[clinic input]
iter_unpack
format as s_object: cache_struct
buffer: object
/
Return an iterator yielding tuples unpacked from the given bytes.
The bytes are unpacked according to the format string, like
a repeated invocation of unpack_from().
Requires that the bytes length be a multiple of the format struct size.
[clinic start generated code]*/
static PyObject *
iter_unpack_impl(PyObject *module, PyStructObject *s_object,
PyObject *buffer)
/*[clinic end generated code: output=0ae50e250d20e74d input=b214a58869a3c98d]*/
{
return Struct_iter_unpack(s_object, buffer);
}
static struct PyMethodDef module_functions[] = {
_CLEARCACHE_METHODDEF
CALCSIZE_METHODDEF
ITER_UNPACK_METHODDEF
{"pack", (PyCFunction)pack, METH_FASTCALL, pack_doc},
{"pack_into", (PyCFunction)pack_into, METH_FASTCALL, pack_into_doc},
UNPACK_METHODDEF
UNPACK_FROM_METHODDEF
{NULL, NULL} /* sentinel */
};
/* Module initialization */
PyDoc_STRVAR(module_doc,
"Functions to convert between Python values and C structs.\n\
Python bytes objects are used to hold the data representing the C struct\n\
and also as format strings (explained below) to describe the layout of data\n\
in the C struct.\n\
\n\
The optional first format char indicates byte order, size and alignment:\n\
@: native order, size & alignment (default)\n\
=: native order, std. size & alignment\n\
: big-endian, std. size & alignment\n\
!: same as >\n\
\n\
The remaining chars indicate types of args and must match exactly;\n\
these can be preceded by a decimal repeat count:\n\
x: pad byte (no data); c:char; b:signed byte; B:unsigned byte;\n\
?: _Bool (requires C99; if not available, char is used instead)\n\
h:short; H:unsigned short; i:int; I:unsigned int;\n\
l:long; L:unsigned long; f:float; d:double; e:half-float.\n\
Special cases (preceding decimal count indicates length):\n\
s:string (array of char); p: pascal string (with count byte).\n\
Special cases (only available in native format):\n\
n:ssize_t; N:size_t;\n\
P:an integer type that is wide enough to hold a pointer.\n\
Special case (not in native mode unless 'long long' in platform C):\n\
q:long long; Q:unsigned long long\n\
Whitespace between formats is ignored.\n\
\n\
The variable struct.error is an exception raised on errors.\n");
static struct PyModuleDef _structmodule = {
PyModuleDef_HEAD_INIT,
"_struct",
module_doc,
-1,
module_functions,
NULL,
NULL,
NULL,
NULL
};
PyMODINIT_FUNC
PyInit__struct(void)
{
PyObject *m;
m = PyModule_Create(&_structmodule);
if (m == NULL)
return NULL;
_Py_SET_TYPE(&PyStructType, &PyType_Type);
if (PyType_Ready(&PyStructType) < 0)
return NULL;
if (PyType_Ready(&unpackiter_type) < 0)
return NULL;
/* Check endian and swap in faster functions */
{
const formatdef *native = native_table;
formatdef *other, *ptr;
#if PY_LITTLE_ENDIAN
other = lilendian_table;
#else
other = bigendian_table;
#endif
/* Scan through the native table, find a matching
entry in the endian table and swap in the
native implementations whenever possible
(64-bit platforms may not have "standard" sizes) */
while (native->format != '\0' && other->format != '\0') {
ptr = other;
while (ptr->format != '\0') {
if (ptr->format == native->format) {
/* Match faster when formats are
listed in the same order */
if (ptr == other)
other++;
/* Only use the trick if the
size matches */
if (ptr->size != native->size)
break;
/* Skip float and double, could be
"unknown" float format */
if (ptr->format == 'd' || ptr->format == 'f')
break;
ptr->pack = native->pack;
ptr->unpack = native->unpack;
break;
}
ptr++;
}
native++;
}
}
/* Add some symbolic constants to the module */
if (StructError == NULL) {
StructError = PyErr_NewException("struct.error", NULL, NULL);
if (StructError == NULL)
return NULL;
}
Py_INCREF(StructError);
PyModule_AddObject(m, "error", StructError);
Py_INCREF((PyObject*)&PyStructType);
PyModule_AddObject(m, "Struct", (PyObject*)&PyStructType);
return m;
}