The buffer interface exports a model where an object can expose its internal data as a set of chunks of data, where each chunk is specified as a pointer/length pair. These chunks are called segments and are presumed to be non-contiguous in memory.
If an object does not export the buffer interface, then its tp_as_buffer member in the PyTypeObject structure should be NULL. Otherwise, the tp_as_buffer will point to a PyBufferProcs structure.
Note: It is very important that your
PyTypeObject structure uses
Py_TPFLAGS_DEFAULT for the
value of the tp_flags member rather than
tells the Python runtime that your PyBufferProcs structure
contains the bf_getcharbuffer slot. Older versions of Python
did not have this member, so a new Python interpreter using an old
extension needs to be able to test for its presence before using it.
The first slot is bf_getreadbuffer, of type getreadbufferproc. If this slot is NULL, then the object does not support reading from the internal data. This is non-sensical, so implementors should fill this in, but callers should test that the slot contains a non-NULL value.
The next slot is bf_getwritebuffer having type getwritebufferproc. This slot may be NULL if the object does not allow writing into its returned buffers.
The third slot is bf_getsegcount, with type getsegcountproc. This slot must not be NULL and is used to inform the caller how many segments the object contains. Simple objects such as PyString_Type and PyBuffer_Type objects contain a single segment.
The last slot is bf_getcharbuffer, of type
getcharbufferproc. This slot will only be present if the
Py_TPFLAGS_HAVE_GETCHARBUFFER flag is present in the
tp_flags field of the object's PyTypeObject. Before using
this slot, the caller should test whether it is present by using the
Note: The current policy seems to state that these characters may be multi-byte characters. This implies that a buffer size of N does not mean there are N characters present.
-1. The segment which is passed must be zero or positive, and strictly less than the number of segments returned by the bf_getsegcount slot function. On success, returns
*ptrptrto a pointer to the buffer memory.
*ptrptr; the memory buffer must correspond to buffer segment segment. Must return
-1and set an exception on error. TypeError should be raised if the object only supports read-only buffers, and SystemError should be raised when segment specifies a segment that doesn't exist.
*lenp. The function cannot fail.