| 1 | =head1 NAME |
| 2 | |
| 3 | Inline::C - Write Perl Subroutines in C |
| 4 | |
| 5 | =head1 DESCRIPTION |
| 6 | |
| 7 | C<Inline::C> is a module that allows you to write Perl subroutines in C. |
| 8 | Since version 0.30 the Inline module supports multiple programming |
| 9 | languages and each language has its own support module. This document |
| 10 | describes how to use Inline with the C programming language. It also |
| 11 | goes a bit into Perl C internals. |
| 12 | |
| 13 | If you want to start working with programming examples right away, check |
| 14 | out L<Inline::C-Cookbook>. For more information on Inline in general, |
| 15 | see L<Inline>. |
| 16 | |
| 17 | =head1 Usage |
| 18 | |
| 19 | You never actually use C<Inline::C> directly. It is just a support |
| 20 | module for using C<Inline.pm> with C. So the usage is always: |
| 21 | |
| 22 | use Inline C => ...; |
| 23 | |
| 24 | or |
| 25 | |
| 26 | bind Inline C => ...; |
| 27 | |
| 28 | =head1 Function Definitions |
| 29 | |
| 30 | The Inline grammar for C recognizes certain function definitions (or |
| 31 | signatures) in your C code. If a signature is recognized by Inline, then |
| 32 | it will be available in Perl-space. That is, Inline will generate the |
| 33 | "glue" necessary to call that function as if it were a Perl subroutine. |
| 34 | If the signature is not recognized, Inline will simply ignore it, with |
| 35 | no complaints. It will not be available from Perl-space, although it |
| 36 | I<will> be available from C-space. |
| 37 | |
| 38 | Inline looks for ANSI/prototype style function definitions. They must be |
| 39 | of the form: |
| 40 | |
| 41 | return-type function-name ( type-name-pairs ) { ... } |
| 42 | |
| 43 | The most common types are: C<int>, C<long>, C<double>, C<char*>, and |
| 44 | C<SV*>. But you can use any type for which Inline can find a typemap. |
| 45 | Inline uses the C<typemap> file distributed with Perl as the default. |
| 46 | You can specify more typemaps with the TYPEMAPS configuration option. |
| 47 | |
| 48 | A return type of C<void> may also be used. The following are examples of |
| 49 | valid function definitions. |
| 50 | |
| 51 | int Foo(double num, char* str) { |
| 52 | void Foo(double num, char* str) { |
| 53 | SV* Foo() { |
| 54 | void Foo(SV*, ...) { |
| 55 | long Foo(int i, int j, ...) { |
| 56 | |
| 57 | The following definitions would not be recognized: |
| 58 | |
| 59 | Foo(int i) { # no return type |
| 60 | int Foo(float f) { # no (default) typemap for float |
| 61 | int Foo(num, str) double num; char* str; { |
| 62 | void Foo(void) { # void only valid for return type |
| 63 | |
| 64 | Notice that Inline only looks for function I<definitions>, not function |
| 65 | I<prototypes>. Definitions are the syntax directly preceeding a function |
| 66 | body. Also Inline does not scan external files, like headers. Only the |
| 67 | code passed to Inline is used to create bindings; although other |
| 68 | libraries can linked in, and called from C-space. |
| 69 | |
| 70 | =head1 C Configuration Options |
| 71 | |
| 72 | For information on how to specify Inline configuration options, see |
| 73 | L<Inline>. This section describes each of the configuration options |
| 74 | available for C. Most of the options correspond either to MakeMaker or |
| 75 | XS options of the same name. See L<ExtUtils::MakeMaker> and L<perlxs>. |
| 76 | |
| 77 | =head2 AUTO_INCLUDE |
| 78 | |
| 79 | Specifies extra statements to automatically included. They will be added |
| 80 | onto the defaults. A newline char will be automatically added. |
| 81 | |
| 82 | use Inline C => Config => AUTO_INCLUDE => '#include "yourheader.h"'; |
| 83 | |
| 84 | =head2 AUTOWRAP |
| 85 | |
| 86 | If you 'ENABLE => AUTOWRAP', Inline::C will parse function declarations |
| 87 | (prototype statements) in your C code. For each declaration it can bind |
| 88 | to, it will create a dummy wrapper that will call the real function |
| 89 | which may be in an external library. This is a nice convenience for |
| 90 | functions that would otherwise just require an empty wrapper function. |
| 91 | |
| 92 | This is similar to the base functionality you get from C<h2xs>. It can |
| 93 | be very useful for binding to external libraries. |
| 94 | |
| 95 | =head2 BOOT |
| 96 | |
| 97 | Specifies C code to be executed in the XS BOOT section. Corresponds to |
| 98 | the XS parameter. |
| 99 | |
| 100 | =head2 CC |
| 101 | |
| 102 | Specify which compiler to use. |
| 103 | |
| 104 | =head2 CCFLAGS |
| 105 | |
| 106 | Specify extra compiler flags. |
| 107 | |
| 108 | =head2 FILTERS |
| 109 | |
| 110 | Allows you to specify a list of source code filters. If more than one is |
| 111 | requested, be sure to group them with an array ref. The filters can |
| 112 | either be subroutine references or names of filters provided by the |
| 113 | supplementary Inline::Filters module. |
| 114 | |
| 115 | Your source code will be filtered just before it is parsed by Inline. |
| 116 | The MD5 fingerprint is generated before filtering. Source code |
| 117 | filters can be used to do things like stripping out POD |
| 118 | documentation, pre-expanding #include statements or whatever else you |
| 119 | please. For example: |
| 120 | |
| 121 | use Inline C => DATA => |
| 122 | FILTERS => [Strip_POD => \&MyFilter => Preprocess ]; |
| 123 | |
| 124 | Filters are invoked in the order specified. See L<Inline::Filters> for |
| 125 | more information. |
| 126 | |
| 127 | =head2 INC |
| 128 | |
| 129 | Specifies an include path to use. Corresponds to the MakeMaker parameter. |
| 130 | |
| 131 | use Inline C => Config => INC => '-I/inc/path'; |
| 132 | |
| 133 | =head2 LD |
| 134 | |
| 135 | Specify which linker to use. |
| 136 | |
| 137 | =head2 LDDLFLAGS |
| 138 | |
| 139 | Specify which linker flags to use. |
| 140 | |
| 141 | NOTE: |
| 142 | These flags will completely override the existing flags, instead of |
| 143 | just adding to them. So if you need to use those too, you must |
| 144 | respecify them here. |
| 145 | |
| 146 | =head2 LIBS |
| 147 | |
| 148 | Specifies external libraries that should be linked into your code. |
| 149 | Corresponds to the MakeMaker parameter. |
| 150 | |
| 151 | use Inline C => Config => LIBS => '-lyourlib'; |
| 152 | |
| 153 | or |
| 154 | |
| 155 | use Inline C => Config => LIBS => '-L/your/path -lyourlib'; |
| 156 | |
| 157 | =head2 MAKE |
| 158 | |
| 159 | Specify the name of the 'make' utility to use. |
| 160 | |
| 161 | =head2 MYEXTLIB |
| 162 | |
| 163 | Specifies a user compiled object that should be linked in. Corresponds |
| 164 | to the MakeMaker parameter. |
| 165 | |
| 166 | use Inline C => Config => MYEXTLIB => '/your/path/yourmodule.so'; |
| 167 | |
| 168 | =head2 OPTIMIZE |
| 169 | |
| 170 | This controls the MakeMaker OPTIMIZE setting. By setting this value to |
| 171 | C<'-g'>, you can turn on debugging support for your Inline extensions. |
| 172 | This will allow you to be able to set breakpoints in your C code using a |
| 173 | debugger like gdb. |
| 174 | |
| 175 | =head2 PREFIX |
| 176 | |
| 177 | Specifies a prefix that will be automatically stripped from C functions |
| 178 | when they are bound to Perl. Useful for creating wrappers for shared |
| 179 | library API-s, and binding to the original names in Perl. Also useful |
| 180 | when names conflict with Perl internals. Corresponds to the XS |
| 181 | parameter. |
| 182 | |
| 183 | use Inline C => Config => PREFIX => 'ZLIB_'; |
| 184 | |
| 185 | =head2 TYPEMAPS |
| 186 | |
| 187 | Specifies extra typemap files to use. These types will modify the |
| 188 | behaviour of the C parsing. Corresponds to the MakeMaker parameter. |
| 189 | |
| 190 | use Inline C => Config => TYPEMAPS => '/your/path/typemap'; |
| 191 | |
| 192 | =head1 C-Perl Bindings |
| 193 | |
| 194 | This section describes how the C<Perl> variables get mapped to C<C> |
| 195 | variables and back again. |
| 196 | |
| 197 | First, you need to know how C<Perl> passes arguments back and forth to |
| 198 | subroutines. Basically it uses a stack (also known as the B<Stack>). |
| 199 | When a sub is called, all of the parenthesized arguments get expanded |
| 200 | into a list of scalars and pushed onto the B<Stack>. The subroutine then |
| 201 | pops all of its parameters off of the B<Stack>. When the sub is done, it |
| 202 | pushes all of its return values back onto the B<Stack>. |
| 203 | |
| 204 | The B<Stack> is an array of scalars known internally as C<SV>'s. The |
| 205 | B<Stack> is actually an array of B<pointers to SV> or C<SV*>; therefore |
| 206 | every element of the B<Stack> is natively a C<SV*>. For I<FMTYEWTK> |
| 207 | about this, read C<perldoc perlguts>. |
| 208 | |
| 209 | So back to variable mapping. XS uses a thing known as "typemaps" to turn |
| 210 | each C<SV*> into a C<C> type and back again. This is done through |
| 211 | various XS macro calls, casts and the Perl API. See C<perldoc perlapi>. |
| 212 | XS allows you to define your own typemaps as well for fancier |
| 213 | non-standard types such as C<typedef>-ed structs. |
| 214 | |
| 215 | Inline uses the default Perl typemap file for its default types. This |
| 216 | file is called C</usr/local/lib/perl5/5.6.1/ExtUtils/typemap>, or |
| 217 | something similar, depending on your Perl installation. It has |
| 218 | definitions for over 40 types, which are automatically used by Inline. |
| 219 | (You should probably browse this file at least once, just to get an idea |
| 220 | of the possibilities.) |
| 221 | |
| 222 | Inline parses your code for these types and generates the XS code to map |
| 223 | them. The most commonly used types are: |
| 224 | |
| 225 | - int |
| 226 | - long |
| 227 | - double |
| 228 | - char* |
| 229 | - void |
| 230 | - SV* |
| 231 | |
| 232 | If you need to deal with a type that is not in the defaults, just |
| 233 | use the generic C<SV*> type in the function definition. Then inside |
| 234 | your code, do the mapping yourself. Alternatively, you can create |
| 235 | your own typemap files and specify them using the C<TYPEMAPS> |
| 236 | configuration option. |
| 237 | |
| 238 | A return type of C<void> has a special meaning to Inline. It means that |
| 239 | you plan to push the values back onto the B<Stack> yourself. This is |
| 240 | what you need to do to return a list of values. If you really don't want |
| 241 | to return anything (the traditional meaning of C<void>) then simply |
| 242 | don't push anything back. |
| 243 | |
| 244 | If ellipsis or C<...> is used at the end of an argument list, it means |
| 245 | that any number of C<SV*>s may follow. Again you will need to pop the |
| 246 | values off of the C<Stack> yourself. |
| 247 | |
| 248 | See L<"Examples"> below. |
| 249 | |
| 250 | =head1 The Inline Stack Macros |
| 251 | |
| 252 | When you write Inline C, the following lines are automatically prepended |
| 253 | to your code (by default): |
| 254 | |
| 255 | #include "EXTERN.h" |
| 256 | #include "perl.h" |
| 257 | #include "XSUB.h" |
| 258 | #include "INLINE.h" |
| 259 | |
| 260 | The file C<INLINE.h> defines a set of macros that are useful for |
| 261 | handling the Perl Stack from your C functions. |
| 262 | |
| 263 | =over 4 |
| 264 | |
| 265 | =item Inline_Stack_Vars |
| 266 | |
| 267 | You'll need to use this one, if you want to use the others. It sets up a |
| 268 | few local variables: C<sp>, C<items>, C<ax> and C<mark>, for use by the |
| 269 | other macros. It's not important to know what they do, but I mention |
| 270 | them to avoid possible name conflicts. |
| 271 | |
| 272 | NOTE: |
| 273 | Since this macro declares variables, you'll need to put it with your |
| 274 | other variable declarations at the top of your function. It must |
| 275 | come before any executable statements and before any other |
| 276 | C<Inline_Stack> macros. |
| 277 | |
| 278 | =item Inline_Stack_Items |
| 279 | |
| 280 | Returns the number of arguments passed in on the Stack. |
| 281 | |
| 282 | =item Inline_Stack_Item(i) |
| 283 | |
| 284 | Refers to a particular C<SV*> in the Stack, where C<i> is an index |
| 285 | number starting from zero. Can be used to get or set the value. |
| 286 | |
| 287 | =item Inline_Stack_Reset |
| 288 | |
| 289 | Use this before pushing anything back onto the Stack. It resets the |
| 290 | internal Stack pointer to the beginning of the Stack. |
| 291 | |
| 292 | =item Inline_Stack_Push(sv) |
| 293 | |
| 294 | Push a return value back onto the Stack. The value must be of type C<SV*>. |
| 295 | |
| 296 | =item Inline_Stack_Done |
| 297 | |
| 298 | After you have pushed all of your return values, you must call this macro. |
| 299 | |
| 300 | =item Inline_Stack_Return(n) |
| 301 | |
| 302 | Return C<n> items on the Stack. |
| 303 | |
| 304 | =item Inline_Stack_Void |
| 305 | |
| 306 | A special macro to indicate that you really don't want to return |
| 307 | anything. Same as: |
| 308 | |
| 309 | Inline_Stack_Return(0); |
| 310 | |
| 311 | Please note that this macro actually B<returns> from your function. |
| 312 | |
| 313 | =back |
| 314 | |
| 315 | Each of these macros is available in 3 different styles to suit your |
| 316 | coding tastes. The following macros are equivalent. |
| 317 | |
| 318 | Inline_Stack_Vars |
| 319 | inline_stack_vars |
| 320 | INLINE_STACK_VARS |
| 321 | |
| 322 | All of this functionality is available through XS macro calls as well. |
| 323 | So why duplicate the functionality? There are a few reasons why I |
| 324 | decided to offer this set of macros. First, as a convenient way to |
| 325 | access the Stack. Second, for consistent, self documenting, non-cryptic |
| 326 | coding. Third, for future compatibility. It occured to me that if a lot |
| 327 | of people started using XS macros for their C code, the interface might |
| 328 | break under Perl6. By using this set, hopefully I will be able to insure |
| 329 | future compatibility of argument handling. |
| 330 | |
| 331 | Of course, if you use the rest of the Perl API, your code will most |
| 332 | likely break under Perl6. So this is not a 100% guarantee. But since |
| 333 | argument handling is the most common interface you're likely to use, it |
| 334 | seemed like a wise thing to do. |
| 335 | |
| 336 | =head1 Writing C Subroutines |
| 337 | |
| 338 | The definitions of your C functions will fall into one of the following |
| 339 | four categories. For each category there are special considerations. |
| 340 | |
| 341 | =over 4 |
| 342 | |
| 343 | =item 1 |
| 344 | |
| 345 | int Foo(int arg1, char* arg2, SV* arg3) { |
| 346 | |
| 347 | This is the simplest case. You have a non C<void> return type and a |
| 348 | fixed length argument list. You don't need to worry about much. All the |
| 349 | conversions will happen automatically. |
| 350 | |
| 351 | =item 2 |
| 352 | |
| 353 | void Foo(int arg1, char* arg2, SV* arg3) { |
| 354 | |
| 355 | In this category you have a C<void> return type. This means that either |
| 356 | you want to return nothing, or that you want to return a list. In the |
| 357 | latter case you'll need to push values onto the B<Stack> yourself. There |
| 358 | are a few Inline macros that make this easy. Code something like this: |
| 359 | |
| 360 | int i, max; SV* my_sv[10]; |
| 361 | Inline_Stack_Vars; |
| 362 | Inline_Stack_Reset; |
| 363 | for (i = 0; i < max; i++) |
| 364 | Inline_Stack_Push(my_sv[i]); |
| 365 | Inline_Stack_Done; |
| 366 | |
| 367 | After resetting the Stack pointer, this code pushes a series of return |
| 368 | values. At the end it uses C<Inline_Stack_Done> to mark the end of the |
| 369 | return stack. |
| 370 | |
| 371 | If you really want to return nothing, then don't use the |
| 372 | C<Inline_Stack_> macros. If you must use them, then set use |
| 373 | C<Inline_Stack_Void> at the end of your function. |
| 374 | |
| 375 | =item 3 |
| 376 | |
| 377 | char* Foo(SV* arg1, ...) { |
| 378 | |
| 379 | In this category you have an unfixed number of arguments. This |
| 380 | means that you'll have to pop values off the B<Stack> yourself. Do |
| 381 | it like this: |
| 382 | |
| 383 | int i; |
| 384 | Inline_Stack_Vars; |
| 385 | for (i = 0; i < Inline_Stack_Items; i++) |
| 386 | handle_sv(Inline_Stack_Item(i)); |
| 387 | |
| 388 | The return type of C<Inline_Stack_Item(i)> is C<SV*>. |
| 389 | |
| 390 | =item 4 |
| 391 | |
| 392 | void* Foo(SV* arg1, ...) { |
| 393 | |
| 394 | In this category you have both a C<void> return type and an |
| 395 | unfixed number of arguments. Just combine the techniques from |
| 396 | Categories 3 and 4. |
| 397 | |
| 398 | =back |
| 399 | |
| 400 | =head1 Examples |
| 401 | |
| 402 | Here are a few examples. Each one is a complete program that you can try |
| 403 | running yourself. For many more examples see L<Inline::C-Cookbook>. |
| 404 | |
| 405 | =head2 Example #1 - Greetings |
| 406 | |
| 407 | This example will take one string argument (a name) and print a |
| 408 | greeting. The function is called with a string and with a number. In the |
| 409 | second case the number is forced to a string. |
| 410 | |
| 411 | Notice that you do not need to C<#include <stdio.h>>. The C<perl.h> |
| 412 | header file which gets included by default, automatically loads the |
| 413 | standard C header files for you. |
| 414 | |
| 415 | use Inline C; |
| 416 | greet('Ingy'); |
| 417 | greet(42); |
| 418 | __END__ |
| 419 | __C__ |
| 420 | void greet(char* name) { |
| 421 | printf("Hello %s!\n", name); |
| 422 | } |
| 423 | |
| 424 | =head2 Example #2 - and Salutations |
| 425 | |
| 426 | This is similar to the last example except that the name is passed in as |
| 427 | a C<SV*> (pointer to Scalar Value) rather than a string (C<char*>). That |
| 428 | means we need to convert the C<SV> to a string ourselves. This is |
| 429 | accomplished using the C<SvPVX> function which is part of the C<Perl> |
| 430 | internal API. See C<perldoc perlapi> for more info. |
| 431 | |
| 432 | One problem is that C<SvPVX> doesn't automatically convert strings |
| 433 | to numbers, so we get a little surprise when we try to greet C<42>. |
| 434 | The program segfaults, a common occurence when delving into the |
| 435 | guts of Perl. |
| 436 | |
| 437 | use Inline C; |
| 438 | greet('Ingy'); |
| 439 | greet(42); |
| 440 | __END__ |
| 441 | __C__ |
| 442 | void greet(SV* sv_name) { |
| 443 | printf("Hello %s!\n", SvPVX(sv_name)); |
| 444 | } |
| 445 | |
| 446 | =head2 Example #3 - Fixing the problem |
| 447 | |
| 448 | We can fix the problem in Example #2 by using the C<SvPV> function |
| 449 | instead. This function will stringify the C<SV> if it does not contain a |
| 450 | string. C<SvPV> returns the length of the string as it's second |
| 451 | parameter. Since we don't care about the length, we can just put |
| 452 | C<PL_na> there, which is a special variable designed for that purpose. |
| 453 | |
| 454 | use Inline C; |
| 455 | greet('Ingy'); |
| 456 | greet(42); |
| 457 | __END__ |
| 458 | __C__ |
| 459 | void greet(SV* sv_name) { |
| 460 | printf("Hello %s!\n", SvPV(sv_name, PL_na)); |
| 461 | } |
| 462 | |
| 463 | =head1 SEE ALSO |
| 464 | |
| 465 | For general information about Inline see L<Inline>. |
| 466 | |
| 467 | For sample programs using Inline with C see L<Inline::C-Cookbook>. |
| 468 | |
| 469 | For information on supported languages and platforms see |
| 470 | L<Inline-Support>. |
| 471 | |
| 472 | For information on writing your own Inline Language Support Module, see |
| 473 | L<Inline-API>. |
| 474 | |
| 475 | Inline's mailing list is inline@perl.org |
| 476 | |
| 477 | To subscribe, send email to inline-subscribe@perl.org |
| 478 | |
| 479 | =head1 BUGS AND DEFICIENCIES |
| 480 | |
| 481 | =over 4 |
| 482 | |
| 483 | =item 1 |
| 484 | |
| 485 | If you use C function names that happen to be used internally by Perl, |
| 486 | you will get a load error at run time. There is currently no |
| 487 | functionality to prevent this or to warn you. For now, a list of Perl's |
| 488 | internal symbols is packaged in the Inline module distribution under the |
| 489 | filename C<'symbols.perl'>. Avoid using these in your code. |
| 490 | |
| 491 | =back |
| 492 | |
| 493 | =head1 AUTHOR |
| 494 | |
| 495 | Brian Ingerson <INGY@cpan.org> |
| 496 | |
| 497 | =head1 COPYRIGHT |
| 498 | |
| 499 | Copyright (c) 2000, 2001, 2002. Brian Ingerson. All rights reserved. |
| 500 | |
| 501 | This program is free software; you can redistribute it and/or modify it |
| 502 | under the same terms as Perl itself. |
| 503 | |
| 504 | See http://www.perl.com/perl/misc/Artistic.html |
| 505 | |
| 506 | =cut |