<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"api.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"api.html" title='Python/C API Reference Manual'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"supporting-iteration.html" />
<link rel=
"prev" href=
"sequence-structs.html" />
<link rel=
"parent" href=
"newTypes.html" />
<link rel=
"next" href=
"supporting-iteration.html" />
<meta name='aesop' content='information'
/>
<title>10.7 Buffer Object Structures
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"10.6 Sequence Object Structures"
href=
"sequence-structs.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"10. Object Implementation Support"
href=
"newTypes.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"10.8 Supporting the Iterator"
href=
"supporting-iteration.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python/C API Reference Manual
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"sequence-structs.html">10.6 Sequence Object Structures
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"newTypes.html">10. Object Implementation Support
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"supporting-iteration.html">10.8 Supporting the Iterator
</A>
<!--End of Navigation Panel-->
<H1><A NAME=
"SECTION0012700000000000000000"></A><A NAME=
"buffer-structs"></A>
10.7 Buffer Object Structures
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
<i class=
"dfn">segments
</i> and are presumed to be non-contiguous in memory.
If an object does not export the buffer interface, then its
<tt class=
"member">tp_as_buffer
</tt> member in the
<tt class=
"ctype">PyTypeObject
</tt> structure
should be
<tt class=
"constant">NULL
</tt>. Otherwise, the
<tt class=
"member">tp_as_buffer
</tt> will point to
a
<tt class=
"ctype">PyBufferProcs
</tt> structure.
<span class=
"note"><b class=
"label">Note:
</b>
It is very important that your
<tt class=
"ctype">PyTypeObject
</tt> structure
uses
<tt class=
"constant">Py_TPFLAGS_DEFAULT
</tt> for the value of the
<tt class=
"member">tp_flags
</tt> member rather than
<code>0</code>. This tells the Python
runtime that your
<tt class=
"ctype">PyBufferProcs
</tt> structure contains the
<tt class=
"member">bf_getcharbuffer
</tt> 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.
</span>
<dl><dt><b><tt class=
"ctype"><a id='l2h-
1008' xml:id='l2h-
1008'
>PyBufferProcs
</a></tt></b></dt>
Structure used to hold the function pointers which define an
implementation of the buffer protocol.
The first slot is
<tt class=
"member">bf_getreadbuffer
</tt>, of type
<tt class=
"ctype">getreadbufferproc
</tt>. If this slot is
<tt class=
"constant">NULL
</tt>, 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-
<tt class=
"constant">NULL
</tt> value.
The next slot is
<tt class=
"member">bf_getwritebuffer
</tt> having type
<tt class=
"ctype">getwritebufferproc
</tt>. This slot may be
<tt class=
"constant">NULL
</tt> if the object
does not allow writing into its returned buffers.
The third slot is
<tt class=
"member">bf_getsegcount
</tt>, with type
<tt class=
"ctype">getsegcountproc
</tt>. This slot must not be
<tt class=
"constant">NULL
</tt> and is used
to inform the caller how many segments the object contains. Simple
objects such as
<tt class=
"ctype">PyString_Type
</tt> and
<tt class=
"ctype">PyBuffer_Type
</tt>
objects contain a single segment.
The last slot is
<tt class=
"member">bf_getcharbuffer
</tt>, of type
<tt class=
"ctype">getcharbufferproc
</tt>. This slot will only be present if the
<tt class=
"constant">Py_TPFLAGS_HAVE_GETCHARBUFFER
</tt> flag is present in the
<tt class=
"member">tp_flags
</tt> field of the object's
<tt class=
"ctype">PyTypeObject
</tt>.
Before using this slot, the caller should test whether it is present
<tt class=
"cfunction">PyType_HasFeature()
</tt><a id='l2h-
1014' xml:id='l2h-
1014'
></a>
function. If present, it may be
<tt class=
"constant">NULL
</tt>, indicating that the object's
contents cannot be used as
<em>8-bit characters
</em>.
The slot function may also raise an error if the object's contents
cannot be interpreted as
8-bit characters. For example, if the
object is an array which is configured to hold floating point
values, an exception may be raised if a caller attempts to use
<tt class=
"member">bf_getcharbuffer
</tt> to fetch a sequence of
8-bit characters.
This notion of exporting the internal buffers as ``text'' is used to
distinguish between objects that are binary in nature, and those
which have character-based content.
<span class=
"note"><b class=
"label">Note:
</b>
The current policy seems to state that these characters
may be multi-byte characters. This implies that a buffer size of
<var>N
</var> does not mean there are
<var>N
</var> characters present.
</span>
<dl><dt><b><tt id='l2h-
1009' xml:id='l2h-
1009'
>Py_TPFLAGS_HAVE_GETCHARBUFFER
</tt></b></dt>
Flag bit set in the type structure to indicate that the
<tt class=
"member">bf_getcharbuffer
</tt> slot is known. This being set does not
indicate that the object supports the buffer interface or that the
<tt class=
"member">bf_getcharbuffer
</tt> slot is non-
<tt class=
"constant">NULL
</tt>.
<dl><dt><b><tt class=
"ctype"><a id='l2h-
1010' xml:id='l2h-
1010'
>int (*getreadbufferproc)
(PyObject *self, int segment, void **ptrptr)
</a></tt></b></dt>
Return a pointer to a readable segment of the buffer. This function
is allowed to raise an exception, in which case it must return
<code>-
1</code>. The
<var>segment
</var> which is passed must be zero or
positive, and strictly less than the number of segments returned by
the
<tt class=
"member">bf_getsegcount
</tt> slot function. On success, it returns
the length of the buffer memory, and sets
<code>*
<var>ptrptr
</var></code> to a
<dl><dt><b><tt class=
"ctype"><a id='l2h-
1011' xml:id='l2h-
1011'
>int (*getwritebufferproc)
(PyObject *self, int segment, void **ptrptr)
</a></tt></b></dt>
Return a pointer to a writable memory buffer in
<code>*
<var>ptrptr
</var></code>, and the length of that segment as the function
return value. The memory buffer must correspond to buffer segment
<var>segment
</var>. Must return
<code>-
1</code> and set an exception on
error.
<tt class=
"exception">TypeError
</tt> should be raised if the object only
supports read-only buffers, and
<tt class=
"exception">SystemError
</tt> should be
raised when
<var>segment
</var> specifies a segment that doesn't exist.
<dl><dt><b><tt class=
"ctype"><a id='l2h-
1012' xml:id='l2h-
1012'
>int (*getsegcountproc)
(PyObject *self, int *lenp)
</a></tt></b></dt>
Return the number of memory segments which comprise the buffer. If
<var>lenp
</var> is not
<tt class=
"constant">NULL
</tt>, the implementation must report the sum of
the sizes (in bytes) of all segments in
<code>*
<var>lenp
</var></code>.
The function cannot fail.
<dl><dt><b><tt class=
"ctype"><a id='l2h-
1013' xml:id='l2h-
1013'
>int (*getcharbufferproc)
(PyObject *self, int segment, const char **ptrptr)
</a></tt></b></dt>
Return the size of the memory buffer in
<var>ptrptr
</var> for segment
<var>segment
</var>.
<code>*
<var>ptrptr
</var></code> is set to the memory buffer.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"10.6 Sequence Object Structures"
href=
"sequence-structs.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"10. Object Implementation Support"
href=
"newTypes.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"10.8 Supporting the Iterator"
href=
"supporting-iteration.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python/C API Reference Manual
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"sequence-structs.html">10.6 Sequence Object Structures
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"newTypes.html">10. Object Implementation Support
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"supporting-iteration.html">10.8 Supporting the Iterator
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.