| 1 |
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| 2 |
<HTML> |
| 3 |
<HEAD> |
| 4 |
<META NAME=viewport CONTENT="width=device-width, initial-scale=1"> |
| 5 |
<TITLE>Loading C Functions in Icon</TITLE> |
| 6 |
<LINK REL="STYLESHEET" TYPE="text/css" HREF="istyle.css"> |
| 7 |
<LINK REL="SHORTCUT ICON" HREF="shortcut.gif"> |
| 8 |
</HEAD> |
| 9 |
<BODY> |
| 10 |
|
| 11 |
<P> <A HREF="http://www.cs.arizona.edu/icon/"> <IMG SRC="wwwcube.gif" |
| 12 |
ALT="[Icon home]" WIDTH=128 HEIGHT=144 BORDER=0 ALIGN=RIGHT> </A> |
| 13 |
|
| 14 |
|
| 15 |
<H1> Loading C Functions in Icon</H1> |
| 16 |
|
| 17 |
<P> Gregg M. Townsend |
| 18 |
<BR> <SMALL> Department of Computer Science </SMALL> |
| 19 |
<BR> <SMALL> The University of Arizona </SMALL> |
| 20 |
|
| 21 |
<P> <SMALL> www.cs.arizona.edu/icon/uguide/cfuncs.htm |
| 22 |
<BR> Adapted from |
| 23 |
<A HREF="http://www.cs.arizona.edu/icon/analyst/backiss/IA36.pdf"> |
| 24 |
<CITE>Icon Analyst 36</CITE></A> |
| 25 |
<BR> Last updated October 27, 2009 </SMALL> |
| 26 |
|
| 27 |
|
| 28 |
<P> Dynamic loading allows Icon programs to use functions coded in C |
| 29 |
without modifying the Icon system itself. The C code is |
| 30 |
compiled and placed in a library, then loaded |
| 31 |
from the library when the Icon program runs. |
| 32 |
Here is a discussion of the use and construction of such functions. |
| 33 |
|
| 34 |
|
| 35 |
<H2> Program library functions </H2> |
| 36 |
|
| 37 |
<P> The |
| 38 |
<A HREF="http://www.cs.arizona.edu/icon/library/ipl.htm">Icon |
| 39 |
program library</A> |
| 40 |
includes an assortment of loadable Unix |
| 41 |
interfaces and special-purpose functions. |
| 42 |
Some are there for their general utility, |
| 43 |
some for illustration, and some to fill specialized needs. |
| 44 |
Here is a sampling: |
| 45 |
<BLOCKQUOTE> |
| 46 |
<CODE>bitcount(i)</CODE> — count the bits set in an integer |
| 47 |
<BR><CODE>chmod(s, i)</CODE> — change the permissions of a file |
| 48 |
<BR><CODE>fpoll(f, i)</CODE> — poll a file for input, with timeout |
| 49 |
<BR><CODE>getpid()</CODE> — return the process identification number |
| 50 |
<BR><CODE>kill(i1, i2)</CODE> — send a signal to a process |
| 51 |
<BR><CODE>lgconv(i)</CODE> — convert a large integer to a string |
| 52 |
<BR><CODE>tconnect(s, i)</CODE> — connect a file to a TCP port |
| 53 |
<BR><CODE>umask(i)</CODE> — change the process permission mask |
| 54 |
</BLOCKQUOTE> |
| 55 |
|
| 56 |
<P> The full set of functions can be found in the |
| 57 |
library's <CODE>cfuncs</CODE> directory. |
| 58 |
Documentation and code are also |
| 59 |
<A HREF="http://www.cs.arizona.edu/icon/library/fcfuncs.htm">available |
| 60 |
on line</A>. |
| 61 |
These functions are available automatically to an Icon program |
| 62 |
that includes <CODE>link cfunc</CODE>. |
| 63 |
The <CODE>bitcount()</CODE> function |
| 64 |
is a good example for detailed examination. |
| 65 |
|
| 66 |
|
| 67 |
<H2> Loading a function </H2> |
| 68 |
|
| 69 |
<P> The built-in Icon function <CODE>loadfunc(libname, funcname)</CODE> |
| 70 |
loads the C function <CODE>funcname()</CODE> from |
| 71 |
the library file <CODE>libname</CODE> and returns a procedure |
| 72 |
value. If the function cannot be loaded, the program is terminated. |
| 73 |
|
| 74 |
<P> If <CODE>loadfunc(libname, "myfunc")</CODE> produces <CODE>p</CODE>, |
| 75 |
then |
| 76 |
<UL> |
| 77 |
<LI><CODE>p(</CODE>arguments<CODE>)</CODE> calls <CODE>myfunc()</CODE> |
| 78 |
with a list of arguments |
| 79 |
<LI><CODE>type(p)</CODE> returns <CODE>"procedure"</CODE> |
| 80 |
<LI><CODE>image(p)</CODE> returns <CODE>"function myfunc"</CODE> |
| 81 |
<LI><CODE>proc("myfunc")</CODE> returns <CODE>p</CODE> |
| 82 |
<LI><CODE>proc("myfunc", 0)</CODE> fails |
| 83 |
</UL> |
| 84 |
|
| 85 |
<P> The following program loads the function |
| 86 |
<CODE>bitcount()</CODE> and assigns it to a global variable of the |
| 87 |
same name. Assigning it to a global variable makes |
| 88 |
it available to other procedures, although that's not |
| 89 |
needed here. The <CODE>bitcount()</CODE> function returns the |
| 90 |
number of bits that are set in the binary representation of an integer. |
| 91 |
<BLOCKQUOTE><PRE> |
| 92 |
$define Library "/icon/bin/libcfunc.so" |
| 93 |
global bitcount |
| 94 |
|
| 95 |
procedure main() |
| 96 |
local i |
| 97 |
bitcount := loadfunc(Library, "bitcount") |
| 98 |
every i := 250 to 260 do |
| 99 |
write(i, " ", bitcount(i)) |
| 100 |
end |
| 101 |
</PRE></BLOCKQUOTE> |
| 102 |
|
| 103 |
<P> When this program is run, it lists the integers |
| 104 |
from 250 to 260 along with their bit counts: |
| 105 |
<BLOCKQUOTE><PRE> |
| 106 |
250 6 |
| 107 |
251 7 |
| 108 |
252 6 |
| 109 |
253 7 |
| 110 |
254 7 |
| 111 |
255 8 |
| 112 |
256 1 |
| 113 |
257 2 |
| 114 |
258 2 |
| 115 |
259 3 |
| 116 |
260 2 |
| 117 |
</PRE></BLOCKQUOTE> |
| 118 |
|
| 119 |
|
| 120 |
<H2> Loading from a path </H2> |
| 121 |
|
| 122 |
<P> Embedding a file name such as <CODE>/icon/bin/libcfunc.so</CODE> |
| 123 |
in the program is undesirable. An alternative is for the |
| 124 |
program to find the library file |
| 125 |
using information from the program environment. |
| 126 |
|
| 127 |
<P> The Icon library procedure |
| 128 |
<CODE>pathload(libname, funcname)</CODE> |
| 129 |
searches the set of directories given by |
| 130 |
the <CODE>FPATH</CODE> environment variable to find <CODE>libname</CODE> |
| 131 |
and load <CODE>funcname</CODE>. |
| 132 |
As is usual in Icon path searching, the current |
| 133 |
directory is searched first. If the |
| 134 |
function cannot be loaded, the program is terminated. |
| 135 |
|
| 136 |
<P> The <CODE>pathload()</CODE> procedure is included |
| 137 |
by linking <CODE>pathfind</CODE> from the Icon program library. Using |
| 138 |
<CODE>pathload()</CODE>, the example program becomes: |
| 139 |
<BLOCKQUOTE><PRE> |
| 140 |
$define Library "libcfunc.so" |
| 141 |
link pathfind |
| 142 |
global bitcount |
| 143 |
|
| 144 |
procedure main() |
| 145 |
local i |
| 146 |
bitcount := pathload(Library, "bitcount") |
| 147 |
every i := 250 to 260 do |
| 148 |
write(i, " ", bitcount(i)) |
| 149 |
end |
| 150 |
</PRE></BLOCKQUOTE> |
| 151 |
|
| 152 |
<P> The default <CODE>FPATH</CODE> includes the current directory |
| 153 |
and the installed Icon program library directory. |
| 154 |
To find a library located elsewhere, |
| 155 |
<CODE>FPATH</CODE> must be set explicitly before the program is run. |
| 156 |
|
| 157 |
|
| 158 |
<H2> Implicit function loading </H2> |
| 159 |
|
| 160 |
<P> It is possible to encapsulate the loading process so that the body of |
| 161 |
an Icon program is unaware |
| 162 |
that it is calling a C function. Consider this example: |
| 163 |
<BLOCKQUOTE><PRE> |
| 164 |
$define Library "libcfunc.so" |
| 165 |
link pathfind |
| 166 |
|
| 167 |
procedure main() |
| 168 |
local i |
| 169 |
every i := 250 to 260 do |
| 170 |
write(i, " ", bitcount(i)) |
| 171 |
end |
| 172 |
|
| 173 |
procedure bitcount(n) |
| 174 |
bitcount := pathload(Library, "bitcount") |
| 175 |
return bitcount(n) |
| 176 |
end |
| 177 |
</PRE></BLOCKQUOTE> |
| 178 |
|
| 179 |
<P> First of all, notice that there is no longer a |
| 180 |
global declaration for <CODE>bitcount</CODE>, and that the main |
| 181 |
procedure no longer calls <CODE>pathload()</CODE>. As far as the |
| 182 |
main procedure is concerned, <CODE>bitcount()</CODE> is just |
| 183 |
another procedure to call, with no special requirements. This is a nice |
| 184 |
simplification. |
| 185 |
|
| 186 |
<P> The new <CODE>bitcount()</CODE> procedure is a bit tricky, |
| 187 |
though. To understand it, you must know that an |
| 188 |
Icon procedure declaration creates a global variable with an initial |
| 189 |
value of that procedure. A |
| 190 |
global variable is subject to assignment. |
| 191 |
|
| 192 |
<P> When <CODE>main()</CODE> calls <CODE>bitcount()</CODE> for the first time, |
| 193 |
the <CODE>bitcount()</CODE> procedure loads the <CODE>bitcount()</CODE> |
| 194 |
C function from the library. The result is assigned to the |
| 195 |
global variable <CODE>bitcount</CODE>, replacing the current procedure value. |
| 196 |
Consequently, all subsequent calls |
| 197 |
to <CODE>bitcount()</CODE> use the loaded function. |
| 198 |
|
| 199 |
<P> The first call to <CODE>bitcount()</CODE> remains incomplete |
| 200 |
after loading the function; the bits of <CODE>n</CODE> still must be |
| 201 |
counted. So, following loading, the procedure calls |
| 202 |
<CODE>bitcount(n)</CODE>. Although this looks like a recursive |
| 203 |
call, it isn't — the call uses the current value of the |
| 204 |
global variable <CODE>bitcount</CODE>, and so it calls the loaded C |
| 205 |
function. The bits of <CODE>n</CODE> are counted and returned, |
| 206 |
completing the first call. |
| 207 |
|
| 208 |
<P> After the first time, calls to <CODE>bitcount()</CODE> |
| 209 |
go directly to the loaded code. The Icon procedure |
| 210 |
<CODE>bitcount()</CODE> is no longer accessible. |
| 211 |
|
| 212 |
|
| 213 |
<H2> Implicit library loading </H2> |
| 214 |
|
| 215 |
<P> The Icon program library provides an implicit loading procedure for |
| 216 |
each of the C functions |
| 217 |
in the library. Small procedures like the <CODE>bitcount()</CODE> |
| 218 |
procedure shown above are included by linking |
| 219 |
<CODE>cfunc</CODE>. Using the library interface procedure, our |
| 220 |
example now can be simplified to this: |
| 221 |
<BLOCKQUOTE><PRE> |
| 222 |
link cfunc |
| 223 |
|
| 224 |
procedure main() |
| 225 |
local i |
| 226 |
every i := 250 to 260 do |
| 227 |
write(i, " ", bitcount(i)) |
| 228 |
end |
| 229 |
</PRE></BLOCKQUOTE> |
| 230 |
|
| 231 |
<P> The <CODE>link cfunc</CODE> declaration is the only hint that |
| 232 |
<CODE>bitcount()</CODE> is written in C. |
| 233 |
|
| 234 |
|
| 235 |
<H2> Making connections </H2> |
| 236 |
|
| 237 |
<P> The bit counting example doesn't really illustrate the full potential |
| 238 |
of using C functions in an |
| 239 |
Icon program. Bit counting, after all, can be done in |
| 240 |
Icon. Here's something that can't. |
| 241 |
|
| 242 |
<P> The library function |
| 243 |
<CODE>tconnect(host, port)</CODE> establishes a TCP connection |
| 244 |
to a specified port |
| 245 |
number on an Internet host. TCP is a communication protocol used by |
| 246 |
telnet programs, news servers, web servers, and many other network |
| 247 |
services. |
| 248 |
|
| 249 |
<P> The following program makes a connection |
| 250 |
to the Icon web server and writes the contents of |
| 251 |
the Icon home page — in its original HTML markup |
| 252 |
language, of course. |
| 253 |
<BLOCKQUOTE><PRE> |
| 254 |
link cfunc |
| 255 |
|
| 256 |
procedure main() |
| 257 |
local f |
| 258 |
f := tconnect("www.cs.arizona.edu", 80) |
| 259 |
writes(f, "GET /icon/ HTTP/1.0\n\n") |
| 260 |
flush(f) |
| 261 |
seek(f, 1) |
| 262 |
while write(read(f)) |
| 263 |
end |
| 264 |
</PRE></BLOCKQUOTE> |
| 265 |
|
| 266 |
<P> The <CODE>tconnect()</CODE> call establishes the connection |
| 267 |
and returns a file that is open for both input and |
| 268 |
output. The internet host <CODE>www.cs.arizona.edu</CODE> is |
| 269 |
the web server for the University of Arizona's |
| 270 |
Department of Computer Science. |
| 271 |
(Port 80 is the standard web server port number.) |
| 272 |
The program then transmits a request for the |
| 273 |
<CODE>/icon/</CODE> web page. The details of the request string |
| 274 |
are specified by the |
| 275 |
<A HREF="http://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext |
| 276 |
Transfer Protocol</A>, not discussed here. |
| 277 |
|
| 278 |
<P> The <CODE>flush()</CODE> call ensures that all the data is |
| 279 |
actually sent, and then the <CODE>seek()</CODE> call resets the file |
| 280 |
in preparation for a switch from output to input. In |
| 281 |
this situation <CODE>seek()</CODE> does not actually reposition |
| 282 |
the file, but it's required when switching modes. |
| 283 |
|
| 284 |
<P> Finally, lines are read and echoed until an |
| 285 |
end-of-file is received. |
| 286 |
|
| 287 |
|
| 288 |
<H2> Writing loadable C functions </H2> |
| 289 |
|
| 290 |
<P> Now consider the construction of library functions. |
| 291 |
Because the Icon system expects C functions |
| 292 |
to implement a certain interface, dynamic loading |
| 293 |
usually requires specially written C functions. In |
| 294 |
general, it is not possible to use an existing C |
| 295 |
function without writing an intermediate "glue" |
| 296 |
function. |
| 297 |
|
| 298 |
<P> C functions must deal with the data types |
| 299 |
used by the Icon run-time system, notably the |
| 300 |
"descriptors" that represent all Icon values. While |
| 301 |
an understanding of |
| 302 |
<A HREF="http://www.cs.arizona.edu/icon/ibsale.htm">the |
| 303 |
Icon run-time system</A> is helpful, |
| 304 |
it is possible to create useful functions by |
| 305 |
modeling them after existing library functions. |
| 306 |
Integer and string values are most easily handled. |
| 307 |
|
| 308 |
<P> A loadable C function has the prototype |
| 309 |
<BLOCKQUOTE><CODE>int funcname(int argc, descriptor *argv)</CODE></BLOCKQUOTE> |
| 310 |
where <CODE>argc</CODE> is the number of arguments and <CODE>argv</CODE> is |
| 311 |
an array of argument descriptors. |
| 312 |
The first element, <CODE>argv[0]</CODE>, is used to return an Icon value, and |
| 313 |
is initialized to a descriptor for the null value. This |
| 314 |
element is not included in the count <CODE>argc</CODE>. The |
| 315 |
actual arguments begin with <CODE>argv[1]</CODE>. |
| 316 |
|
| 317 |
<P> If the C function returns zero, the call from |
| 318 |
Icon succeeds. A negative value indicates failure. If |
| 319 |
a positive value is returned, it is interpreted as an |
| 320 |
error number and a fatal error with that number is |
| 321 |
signalled. In this case, if <CODE>argv[0]</CODE> is non-null, it is |
| 322 |
reported as the "offending value". There is no way |
| 323 |
for a C function to suspend, and no way to indicate |
| 324 |
a null value as an offending value in the case of an |
| 325 |
error. |
| 326 |
|
| 327 |
|
| 328 |
<H2> Interface macros </H2> |
| 329 |
|
| 330 |
<P> The C file <CODE>icall.h</CODE> contains a set of macros for |
| 331 |
use in writing loadable functions. Documentation |
| 332 |
is included as comments. This file can be found in the |
| 333 |
<CODE>cfuncs</CODE> directory in the source code of the Icon |
| 334 |
program library. Alternatively, it can be loaded |
| 335 |
<A HREF="http://www.cs.arizona.edu/icon/library/src/cfuncs/icall.h">from |
| 336 |
the web</A>. Macros are provided for: |
| 337 |
<UL> |
| 338 |
<LI>inspecting the type of an Icon value |
| 339 |
<LI>validating the type of an argument |
| 340 |
<LI>converting an Icon value into a C value |
| 341 |
<LI>returning a C value in Icon form |
| 342 |
<LI>failing or signaling an error |
| 343 |
</UL> |
| 344 |
|
| 345 |
<P> Most macros deal with integers or strings. |
| 346 |
Some support also is provided for handling real |
| 347 |
and file values. |
| 348 |
The macros expect the C arguments to be declared with the |
| 349 |
names of <CODE>argc</CODE> and <CODE>argv</CODE>. |
| 350 |
|
| 351 |
|
| 352 |
<H2> Counting bits, again </H2> |
| 353 |
|
| 354 |
<P> For a concrete example of a C function, consider the source code |
| 355 |
of the <CODE>bitcount()</CODE> function used earlier: |
| 356 |
<BLOCKQUOTE><PRE> |
| 357 |
#include "icall.h" |
| 358 |
|
| 359 |
int bitcount(int argc, descriptor *argv) |
| 360 |
{ |
| 361 |
unsigned long v; |
| 362 |
int n; |
| 363 |
ArgInteger(1); |
| 364 |
v = IntegerVal(argv[1]); |
| 365 |
n = 0; |
| 366 |
while (v != 0) { |
| 367 |
n += v & 1; |
| 368 |
v >>= 1; |
| 369 |
} |
| 370 |
RetInteger(n); |
| 371 |
} |
| 372 |
</PRE></BLOCKQUOTE> |
| 373 |
|
| 374 |
<P> Like all loadable functions, <CODE>bitcount()</CODE> is an |
| 375 |
integer function with two parameters, <CODE>argc</CODE> and |
| 376 |
<CODE>argv</CODE>. |
| 377 |
|
| 378 |
<P> The <CODE>ArgInteger</CODE> macro call verifies that argument 1 is a simple |
| 379 |
integer. (Large integers are |
| 380 |
typically rejected by C functions because of the |
| 381 |
extra work involved.) If argument 1 is missing or |
| 382 |
has the wrong type, <CODE>ArgInteger</CODE> makes the function |
| 383 |
return error code 101 (integer expected or out of |
| 384 |
range). |
| 385 |
|
| 386 |
<P> The <CODE>IntegerVal</CODE> macro call extracts the value |
| 387 |
of the first argument. |
| 388 |
|
| 389 |
<P> In each pass through the <CODE>while</CODE> loop, the low order bit of |
| 390 |
<CODE>v</CODE> is |
| 391 |
extracted (<CODE>v & 1</CODE>), added to <CODE>n</CODE>, and |
| 392 |
shifted off (<CODE>v >>= 1</CODE>). When no more nonzero bits |
| 393 |
are left, the loop exits. Note that <CODE>v</CODE> is declared |
| 394 |
unsigned to ensure that only zero bits are inserted |
| 395 |
by the shift operation. |
| 396 |
|
| 397 |
<P> The <CODE>RetInteger</CODE> macro call returns the value |
| 398 |
of <CODE>n</CODE> as an Icon integer. |
| 399 |
|
| 400 |
|
| 401 |
<H2> External data values </H2> |
| 402 |
|
| 403 |
<P> Loadable functions can create and return data structures |
| 404 |
that are treated as an opaque <CODE>external</CODE> type by Icon. |
| 405 |
The use of external types is described <A HREF="extlvals.htm">separately</A>. |
| 406 |
|
| 407 |
|
| 408 |
<H2> Preparing a library </H2> |
| 409 |
|
| 410 |
<P> To be used in an Icon program, a C function |
| 411 |
must be built and installed in a library. Compilation comes first, |
| 412 |
usually involving a command such as |
| 413 |
<BLOCKQUOTE><CODE>cc –c bitcount.c</CODE></BLOCKQUOTE> |
| 414 |
to produce an object file <CODE>bitcount.o</CODE>. |
| 415 |
The <CODE>–c</CODE> option causes a relocatable object file |
| 416 |
to be produced instead of a stand-alone executable program. |
| 417 |
If <CODE>icall.h</CODE> is not in the current directory, |
| 418 |
an additional option may be needed to specify its location. |
| 419 |
Other options, such as optimization options, also could be specified. |
| 420 |
|
| 421 |
<P> A C function can be loaded only from a "shared library". |
| 422 |
Even if there is just one function, it must be placed in a library. |
| 423 |
Library names conventionally end with a <CODE>.so</CODE> suffix. |
| 424 |
|
| 425 |
<P> It seems that every system has a different |
| 426 |
way to create libraries, usually involving special |
| 427 |
flags to <CODE>cc</CODE> or <CODE>ld</CODE>. |
| 428 |
The shell script <CODE>mklib.sh</CODE> |
| 429 |
embodies our understanding of shared library creation. |
| 430 |
It takes one argument naming the library to be created and one or more |
| 431 |
additional arguments listing object file names. |
| 432 |
For example, the command |
| 433 |
<BLOCKQUOTE><CODE>mklib.sh mylib.so bitcount.o</CODE></BLOCKQUOTE> |
| 434 |
creates a file <CODE>mylib.so</CODE> containing the functions read |
| 435 |
from <CODE>bitcount.o</CODE>. |
| 436 |
Like <CODE>icall.h</CODE>, <CODE>mklib.sh</CODE> is available in |
| 437 |
the program library source code or |
| 438 |
<A HREF="http://www.cs.arizona.edu/icon/library/src/cfuncs/mklib.sh">from |
| 439 |
the web</A>. |
| 440 |
|
| 441 |
|
| 442 |
<H2> Summary </H2> |
| 443 |
|
| 444 |
<UL> |
| 445 |
<LI> Icon programs can load and call functions written in C. |
| 446 |
<LI> The C functions must be tailored to Icon's requirements. |
| 447 |
<LI> Each function must be loaded before it can be called. |
| 448 |
<LI> A simple Icon procedure can be used to hide the loading details. |
| 449 |
<LI> <CODE>pathload()</CODE> searches <CODE>FPATH</CODE> |
| 450 |
to find a function library. |
| 451 |
<LI> C functions can embed data in opaque <CODE>external</CODE> values. |
| 452 |
<LI> Some useful functions are provided in the Icon program library. |
| 453 |
</UL> |
| 454 |
|
| 455 |
<HR> |
| 456 |
|
| 457 |
</BODY> |
| 458 |
</HTML> |