dlperl/dlperl.doc

   1
   2
   3
   4 DLPERL(1)                USER COMMANDS                  DLPERL(1)
   5
   6
   7
   8 NAME
   9      dlperl - dynamic link-editor subroutines for perl
  10
  11 SYNOPSIS
  12      $dl_so = &dl_open($file)
  13      $dl_func = &dl_sym($dl_so, $symbol)
  14      @vals = &dl_call($dl_func, $parms_desc, $return_desc, @parms)
  15      $dl_err = &dl_close($dl_so)
  16
  17      $DL_VERSION
  18      $DL_WARN
  19      $dl_errno
  20      $dl_errstr
  21
  22 DESCRIPTION
  23      _\bD_\bl_\bp_\be_\br_\bl is _\bp_\be_\br_\bl plus user defined  subroutines  (_\bu_\bs_\bu_\bb_\bs)  that
  24      interface to the dynamic link-editor and can call most C and
  25      Fortran functions whose object code has been linked  into  a
  26      shared object file.
  27
  28      Subroutines
  29
  30      All  _\bd_\bl_\bp_\be_\br_\bl  subroutines  set  the  two   predefined   names
  31      $dl_errno  and  $dl_errstr.   Only  partial  descriptions of
  32      &dl_open, &dl_sym and &dl_close appear below, see _\bd_\bl_\bo_\bp_\be_\bn(_\b3_\bx)
  33      for  a  complete description.  The following subroutines are
  34      defined by _\bd_\bl_\bp_\be_\br_\bl:
  35
  36      &dl_open($file)
  37              Adds the shared object  $_\bf_\bi_\bl_\be  to  _\bd_\bl_\bp_\be_\br_\bl's  address
  38              space.   Returns  a  descriptor that can be used for
  39              later reference to the object in  calls  to  &dl_sym
  40              and  &dl_close.  When an error occurs an undef value
  41              is returned.
  42
  43      &dl_sym($dl_so, $symbol)
  44              Obtains an address binding for the function  $_\bs_\by_\bm_\bb_\bo_\bl
  45              as  it  occurs  in  the  shared object identified by
  46              $_\bd_\bl__\bs_\bo.  When an error  occurs  an  undef  value  is
  47              returned.
  48
  49      &dl_call($dl_func, $parms_desc, $return_desc, @parms)
  50              Calls the  function  identified  by  $_\bd_\bl__\bf_\bu_\bn_\bc.   The
  51              function's   entry   parameters   are  described  by
  52              $_\bp_\ba_\br_\bm_\bs__\bd_\be_\bs_\bc and assigned values  from  @_\bp_\ba_\br_\bm_\bs.   The
  53              function's  exit value is described by $_\br_\be_\bt_\bu_\br_\bn__\bd_\be_\bs_\bc.
  54              An array is returned that contains the values of any
  55              result  parameters  and  the  return value.  When an
  56              error  occurs  because  of  a  problem  parsing  the
  57              descriptions  or  because  of an incorrect parameter
  58              count no values are returned (although the  underly-
  59              ing function may have been called).
  60
  61
  62
  63 Sun Release 4.1       Last change: 10/16/92                     1
  64
  65
  66
  67
  68
  69
  70 DLPERL(1)                USER COMMANDS                  DLPERL(1)
  71
  72
  73
  74              The descriptions are sequences  of  characters  that
  75              give the order and type of parameters:
  76
  77                   c    A signed char value.
  78                   C    An unsigned char value.
  79                   s    A signed short value.
  80                   S    An unsigned short value.
  81                   i    A signed integer value.
  82                   I    An unsigned integer value.
  83                   l    A signed long value.
  84                   L    An unsigned long value.
  85                   f    A single-precision float.
  86                   d    A double-precision float.
  87                   a    An ascii (null-terminated) string.
  88                   p    A pointer to <length> buffer.
  89
  90              Each letter may optionally be preceded by  a  number
  91              that gives a repeat count.  An array is specified by
  92              a preceding [_\ba_\br_\br_\ba_\by__\bs_\bi_\bz_\be] (or & as  a  shorthand  for
  93              [_\b1]).   (Multi-dimension  arrays  are  not currently
  94              supported.)  Each scalar or array  element  is  ini-
  95              tialized  from  @_\bp_\ba_\br_\bm_\bs.   A  preceding  - leaves the
  96              parameter uninitialized.  Type _\bp expects a preceding
  97              <_\bb_\bu_\bf_\bf_\be_\br__\bl_\be_\bn_\bg_\bt_\bh>.  A preceding + specifies that after
  98              the function is called that  particular  parameter's
  99              value   is  to  be  returned  (multiple  values  are
 100              returned for array types, a + with a  integral  type
 101              like  _\bi  returns  an undef value).  The $_\br_\be_\bt_\bu_\br_\bn__\bd_\be_\bs_\bc
 102              contains only one letter with no repeat count, -  or
 103              +.
 104
 105              An undef or zero-length $_\bp_\ba_\br_\bm__\bd_\be_\bs_\bc means  the  func-
 106              tion  has  no parameters.  An undef or a zero-length
 107              $_\br_\be_\bt_\bu_\br_\bn__\bd_\be_\bs_\bc  means  the  function   returns   void.
 108              Strings  or  buffers  that must be a specific length
 109              (because the values are overwritten)  must  be  pre-
 110              extended.   Although  type _\bf is supported, compilers
 111              typically pass floats as doubles.
 112
 113      &dl_close($dl_so)
 114              Removes the shared object identified by $_\bd_\bl__\bs_\bo  from
 115              _\bd_\bl_\bp_\be_\br_\bl's  address  space.  If successful, a value of
 116              zero is returned.  When an error occurs  a  non-zero
 117              value is returned.
 118
 119      Predefined Names
 120
 121      The following names have special meaning to _\bd_\bl_\bp_\be_\br_\bl.
 122
 123      $DL_VERSION
 124              The version of _\bd_\bl_\bp_\be_\br_\bl.  This variable is read-only.
 125
 126
 127
 128
 129 Sun Release 4.1       Last change: 10/16/92                     2
 130
 131
 132
 133
 134
 135
 136 DLPERL(1)                USER COMMANDS                  DLPERL(1)
 137
 138
 139
 140      $DL_WARN
 141              The  current  value  of  the  _\bd_\bl_\bp_\be_\br_\bl  warning  flag.
 142              Default  is 1.  If non-zero, when errors occur warn-
 143              ings are sent to standard error.  The warning is the
 144              same information that is stored in $dl_errstr.
 145
 146      $dl_errno
 147              The error number for the error that occurred.  If  a
 148              _\bd_\bl_\bp_\be_\br_\bl  subroutine  completes successfully $dl_errno
 149              is set to zero.  This variable is read-only.
 150
 151      $dl_errstr
 152              The error message for the error that occurred.  If a
 153              _\bd_\bl_\bp_\be_\br_\bl  subroutine completes successfully $dl_errstr
 154              is set to a zero length string.   This  variable  is
 155              read-only.
 156
 157 EXAMPLES
 158      This is an example of calling a simple C function:
 159
 160           open(OUT, ">example.c");
 161           print OUT <<'EOC';
 162                void
 163                example(a1, a2, i1, d1, a3)
 164                char *a1[2];
 165                char *a2[2];
 166                int  i1;
 167                double    *d1;
 168                char *a3[4];
 169                {
 170                     a3[i1 + (int) *d1] = a1[0];
 171                     a3[i1 * (int) *d1] = a1[1];
 172                     a3[(int) *d1 - i1] = a2[0];
 173                     a3[(int) *d1 - 2 * i1] = a2[1];
 174                }
 175           EOC
 176           close(OUT);
 177
 178           system("cc -c example.c;ld -o example.so example.o");
 179
 180           $dl_so = &dl_open("example.so");
 181           die "$0: $dl_errstr" if($dl_errno);
 182
 183           $dl_func = &dl_sym($dl_so, "example");
 184           die "$0: $dl_errstr" if($dl_errno);
 185
 186           $dl_func =~ s/(['\\])/\\$1/g;
 187           eval <<EOC;
 188                sub example {
 189                     &dl_call('$dl_func', "2[2]a i &d -+[4]a", undef, @_);
 190                }
 191           EOC
 192
 193
 194
 195 Sun Release 4.1       Last change: 10/16/92                     3
 196
 197
 198
 199
 200
 201
 202 DLPERL(1)                USER COMMANDS                  DLPERL(1)
 203
 204
 205
 206           @vals = &example("hacker,", "Perl", "another", "Just", 1, 2);
 207           print "@vals\n";
 208
 209           &dl_close($dl_so);
 210           die "$0: $dl_errstr" if($dl_errno);
 211
 212           unlink('example.c', 'example.o', 'example.so');
 213
 214      If a more complicated interface is needed,  the  dynamically
 215      linked  function  can  define _\bu_\bs_\bu_\bb_\bs by calling internal _\bp_\be_\br_\bl
 216      functions.
 217
 218 AUTHOR
 219      Eric Fifer <egf@sbi.com>
 220
 221 SEE ALSO
 222      perl(1), dlopen(3X), ld(1)
 223
 224 BUGS
 225      Additional parameter types should be implemented to  support
 226      structures,  multi-dimension  arrays,  pointers  to  arrays,
 227      pointers to functions, etc.
 228
 229      Unlike the _\bp_\ba_\bc_\bk operator,  the  repeat  count  precedes  the
 230      letter  in  the $_\bp_\ba_\br_\bm__\bd_\be_\bs_\bc syntax.  The array size preceding
 231      the parameter letter is also unconventional.
 232
 233      All errors set $dl_errno to 1.
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261 Sun Release 4.1       Last change: 10/16/92                     4
 262
 263
 264