projects / OpenSPARC-T2-SAM / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / html / python / ext / simpleExample.html
CommitLineData
920dae64
AT		 1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<link rel="STYLESHEET" href="ext.css" type='text/css' />
5<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
6<link rel='start' href='../index.html' title='Python Documentation Index' />
7<link rel="first" href="ext.html" title='Extending and Embedding the Python Interpreter' />
8<link rel='contents' href='contents.html' title="Contents" />
9<link rel='last' href='about.html' title='About this document...' />
10<link rel='help' href='about.html' title='About this document...' />
11<link rel="next" href="errors.html" />
12<link rel="prev" href="intro.html" />
13<link rel="parent" href="intro.html" />
14<link rel="next" href="errors.html" />
15<meta name='aesop' content='information' />
16<title>1.1 A Simple Example
17</title>
18</head>
19<body>
20<DIV CLASS="navigation">
21<div id='top-navigation-panel' xml:id='top-navigation-panel'>
22<table align="center" width="100%" cellpadding="0" cellspacing="2">
23<tr>
24<td class='online-navigation'><a rel="prev" title="1. Extending Python with"
25 href="intro.html"><img src='../icons/previous.png'
26 border='0' height='32' alt='Previous Page' width='32' /></A></td>
27<td class='online-navigation'><a rel="parent" title="1. Extending Python with"
28 href="intro.html"><img src='../icons/up.png'
29 border='0' height='32' alt='Up One Level' width='32' /></A></td>
30<td class='online-navigation'><a rel="next" title="1.2 Intermezzo: Errors and"
31 href="errors.html"><img src='../icons/next.png'
32 border='0' height='32' alt='Next Page' width='32' /></A></td>
33<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
34<td class='online-navigation'><a rel="contents" title="Table of Contents"
35 href="contents.html"><img src='../icons/contents.png'
36 border='0' height='32' alt='Contents' width='32' /></A></td>
37<td class='online-navigation'><img src='../icons/blank.png'
38 border='0' height='32' alt='' width='32' /></td>
39<td class='online-navigation'><img src='../icons/blank.png'
40 border='0' height='32' alt='' width='32' /></td>
41</tr></table>
42<div class='online-navigation'>
43<b class="navlabel">Previous:</b>
44<a class="sectref" rel="prev" href="intro.html">1. Extending Python with</A>
45<b class="navlabel">Up:</b>
46<a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A>
47<b class="navlabel">Next:</b>
48<a class="sectref" rel="next" href="errors.html">1.2 Intermezzo: Errors and</A>
49</div>
50<hr /></div>
51</DIV>
52<!--End of Navigation Panel-->
53
54<H1><A NAME="SECTION003100000000000000000"></A><A NAME="simpleExample"></A>
55<BR>
561.1 A Simple Example
57
58</H1>
59
60<P>
61Let's create an extension module called "<tt class="samp">spam</tt>" (the favorite food
62of Monty Python fans...) and let's say we want to create a Python
63interface to the C library function <tt class="cfunction">system()</tt>.<A NAME="tex2html1"
64 HREF="#foot519"><SUP>1.1</SUP></A>This function takes a null-terminated character string as argument and
65returns an integer. We want this function to be callable from Python
66as follows:
67
68<P>
69<div class="verbatim"><pre>
70&gt;&gt;&gt; import spam
71&gt;&gt;&gt; status = spam.system("ls -l")
72</pre></div>
73
74<P>
75Begin by creating a file <span class="file">spammodule.c</span>. (Historically, if a
76module is called "<tt class="samp">spam</tt>", the C file containing its implementation
77is called <span class="file">spammodule.c</span>; if the module name is very long, like
78"<tt class="samp">spammify</tt>", the module name can be just <span class="file">spammify.c</span>.)
79
80<P>
81The first line of our file can be:
82
83<P>
84<div class="verbatim"><pre>
85#include &lt;Python.h&gt;
86</pre></div>
87
88<P>
89which pulls in the Python API (you can add a comment describing the
90purpose of the module and a copyright notice if you like).
91
92<P>
93<div class="warning"><b class="label">Warning:</b>
94
95 Since Python may define some pre-processor definitions which affect
96 the standard headers on some systems, you <em>must</em> include
97 <span class="file">Python.h</span> before any standard headers are included.
98</div>
99
100<P>
101All user-visible symbols defined by <span class="file">Python.h</span> have a prefix of
102"<tt class="samp">Py</tt>" or "<tt class="samp">PY</tt>", except those defined in standard header files.
103For convenience, and since they are used extensively by the Python
104interpreter, <code>"Python.h"</code> includes a few standard header files:
105<code>&lt;stdio.h&gt;</code>, <code>&lt;string.h&gt;</code>, <code>&lt;errno.h&gt;</code>, and
106<code>&lt;stdlib.h&gt;</code>. If the latter header file does not exist on your
107system, it declares the functions <tt class="cfunction">malloc()</tt>,
108<tt class="cfunction">free()</tt> and <tt class="cfunction">realloc()</tt> directly.
109
110<P>
111The next thing we add to our module file is the C function that will
112be called when the Python expression "<tt class="samp">spam.system(<var>string</var>)</tt>"is evaluated (we'll see shortly how it ends up being called):
113
114<P>
115<div class="verbatim"><pre>
116static PyObject *
117spam_system(PyObject *self, PyObject *args)
118{
119 const char *command;
120 int sts;
121
122 if (!PyArg_ParseTuple(args, "s", &amp;command))
123 return NULL;
124 sts = system(command);
125 return Py_BuildValue("i", sts);
126}
127</pre></div>
128
129<P>
130There is a straightforward translation from the argument list in
131Python (for example, the single expression <code>"ls -l"</code>) to the
132arguments passed to the C function. The C function always has two
133arguments, conventionally named <var>self</var> and <var>args</var>.
134
135<P>
136The <var>self</var> argument is only used when the C function implements a
137built-in method, not a function. In the example, <var>self</var> will
138always be a <tt class="constant">NULL</tt> pointer, since we are defining a function, not a
139method. (This is done so that the interpreter doesn't have to
140understand two different types of C functions.)
141
142<P>
143The <var>args</var> argument will be a pointer to a Python tuple object
144containing the arguments. Each item of the tuple corresponds to an
145argument in the call's argument list. The arguments are Python
146objects -- in order to do anything with them in our C function we have
147to convert them to C values. The function <tt class="cfunction">PyArg_ParseTuple()</tt>
148in the Python API checks the argument types and converts them to C
149values. It uses a template string to determine the required types of
150the arguments as well as the types of the C variables into which to
151store the converted values. More about this later.
152
153<P>
154<tt class="cfunction">PyArg_ParseTuple()</tt> returns true (nonzero) if all arguments have
155the right type and its components have been stored in the variables
156whose addresses are passed. It returns false (zero) if an invalid
157argument list was passed. In the latter case it also raises an
158appropriate exception so the calling function can return
159<tt class="constant">NULL</tt> immediately (as we saw in the example).
160
161<P>
162<BR><HR><H4>Footnotes</H4>
163<DL>
164<DT><A NAME="foot519">...system().</A><A
165 href="simpleExample.html#tex2html1"><SUP>1.1</SUP></A></DT>
166<DD>An
167interface for this function already exists in the standard module
168<tt class="module">os</tt> -- it was chosen as a simple and straightforward example.
169
170</DD>
171</DL>
172<DIV CLASS="navigation">
173<div class='online-navigation'>
174<p></p><hr />
175<table align="center" width="100%" cellpadding="0" cellspacing="2">
176<tr>
177<td class='online-navigation'><a rel="prev" title="1. Extending Python with"
178 href="intro.html"><img src='../icons/previous.png'
179 border='0' height='32' alt='Previous Page' width='32' /></A></td>
180<td class='online-navigation'><a rel="parent" title="1. Extending Python with"
181 href="intro.html"><img src='../icons/up.png'
182 border='0' height='32' alt='Up One Level' width='32' /></A></td>
183<td class='online-navigation'><a rel="next" title="1.2 Intermezzo: Errors and"
184 href="errors.html"><img src='../icons/next.png'
185 border='0' height='32' alt='Next Page' width='32' /></A></td>
186<td align="center" width="100%">Extending and Embedding the Python Interpreter</td>
187<td class='online-navigation'><a rel="contents" title="Table of Contents"
188 href="contents.html"><img src='../icons/contents.png'
189 border='0' height='32' alt='Contents' width='32' /></A></td>
190<td class='online-navigation'><img src='../icons/blank.png'
191 border='0' height='32' alt='' width='32' /></td>
192<td class='online-navigation'><img src='../icons/blank.png'
193 border='0' height='32' alt='' width='32' /></td>
194</tr></table>
195<div class='online-navigation'>
196<b class="navlabel">Previous:</b>
197<a class="sectref" rel="prev" href="intro.html">1. Extending Python with</A>
198<b class="navlabel">Up:</b>
199<a class="sectref" rel="parent" href="intro.html">1. Extending Python with</A>
200<b class="navlabel">Next:</b>
201<a class="sectref" rel="next" href="errors.html">1.2 Intermezzo: Errors and</A>
202</div>
203</div>
204<hr />
205<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
206</DIV>
207<!--End of Navigation Panel-->
208<ADDRESS>
209See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
210</ADDRESS>
211</BODY>
212</HTML>
Full OpenSPARC architecture tarball including simulator, hypervisor, and OBP.