Calling C Functions from Version 9 of Icon

Department of Computer Science The University of Arizona Tucson, Arizona IPD240b March 14, 1996 http://www.cs.arizona.edu/icon/docs/ipd240.htm

1. Introduction

2. External Functions

dptr extcall(dptr argv, int argc, int *ip)

Designating C Functions

Error Handling

3. Dynamic Loading

SunOS 4.x:

ld -o lib.so file1.o file2.o



Solaris 2.x:

cc -G -K pic -o lib.so file1.o file2.o



Dec OSF1 v2.x:

ld -shared -expect unresolved '*' -o lib.so file1.o file2.o -lc



SGI Irix 5.x:

ld -shared -o lib.so file1.o file2.o



FreeBSD:

ld -Bshareable -o lib.so file1.o file2.o -lc

The C Function Interface

int funcname(int argc, dptr argv)

4. Data Interface

cnv_int(dp1, dp2)

Converts the value in the descriptor pointed to by dp1 to an integer descriptor pointed to by dp2, returning 0 if the conversion cannot be performed.

cnv_str(dp1, dp2)

Converts the value in the descriptor pointed to by dp1 to a string string descriptor (qualifier) pointed to by dp2, returning 0 if the conversion cannot be performed.

cnv_real(dp1, dp2)

Converts the value in the descriptor pointed to by dp1 to a real number descriptor (floating-point double) pointed to by dp2, returning 0 if the conversion fails.

Qual(d)

Tests if d is a descriptor for a string.

IntVal(d)

Accesses the (long) integer value of the integer descriptor d.

MakeInt(i, dp)

Constructs a integer descriptor pointed to by dp from the (long) integer i.

StrLen(d)

Accesses the length of the string in the descriptor d.

StrLoc(d)

Accesses the address of the string in the descriptor d.

qtos(dp, sbuf)

Constructs a C-style string from the descriptor pointed to by dp, placing it in sbuf, a buffer of length MaxCvtLen, if it is small enough or in the allocated string region if it is not. If there is not enough space available in the allocated string region, Error is returned.

alcstr(sbuf, i)

Copies the string of length i in sbuf to the allocated string region, returning NULL if the requested amount of space is not available.

GetReal(dp, r)

Places the floating-point double from the descriptor pointed to by dp into r.

nulldesc

descriptor for the null value

zerodesc

descriptor for the Icon integer 0

onedesc

descriptor for the Icon integer 1

emptystr

descriptor for the empty string

Acknowledgements

References

Appendix A -- External Function Examples

Example 1: Functions Designated by Numbers

#if !COMPILER
#ifdef ExternalFunctions
/*
 * Example of calling C functions by integer codes.  Here it's
 *  one of three UNIX functions:
 *
 *    1: getpid (get process identification)
 *    2: getppid (get parent process identification)
 *    3: getpgrp (get process group)
 */

struct descrip retval;        /* for returned value */

dptr extcall(dargv, argc, ip)
dptr dargv;
int argc;
int *ip;
   {
   int retcode;
   int getpid(), getppid(), getpgrp();

   if (!cnv_int(dargv, dargv)) {/* 1st argument must be a string */
      *ip = 101;              /* "integer expected" error number */
      return dargv;           /* return offending value */
      }

   switch ((int)IntVal(*dargv)) {
      case 1:                 /* getpid */
         retcode = getpid();
         break;

      case 2:                 /* getppid */
         retcode = getppid();
         break;

      case 3:                 /* getpgrp */
         if (argc < 2) {
            *ip = 205;        /* no error number fits, really */
            return NULL;      /* no offending value */
            }
         dargv++;             /* get to next value */
         if (!cnv_int(dargv, dargv)) {/* 2nd argument must be integer */
            *ip = 101;        /* "integer expected" error number */
            return dargv;
            }
         retcode = getpgrp(IntVal(*dargv));
         break;

      default:
         *ip = 216;           /* external function not found */
         return NULL;
      }

   MakeInt(retcode,&retval);  /* make an Icon integer for result */
   return &retval;
   }
#else ExternalFunctions
static char x;                /* prevent empty module */
#endif                        /* ExternalFunctions */
#endif                        /* COMPILER */

Example 2: Functions Designated by Name

#if !COMPILER
#ifdef ExternalFunctions
/*
 * Example of calling C functions by their names.  Here it's just
 *  chdir (change directory) or getwd (get path of current working directory).
 */

struct descrip retval;        /* for returned value */

dptr extcall(dargv, argc, ip)
dptr dargv;
int argc;
int *ip;
   {
   int len, retcode;
   int chdir(), getwd();
   char sbuf[MaxCvtLen];

   *ip = -1;                  /* anticipate error-free execution */

   if (!cnv_str(dargv, dargv)) {/* 1st argument must be a string */
      *ip = 103;              /* "string expected" error number */
      return dargv;           /* return offending value */
      }

   if (strncmp("chdir", StrLoc(*dargv), StrLen(*dargv)) == 0) {
      if (argc < 2) {         /* must be a 2nd argument */
         *ip = 103;           /* no error number fits, really */
         return NULL;         /* no offending value */
         }
      dargv++;                /* get to next argument */
      if (!cnv_str(dargv, dargv)) {/* 2nd argument must be a string */
         *ip = 103;           /* "string expected" error number */
         return dargv;        /* return offending value */
         }
      qtos(dargv,sbuf);       /* get C-style string in sbuf2 */
      retcode = chdir(sbuf);  /* try to change directory */
      if (retcode == -1)      /* see if chdir failed */
         return (dptr)NULL;   /* signal failure */
      return &zerodesc;       /* not a very useful result */
      }
   else if (strncmp("getwd", StrLoc(*dargv), StrLen(*dargv)) == 0) {
      dargv++;                /* get to next argument */
      retcode = getwd(sbuf);  /* get current working directory */
      if (retcode == 0)       /* see if getwd failed */
         return NULL;         /* signal failure */
      len = strlen(sbuf);     /* length of resulting string */
      StrLoc(retval) = alcstr(sbuf,len);  /* allocate and copy the string */
      if (StrLoc(retval) == NULL) {/* allocation may fail */
          *ip = 0;
          return (dptr)NULL;  /* no offending value */
          }
      StrLen(retval) = len;
      return &retval;         /* return a pointer to the qualifier */
      }
   else {
      *ip = 216;              /* name is not one of those supported here */
      return dargv;           /* return pointer to offending value */
      }
   }
#else                         /* ExternalFunctions */
static char x;                /* avoid empty module */
#endif                        /* ExternalFunctions */
#endif                        /* !COMPILER */

Appendix B -- Dynamic Loading Example

Icon Program

#  Demonstrate dynamic loading of bitcount() function

global bitcount

procedure main()
   local i

   bitcount := loadfunc("./lib.so", "bitcount")
   every i := 500 to 520 do
      write(i, "  ", bitcount(i))
end

C Function

/*
 *  bitcount(i) -- count the bits in an integer
 */

#include "rt.h"

int bitcount(argc, argv)
int argc;
struct descrip *argv;
   {
   struct descrip d;
   unsigned long v;
   int n;

   if (argc < 1)
      return 101;             /* integer expected */

   if (!cnv_int(&argv[1], &d)) {
      argv[0] = argv[1];      /* offending value */
      return 101;             /* integer expected */
      }

   v = IntVal(argv[1]);       /* get value as unsigned long */
   n = 0;
   while (v != 0) {           /* while more bits to count */
      n += v & 1;             /*    check low-order bit */
      v >>= 1;                /*    shift off with zero-fill */
      }

   MakeInt(n, &argv[0]);      /* construct result integer */
   return 0;                  /* success */
   }

Icon home page