diff options
Diffstat (limited to 'dlperl/dlperl.man')
| -rw-r--r-- | dlperl/dlperl.man | 219 |
1 files changed, 219 insertions, 0 deletions
diff --git a/dlperl/dlperl.man b/dlperl/dlperl.man new file mode 100644 index 0000000000..8879133ca2 --- /dev/null +++ b/dlperl/dlperl.man @@ -0,0 +1,219 @@ +.\" +.\" name: dlperl.man +.\" synopsis: dlperl man page +.\" sccsid: @(#)dlperl.man 1.4 10/16/92 (DLPERL) +.\" +.ds RP 10/16/92 +.rn '' }` +.de Sh +.br +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp +.if t .sp .5v +.if n .sp +.. +.de Ip +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +''' +''' Set up \*(-- to give an unbreakable dash; +''' string Tr holds user defined translation string. +''' Bell System Logo is used as a dummy character. +''' +.tr \(*W-|\(bv\*(Tr +.ie n \{\ +.ds -- \(*W- +.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 L' ' +.ds R' ' +'br\} +.el\{\ +.ds -- \(em\| +.tr \*(Tr +.ds L" `` +.ds R" '' +.ds L' ` +.ds R' ' +'br\} +.TH DLPERL 1 "\*(RP" +.UC +.SH NAME +dlperl \- dynamic link-editor subroutines for perl +.SH SYNOPSIS +.nf +.ft B +$dl_so = &dl_open($file) +$dl_func = &dl_sym($dl_so, $symbol) +@vals = &dl_call($dl_func, $parms_desc, $return_desc, @parms) +$dl_err = &dl_close($dl_so) +.ft +.fi +.LP +.nf +.ft B +$DL_VERSION +$DL_WARN +$dl_errno +$dl_errstr +.ft +.fi +.SH DESCRIPTION +.I Dlperl +is \fIperl\fP plus user defined subroutines (\fIusubs\fP) that +interface to the dynamic link-editor and can call most C and Fortran +functions whose object code has been linked into a shared object file. +.Sh "Subroutines" +All \fIdlperl\fP subroutines set the two predefined names $dl_errno and +$dl_errstr. Only partial descriptions of &dl_open, &dl_sym and +&dl_close appear below, see \fIdlopen(3x)\fP for a complete +description. The following subroutines are defined by \fIdlperl\fP: +.Ip "&dl_open($file)" 8 2 +Adds the shared object \fI$file\fP to \fIdlperl\fP's address space. +Returns a descriptor that can be used for later reference to the object +in calls to &dl_sym and &dl_close. When an error occurs +an undef value is returned. +.Ip "&dl_sym($dl_so, $symbol)" 8 2 +Obtains an address binding for the function \fI$symbol\fP as it occurs +in the shared object identified by \fI$dl_so\fP. When an error occurs +an undef value is returned. +.Ip "&dl_call($dl_func, $parms_desc, $return_desc, @parms)" 8 2 +Calls the function identified by \fI$dl_func\fP. The function's entry +parameters are described by \fI$parms_desc\fP and assigned values from +\fI@parms\fP. The function's exit value is described by +\fI$return_desc\fP. An array is returned that contains the values of +any result parameters and the return value. When an error occurs +because of a problem parsing the descriptions or because of an +incorrect parameter count no values are returned (although the +underlying function may have been called). +.Sp +The descriptions are sequences of characters that give the order and +type of parameters: +.nf + + c A signed char value. + C An unsigned char value. + s A signed short value. + S An unsigned short value. + i A signed integer value. + I An unsigned integer value. + l A signed long value. + L An unsigned long value. + f A single-precision float. + d A double-precision float. + a An ascii (null-terminated) string. + p A pointer to <length> buffer. + +.fi +Each letter may optionally be preceded by a number that gives a repeat +count. An array is specified by a preceding \fI[array_size\fP] (or +\fI&\fP as a shorthand for \fI[1]\fP). (Multi-dimension arrays are not +currently supported.) Each scalar or array element is initialized from +\fI@parms\fP. A preceding \fI-\fP leaves the parameter uninitialized. +Type \fIp\fP expects a preceding \fI<buffer_length>\fP. A preceding +\fI+\fP specifies that after the function is called that particular +parameter's value is to be returned (multiple values are returned for +array types, a \fI+\fP with a integral type like \fIi\fP returns an +undef value). The \fI$return_desc\fP contains only one letter with no +repeat count, \fI-\fP or \fI+\fP. +.Sp +An undef or zero-length \fI$parm_desc\fP means the function has no +parameters. An undef or a zero-length \fI$return_desc\fP means the +function returns void. Strings or buffers that must be a specific +length (because the values are overwritten) must be pre-extended. +Although type \fIf\fP is supported, compilers typically pass floats as +doubles. +.Ip "&dl_close($dl_so)" 8 2 +Removes the shared object identified by \fI$dl_so\fP from +\fIdlperl\fP's address space. If successful, a value of zero is +returned. When an error occurs a non-zero value is returned. +.Sh "Predefined Names" +The following names have special meaning to \fIdlperl\fP. +.Ip $DL_VERSION 8 +The version of \fIdlperl\fP. This variable is read-only. +.Ip $DL_WARN 8 +The current value of the \fIdlperl\fP warning flag. Default is 1. If +non-zero, when errors occur warnings are sent to standard error. The +warning is the same information that is stored in $dl_errstr. +.Ip $dl_errno 8 +The error number for the error that occurred. If a \fIdlperl\fP +subroutine completes successfully $dl_errno is set to zero. This variable +is read-only. +.Ip $dl_errstr 8 +The error message for the error that occurred. If a \fIdlperl\fP +subroutine completes successfully $dl_errstr is set to a zero length +string. This variable is read-only. +.SH EXAMPLES +This is an example of calling a simple C function: +.Sp +.nf + open(OUT, ">example.c"); + print OUT <<'EOC'; + void + example(a1, a2, i1, d1, a3) + char *a1[2]; + char *a2[2]; + int i1; + double *d1; + char *a3[4]; + { + a3[i1 + (int) *d1] = a1[0]; + a3[i1 * (int) *d1] = a1[1]; + a3[(int) *d1 - i1] = a2[0]; + a3[(int) *d1 - 2 * i1] = a2[1]; + } + EOC + close(OUT); + + system("cc -c example.c;ld -o example.so example.o"); + + $dl_so = &dl_open("example.so"); + die "$0: $dl_errstr" if($dl_errno); + + $dl_func = &dl_sym($dl_so, "example"); + die "$0: $dl_errstr" if($dl_errno); + + $dl_func =~ s/(['\e\e])/\e\e$1/g; + eval <<EOC; + sub example { + &dl_call('$dl_func', "2[2]a i &d -+[4]a", undef, @_); + } + EOC + + @vals = &example("hacker,", "Perl", "another", "Just", 1, 2); + print "@vals\en"; + + &dl_close($dl_so); + die "$0: $dl_errstr" if($dl_errno); + + unlink('example.c', 'example.o', 'example.so'); +.fi +.LP +If a more complicated interface is needed, the dynamically linked +function can define \fIusubs\fP by calling internal \fIperl\fP +functions. +.SH AUTHOR +Eric Fifer <egf@sbi.com> +.SH SEE ALSO +.BR perl (1), +.BR dlopen (3X), +.BR ld (1) +.SH BUGS +Additional parameter types should be implemented to support structures, +multi-dimension arrays, pointers to arrays, pointers to functions, etc. +.LP +Unlike the \fIpack\fP operator, the repeat count precedes the letter in +the \fI$parm_desc\fP syntax. The array size preceding the parameter +letter is also unconventional. +.LP +All errors set $dl_errno to 1. +.rn }` '' |