diff options
Diffstat (limited to 'dlperl/dlperl.man')
| -rw-r--r-- | dlperl/dlperl.man | 219 |
1 files changed, 0 insertions, 219 deletions
diff --git a/dlperl/dlperl.man b/dlperl/dlperl.man deleted file mode 100644 index 8879133ca2..0000000000 --- a/dlperl/dlperl.man +++ /dev/null @@ -1,219 +0,0 @@ -.\" -.\" 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 }` '' |