Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Inline::C.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "C 3"
.TH C 3 "2002-11-04" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Inline::C \- Write Perl Subroutines in C
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Inline::C\*(C'\fR is a module that allows you to write Perl subroutines in C.
Since version 0.30 the Inline module supports multiple programming
languages and each language has its own support module. This document
describes how to use Inline with the C programming language. It also
goes a bit into Perl C internals.
.PP
If you want to start working with programming examples right away, check
out Inline::C\-Cookbook. For more information on Inline in general,
see Inline.
.SH "Usage"
.IX Header "Usage"
You never actually use \f(CW\*(C`Inline::C\*(C'\fR directly. It is just a support
module for using \f(CW\*(C`Inline.pm\*(C'\fR with C. So the usage is always:
.PP
.Vb 1
\&    use Inline C => ...;
.Ve
.PP
or
.PP
.Vb 1
\&    bind Inline C => ...;
.Ve
.SH "Function Definitions"
.IX Header "Function Definitions"
The Inline grammar for C recognizes certain function definitions (or
signatures) in your C code. If a signature is recognized by Inline, then
it will be available in Perl\-space. That is, Inline will generate the
\&\*(L"glue\*(R" necessary to call that function as if it were a Perl subroutine.
If the signature is not recognized, Inline will simply ignore it, with
no complaints. It will not be available from Perl\-space, although it
\&\fIwill\fR be available from C\-space.
.PP
Inline looks for ANSI/prototype style function definitions. They must be
of the form:
.PP
.Vb 1
\&    return-type function-name ( type-name-pairs ) { ... }
.Ve
.PP
The most common types are: \f(CW\*(C`int\*(C'\fR, \f(CW\*(C`long\*(C'\fR, \f(CW\*(C`double\*(C'\fR, \f(CW\*(C`char*\*(C'\fR, and
\&\f(CW\*(C`SV*\*(C'\fR. But you can use any type for which Inline can find a typemap.
Inline uses the \f(CW\*(C`typemap\*(C'\fR file distributed with Perl as the default.
You can specify more typemaps with the \s-1TYPEMAPS\s0 configuration option.
.PP
A return type of \f(CW\*(C`void\*(C'\fR may also be used. The following are examples of
valid function definitions.
.PP
.Vb 5
\&    int Foo(double num, char* str) {
\&    void Foo(double num, char* str) {
\&    SV* Foo() {
\&    void Foo(SV*, ...) {
\&    long Foo(int i, int j, ...) {
.Ve
.PP
The following definitions would not be recognized:
.PP
.Vb 4
\&    Foo(int i) {               # no return type
\&    int Foo(float f) {         # no (default) typemap for float
\&    int Foo(num, str) double num; char* str; {
\&    void Foo(void) {           # void only valid for return type
.Ve
.PP
Notice that Inline only looks for function \fIdefinitions\fR, not function
\&\fIprototypes\fR. Definitions are the syntax directly preceeding a function
body. Also Inline does not scan external files, like headers. Only the
code passed to Inline is used to create bindings; although other
libraries can linked in, and called from C\-space.
.SH "C Configuration Options"
.IX Header "C Configuration Options"
For information on how to specify Inline configuration options, see
Inline. This section describes each of the configuration options
available for C. Most of the options correspond either to MakeMaker or
\&\s-1XS\s0 options of the same name. See ExtUtils::MakeMaker and perlxs.
.Sh "\s-1AUTO_INCLUDE\s0"
.IX Subsection "AUTO_INCLUDE"
Specifies extra statements to automatically included. They will be added
onto the defaults. A newline char will be automatically added.
.PP
.Vb 1
\&    use Inline C => Config => AUTO_INCLUDE => '#include "yourheader.h"';
.Ve
.Sh "\s-1AUTOWRAP\s0"
.IX Subsection "AUTOWRAP"
If you '\s-1ENABLE\s0 => \s-1AUTOWRAP\s0', Inline::C will parse function declarations
(prototype statements) in your C code. For each declaration it can bind
to, it will create a dummy wrapper that will call the real function
which may be in an external library. This is a nice convenience for
functions that would otherwise just require an empty wrapper function.
.PP
This is similar to the base functionality you get from \f(CW\*(C`h2xs\*(C'\fR. It can
be very useful for binding to external libraries.
.Sh "\s-1BOOT\s0"
.IX Subsection "BOOT"
Specifies C code to be executed in the \s-1XS\s0 \s-1BOOT\s0 section. Corresponds to
the \s-1XS\s0 parameter.
.Sh "\s-1CC\s0"
.IX Subsection "CC"
Specify which compiler to use.
.Sh "\s-1CCFLAGS\s0"
.IX Subsection "CCFLAGS"
Specify extra compiler flags.
.Sh "\s-1FILTERS\s0"
.IX Subsection "FILTERS"
Allows you to specify a list of source code filters. If more than one is
requested, be sure to group them with an array ref. The filters can
either be subroutine references or names of filters provided by the
supplementary Inline::Filters module.
.PP
Your source code will be filtered just before it is parsed by Inline.
The \s-1MD5\s0 fingerprint is generated before filtering. Source code
filters can be used to do things like stripping out \s-1POD\s0
documentation, pre-expanding #include statements or whatever else you
please. For example:
.PP
.Vb 2
\&    use Inline C => DATA =>
\&               FILTERS => [Strip_POD => \e&MyFilter => Preprocess ];
.Ve
.PP
Filters are invoked in the order specified. See Inline::Filters for
more information.
.Sh "\s-1INC\s0"
.IX Subsection "INC"
Specifies an include path to use. Corresponds to the MakeMaker parameter.
.PP
.Vb 1
\&    use Inline C => Config => INC => '-I/inc/path';
.Ve
.Sh "\s-1LD\s0"
.IX Subsection "LD"
Specify which linker to use.
.Sh "\s-1LDDLFLAGS\s0"
.IX Subsection "LDDLFLAGS"
Specify which linker flags to use. 
.PP
\&\s-1NOTE:\s0 
These flags will completely override the existing flags, instead of
just adding to them. So if you need to use those too, you must
respecify them here.
.Sh "\s-1LIBS\s0"
.IX Subsection "LIBS"
Specifies external libraries that should be linked into your code.
Corresponds to the MakeMaker parameter.
.PP
.Vb 1
\&    use Inline C => Config => LIBS => '-lyourlib';
.Ve
.PP
or 
.PP
.Vb 1
\&    use Inline C => Config => LIBS => '-L/your/path -lyourlib';
.Ve
.Sh "\s-1MAKE\s0"
.IX Subsection "MAKE"
Specify the name of the 'make' utility to use.
.Sh "\s-1MYEXTLIB\s0"
.IX Subsection "MYEXTLIB"
Specifies a user compiled object that should be linked in. Corresponds
to the MakeMaker parameter.
.PP
.Vb 1
\&    use Inline C => Config => MYEXTLIB => '/your/path/yourmodule.so';
.Ve
.Sh "\s-1OPTIMIZE\s0"
.IX Subsection "OPTIMIZE"
This controls the MakeMaker \s-1OPTIMIZE\s0 setting. By setting this value to
\&\f(CW'\-g'\fR, you can turn on debugging support for your Inline extensions.
This will allow you to be able to set breakpoints in your C code using a
debugger like gdb.
.Sh "\s-1PREFIX\s0"
.IX Subsection "PREFIX"
Specifies a prefix that will be automatically stripped from C functions
when they are bound to Perl. Useful for creating wrappers for shared
library API\-s, and binding to the original names in Perl. Also useful
when names conflict with Perl internals. Corresponds to the \s-1XS\s0
parameter.
.PP
.Vb 1
\&    use Inline C => Config => PREFIX => 'ZLIB_';
.Ve
.Sh "\s-1TYPEMAPS\s0"
.IX Subsection "TYPEMAPS"
Specifies extra typemap files to use. These types will modify the
behaviour of the C parsing. Corresponds to the MakeMaker parameter.
.PP
.Vb 1
\&    use Inline C => Config => TYPEMAPS => '/your/path/typemap';
.Ve
.SH "C\-Perl Bindings"
.IX Header "C-Perl Bindings"
This section describes how the \f(CW\*(C`Perl\*(C'\fR variables get mapped to \f(CW\*(C`C\*(C'\fR
variables and back again.
.PP
First, you need to know how \f(CW\*(C`Perl\*(C'\fR passes arguments back and forth to
subroutines. Basically it uses a stack (also known as the \fBStack\fR).
When a sub is called, all of the parenthesized arguments get expanded
into a list of scalars and pushed onto the \fBStack\fR. The subroutine then
pops all of its parameters off of the \fBStack\fR. When the sub is done, it
pushes all of its return values back onto the \fBStack\fR.
.PP
The \fBStack\fR is an array of scalars known internally as \f(CW\*(C`SV\*(C'\fR's. The
\&\fBStack\fR is actually an array of \fBpointers to \s-1SV\s0\fR or \f(CW\*(C`SV*\*(C'\fR; therefore
every element of the \fBStack\fR is natively a \f(CW\*(C`SV*\*(C'\fR. For \fI\s-1FMTYEWTK\s0\fR
about this, read \f(CW\*(C`perldoc perlguts\*(C'\fR.
.PP
So back to variable mapping. \s-1XS\s0 uses a thing known as \*(L"typemaps\*(R" to turn
each \f(CW\*(C`SV*\*(C'\fR into a \f(CW\*(C`C\*(C'\fR type and back again. This is done through
various \s-1XS\s0 macro calls, casts and the Perl \s-1API\s0. See \f(CW\*(C`perldoc perlapi\*(C'\fR.
\&\s-1XS\s0 allows you to define your own typemaps as well for fancier
non-standard types such as \f(CW\*(C`typedef\*(C'\fR\-ed structs.
.PP
Inline uses the default Perl typemap file for its default types. This
file is called \f(CW\*(C`/usr/local/lib/perl5/5.6.1/ExtUtils/typemap\*(C'\fR, or
something similar, depending on your Perl installation. It has
definitions for over 40 types, which are automatically used by Inline.
(You should probably browse this file at least once, just to get an idea
of the possibilities.)
.PP
Inline parses your code for these types and generates the \s-1XS\s0 code to map
them. The most commonly used types are:
.PP
.Vb 6
\& - int
\& - long
\& - double
\& - char*
\& - void
\& - SV*
.Ve
.PP
If you need to deal with a type that is not in the defaults, just
use the generic \f(CW\*(C`SV*\*(C'\fR type in the function definition. Then inside
your code, do the mapping yourself. Alternatively, you can create
your own typemap files and specify them using the \f(CW\*(C`TYPEMAPS\*(C'\fR
configuration option.
.PP
A return type of \f(CW\*(C`void\*(C'\fR has a special meaning to Inline. It means that
you plan to push the values back onto the \fBStack\fR yourself. This is
what you need to do to return a list of values. If you really don't want
to return anything (the traditional meaning of \f(CW\*(C`void\*(C'\fR) then simply
don't push anything back.
.PP
If ellipsis or \f(CW\*(C`...\*(C'\fR is used at the end of an argument list, it means
that any number of \f(CW\*(C`SV*\*(C'\fRs may follow. Again you will need to pop the
values off of the \f(CW\*(C`Stack\*(C'\fR yourself.
.PP
See \*(L"Examples\*(R" below.
.SH "The Inline Stack Macros"
.IX Header "The Inline Stack Macros"
When you write Inline C, the following lines are automatically prepended
to your code (by default):
.PP
.Vb 4
\&    #include "EXTERN.h"
\&    #include "perl.h"
\&    #include "XSUB.h"
\&    #include "INLINE.h"
.Ve
.PP
The file \f(CW\*(C`INLINE.h\*(C'\fR defines a set of macros that are useful for
handling the Perl Stack from your C functions.
.IP "Inline_Stack_Vars" 4
.IX Item "Inline_Stack_Vars"
You'll need to use this one, if you want to use the others. It sets up a
few local variables: \f(CW\*(C`sp\*(C'\fR, \f(CW\*(C`items\*(C'\fR, \f(CW\*(C`ax\*(C'\fR and \f(CW\*(C`mark\*(C'\fR, for use by the
other macros. It's not important to know what they do, but I mention
them to avoid possible name conflicts.
.Sp
\&\s-1NOTE:\s0 
Since this macro declares variables, you'll need to put it with your
other variable declarations at the top of your function. It must
come before any executable statements and before any other
\&\f(CW\*(C`Inline_Stack\*(C'\fR macros.
.IP "Inline_Stack_Items" 4
.IX Item "Inline_Stack_Items"
Returns the number of arguments passed in on the Stack.
.IP "Inline_Stack_Item(i)" 4
.IX Item "Inline_Stack_Item(i)"
Refers to a particular \f(CW\*(C`SV*\*(C'\fR in the Stack, where \f(CW\*(C`i\*(C'\fR is an index
number starting from zero. Can be used to get or set the value.
.IP "Inline_Stack_Reset" 4
.IX Item "Inline_Stack_Reset"
Use this before pushing anything back onto the Stack. It resets the
internal Stack pointer to the beginning of the Stack.
.IP "Inline_Stack_Push(sv)" 4
.IX Item "Inline_Stack_Push(sv)"
Push a return value back onto the Stack. The value must be of type \f(CW\*(C`SV*\*(C'\fR.
.IP "Inline_Stack_Done" 4
.IX Item "Inline_Stack_Done"
After you have pushed all of your return values, you must call this macro.
.IP "Inline_Stack_Return(n)" 4
.IX Item "Inline_Stack_Return(n)"
Return \f(CW\*(C`n\*(C'\fR items on the Stack.
.IP "Inline_Stack_Void" 4
.IX Item "Inline_Stack_Void"
A special macro to indicate that you really don't want to return
anything. Same as:
.Sp
.Vb 1
\&    Inline_Stack_Return(0);
.Ve
.Sp
Please note that this macro actually \fBreturns\fR from your function. 
.PP
Each of these macros is available in 3 different styles to suit your
coding tastes. The following macros are equivalent.
.PP
.Vb 3
\&    Inline_Stack_Vars
\&    inline_stack_vars
\&    INLINE_STACK_VARS
.Ve
.PP
All of this functionality is available through \s-1XS\s0 macro calls as well.
So why duplicate the functionality? There are a few reasons why I
decided to offer this set of macros. First, as a convenient way to
access the Stack. Second, for consistent, self documenting, non-cryptic
coding. Third, for future compatibility. It occured to me that if a lot
of people started using \s-1XS\s0 macros for their C code, the interface might
break under Perl6. By using this set, hopefully I will be able to insure
future compatibility of argument handling.
.PP
Of course, if you use the rest of the Perl \s-1API\s0, your code will most
likely break under Perl6. So this is not a 100% guarantee. But since
argument handling is the most common interface you're likely to use, it
seemed like a wise thing to do.
.SH "Writing C Subroutines"
.IX Header "Writing C Subroutines"
The definitions of your C functions will fall into one of the following
four categories. For each category there are special considerations.
.IP "1" 4
.IX Item "1"
.Vb 1
\&    int Foo(int arg1, char* arg2, SV* arg3) {
.Ve
.Sp
This is the simplest case. You have a non \f(CW\*(C`void\*(C'\fR return type and a
fixed length argument list. You don't need to worry about much. All the
conversions will happen automatically.
.IP "2" 4
.IX Item "2"
.Vb 1
\&    void Foo(int arg1, char* arg2, SV* arg3) {
.Ve
.Sp
In this category you have a \f(CW\*(C`void\*(C'\fR return type. This means that either
you want to return nothing, or that you want to return a list. In the
latter case you'll need to push values onto the \fBStack\fR yourself. There
are a few Inline macros that make this easy. Code something like this:
.Sp
.Vb 6
\&    int i, max; SV* my_sv[10];
\&    Inline_Stack_Vars;
\&    Inline_Stack_Reset;
\&    for (i = 0; i < max; i++)
\&      Inline_Stack_Push(my_sv[i]);
\&    Inline_Stack_Done;
.Ve
.Sp
After resetting the Stack pointer, this code pushes a series of return
values. At the end it uses \f(CW\*(C`Inline_Stack_Done\*(C'\fR to mark the end of the
return stack.
.Sp
If you really want to return nothing, then don't use the
\&\f(CW\*(C`Inline_Stack_\*(C'\fR macros. If you must use them, then set use
\&\f(CW\*(C`Inline_Stack_Void\*(C'\fR at the end of your function.
.IP "3" 4
.IX Item "3"
.Vb 1
\&    char* Foo(SV* arg1, ...) {
.Ve
.Sp
In this category you have an unfixed number of arguments. This
means that you'll have to pop values off the \fBStack\fR yourself. Do
it like this:
.Sp
.Vb 4
\&    int i;
\&    Inline_Stack_Vars;
\&    for (i = 0; i < Inline_Stack_Items; i++)
\&      handle_sv(Inline_Stack_Item(i));
.Ve
.Sp
The return type of \f(CWInline_Stack_Item(i)\fR is \f(CW\*(C`SV*\*(C'\fR.
.IP "4" 4
.IX Item "4"
.Vb 1
\&    void* Foo(SV* arg1, ...) {
.Ve
.Sp
In this category you have both a \f(CW\*(C`void\*(C'\fR return type and an
unfixed number of arguments. Just combine the techniques from
Categories 3 and 4.
.SH "Examples"
.IX Header "Examples"
Here are a few examples. Each one is a complete program that you can try
running yourself. For many more examples see Inline::C\-Cookbook.
.Sh "Example #1 \- Greetings"
.IX Subsection "Example #1 - Greetings"
This example will take one string argument (a name) and print a
greeting. The function is called with a string and with a number. In the
second case the number is forced to a string.
.PP
Notice that you do not need to \f(CW\*(C`#include <stdio.h\*(C'\fR>. The \f(CW\*(C`perl.h\*(C'\fR
header file which gets included by default, automatically loads the
standard C header files for you.
.PP
.Vb 8
\&    use Inline C;
\&    greet('Ingy');
\&    greet(42);
\&    __END__    
\&    __C__
\&    void greet(char* name) {
\&      printf("Hello %s!\en", name);
\&    }
.Ve
.Sh "Example #2 \- and Salutations"
.IX Subsection "Example #2 - and Salutations"
This is similar to the last example except that the name is passed in as
a \f(CW\*(C`SV*\*(C'\fR (pointer to Scalar Value) rather than a string (\f(CW\*(C`char*\*(C'\fR). That
means we need to convert the \f(CW\*(C`SV\*(C'\fR to a string ourselves. This is
accomplished using the \f(CW\*(C`SvPVX\*(C'\fR function which is part of the \f(CW\*(C`Perl\*(C'\fR
internal \s-1API\s0. See \f(CW\*(C`perldoc perlapi\*(C'\fR for more info.
.PP
One problem is that \f(CW\*(C`SvPVX\*(C'\fR doesn't automatically convert strings
to numbers, so we get a little surprise when we try to greet \f(CW42\fR.
The program segfaults, a common occurence when delving into the
guts of Perl.
.PP
.Vb 8
\&    use Inline C;
\&    greet('Ingy');
\&    greet(42);
\&    __END__    
\&    __C__
\&    void greet(SV* sv_name) {
\&      printf("Hello %s!\en", SvPVX(sv_name));
\&    }
.Ve
.Sh "Example #3 \- Fixing the problem"
.IX Subsection "Example #3 - Fixing the problem"
We can fix the problem in Example #2 by using the \f(CW\*(C`SvPV\*(C'\fR function
instead. This function will stringify the \f(CW\*(C`SV\*(C'\fR if it does not contain a
string. \f(CW\*(C`SvPV\*(C'\fR returns the length of the string as it's second
parameter. Since we don't care about the length, we can just put
\&\f(CW\*(C`PL_na\*(C'\fR there, which is a special variable designed for that purpose.
.PP
.Vb 8
\&    use Inline C;
\&    greet('Ingy');
\&    greet(42);
\&    __END__
\&    __C__
\&    void greet(SV* sv_name) {
\&      printf("Hello %s!\en", SvPV(sv_name, PL_na));
\&    }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For general information about Inline see Inline.
.PP
For sample programs using Inline with C see Inline::C\-Cookbook.
.PP
For information on supported languages and platforms see
Inline-Support.
.PP
For information on writing your own Inline Language Support Module, see
Inline-API.
.PP
Inline's mailing list is inline@perl.org
.PP
To subscribe, send email to inline\-subscribe@perl.org
.SH "BUGS AND DEFICIENCIES"
.IX Header "BUGS AND DEFICIENCIES"
.IP "1" 4
.IX Item "1"
If you use C function names that happen to be used internally by Perl,
you will get a load error at run time. There is currently no
functionality to prevent this or to warn you. For now, a list of Perl's
internal symbols is packaged in the Inline module distribution under the
filename \f(CW'symbols.perl'\fR. Avoid using these in your code.
.SH "AUTHOR"
.IX Header "AUTHOR"
Brian Ingerson <INGY@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2000, 2001, 2002. Brian Ingerson. All rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
.PP
See http://www.perl.com/perl/misc/Artistic.html