← Back to branch summary

~ubuntu-branches/ubuntu/hoary/scilab/hoary

« back to all changes in this revision

Viewing changes to man/eng/utilities/link.xml

  • Committer: Bazaar Package Importer
  • Author(s): Torsten Werner
  • Date: 2005-01-09 22:58:21 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20050109225821-473xr8vhgugxxx5j
Tags: 3.0-12
http://bugs.debian.org/255869
changed configure.in to build scilab's own malloc.o, closes: #255869

Show diffs side-by-side

added added

removed removed

Lines of Context:
man/eng/utilities/link.xml
 
1
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
 
2
<!DOCTYPE MAN SYSTEM "../../manrev.dtd">
 
3
<MAN>
 
4
  <LANGUAGE>eng</LANGUAGE>
 
5
  <TITLE>link</TITLE>
 
6
  <TYPE>Scilab Function</TYPE>
 
7
  <DATE>April 1993</DATE>
 
8
  <SHORT_DESCRIPTION name="link"> dynamic link</SHORT_DESCRIPTION>
 
9
  <CALLING_SEQUENCE>
 
10
    <CALLING_SEQUENCE_ITEM>link(files, sub-name)  </CALLING_SEQUENCE_ITEM>
 
11
    <CALLING_SEQUENCE_ITEM>link(files, sub-name, flag)  </CALLING_SEQUENCE_ITEM>
 
12
    <CALLING_SEQUENCE_ITEM>lst=link('show')  </CALLING_SEQUENCE_ITEM>
 
13
    <CALLING_SEQUENCE_ITEM>// Link extensions for machines using ``dlopen''   </CALLING_SEQUENCE_ITEM>
 
14
    <CALLING_SEQUENCE_ITEM>// (sun-solaris/linux-elf/alpha/hppa)  </CALLING_SEQUENCE_ITEM>
 
15
    <CALLING_SEQUENCE_ITEM>x=link(files [, sub-names,flag]);  </CALLING_SEQUENCE_ITEM>
 
16
    <CALLING_SEQUENCE_ITEM>link(x , sub-names [, flag]);  </CALLING_SEQUENCE_ITEM>
 
17
    <CALLING_SEQUENCE_ITEM>ulink(x)  </CALLING_SEQUENCE_ITEM>
 
18
  </CALLING_SEQUENCE>
 
19
  <PARAM>
 
20
    <PARAM_INDENT>
 
21
      <PARAM_ITEM>
 
22
        <PARAM_NAME>files</PARAM_NAME>
 
23
        <PARAM_DESCRIPTION>
 
24
          <SP>: a character string or a vector of character strings. <VERB>ld</VERB> files used to define the new entry point (compiled routines, user libraries, system libraries,..)</SP>
 
25
        </PARAM_DESCRIPTION>
 
26
      </PARAM_ITEM>
 
27
      <PARAM_ITEM>
 
28
        <PARAM_NAME>sub-name</PARAM_NAME>
 
29
        <PARAM_DESCRIPTION>
 
30
          <SP>: a character string. Name of the entry point in <VERB>files</VERB> to be linked.</SP>
 
31
        </PARAM_DESCRIPTION>
 
32
      </PARAM_ITEM>
 
33
      <PARAM_ITEM>
 
34
        <PARAM_NAME>sub-names</PARAM_NAME>
 
35
        <PARAM_DESCRIPTION>
 
36
          <SP>: a character string or a vector of character strings . Name of the entry points in <VERB>files</VERB> to be linked.</SP>
 
37
        </PARAM_DESCRIPTION>
 
38
      </PARAM_ITEM>
 
39
      <PARAM_ITEM>
 
40
        <PARAM_NAME>x</PARAM_NAME>
 
41
        <PARAM_DESCRIPTION>
 
42
          <SP>: an integer which gives the id of a shared library linked into Scilab with a previous call to <VERB>link</VERB>.</SP>
 
43
        </PARAM_DESCRIPTION>
 
44
      </PARAM_ITEM>
 
45
      <PARAM_ITEM>
 
46
        <PARAM_NAME>flag</PARAM_NAME>
 
47
        <PARAM_DESCRIPTION>
 
48
          <SP>: character string <VERB>'f'</VERB> or <VERB>'c'</VERB> for Fortran (default) or C code.</SP>
 
49
        </PARAM_DESCRIPTION>
 
50
      </PARAM_ITEM>
 
51
      <PARAM_ITEM>
 
52
        <PARAM_NAME>names</PARAM_NAME>
 
53
        <PARAM_DESCRIPTION>
 
54
          <SP>: a vector of character string. Names of dynamically linked entry points.</SP>
 
55
        </PARAM_DESCRIPTION>
 
56
      </PARAM_ITEM>
 
57
    </PARAM_INDENT>
 
58
  </PARAM>
 
59
  <DESCRIPTION>
 
60
    <P><VERB>link</VERB> is a dynamic link facility: this command allows to add new compiled
 
61
    Fortran or C routines to Scilab executable code.
 
62
    Linked routines can be called interactively by the function <VERB>fort</VERB>.
 
63
    Linked routines can also be used as &quot;external&quot; for e.g. 
 
64
    non linear problem solvers (<VERB>ode</VERB>, <VERB>optim</VERB>, <VERB>intg</VERB>, 
 
65
    <VERB>dassl</VERB>...). Here are some examples:
 
66
  </P>
 
67
    <P>
 
68
    The command <VERB>link('foo.o','foo','f')</VERB> links the Fortran 
 
69
    object file <VERB>foo.o</VERB> with the entry point <VERB>foo</VERB>.
 
70
  </P>
 
71
    <P>
 
72
    The command <VERB>link('foo.o','foo','c')</VERB> links the C
 
73
    object file <VERB>foo.o</VERB> with the entry point <VERB>foo</VERB>.
 
74
  </P>
 
75
    <P>
 
76
    The command <VERB>link('SCIDIR/libs/calelm.a','dcopy')</VERB> links the 
 
77
    Fortran routine <VERB>dcopy</VERB> in the library <VERB>calelm.a</VERB>.
 
78
  </P>
 
79
    <P>
 
80
    A routine can be linked several times and can be unlinked with
 
81
    <VERB>ulink</VERB>. Note that, on some architectures (the ones on which
 
82
    <VERB>ulink</VERB> exists) when a routine is linked several times, all 
 
83
    the version are kept inside Scilab. 
 
84
  </P>
 
85
    <P>
 
86
    Used with no arguments, <VERB>link()</VERB> returns the current linked routines.
 
87
  </P>
 
88
    <P>
 
89
    If Scilab is compiled with static link (this is the default for
 
90
    SystemV machines) you may have to include the system libraries in the 
 
91
    &quot;link&quot; command.
 
92
  </P>
 
93
    <P>
 
94
    For example, if <VERB>foo.o</VERB> defines the object code of a routine named 
 
95
    <VERB>foo</VERB>, you will use <VERB>link</VERB> in one the following way: 
 
96
  </P>
 
97
    <VERBATIM>
 
98
<![CDATA[
 
99
link('foo.o','foo').
 
100
link('foo.o -lm -lc','foo','c').
 
101
link('foo.o -lfor -lm -lc','foo').
 
102
link('foo.o -lftn -lm -lc','foo').
 
103
link('foo.o -L/opt/SUNWspro/SC3.0/lib/lib77 -lm -lc','foo')
 
104
   ]]>
 
105
    </VERBATIM>
 
106
    <P>
 
107
    If Scilab compiled with the &quot;shared&quot; option, the first example can be used
 
108
    even if a warning for unresolved references is issued.
 
109
  </P>
 
110
    <P>
 
111
    (Experienced) users may also <VERB>link</VERB> a new Scilab interface routine 
 
112
    to add a set of new functions. 
 
113
    See <VERB>Intersci</VERB> documentation for interface generation and
 
114
    <VERB>addinter</VERB> function.
 
115
  </P>
 
116
  </DESCRIPTION>
 
117
  <SECTION label="Remarks">
 
118
    <ITEMIZE>
 
119
      <ITEM label="IBM:">
 
120
        <SP>For IBM-RS6000 only one program can be dynamically linked.</SP>
 
121
      </ITEM>
 
122
      <ITEM label="Demo:">
 
123
        <SP>When running a demo, you may have some trouble with the link due to slight differences between systems. In this case, you modify the demo by adding the needed libraries in the link command.</SP>
 
124
      </ITEM>
 
125
      <ITEM label="dlopen:">
 
126
        <SP>For machines using dlopen functionality extended command can be used. a call to <VERB>link</VERB> returns an integer which gives the id of the shared  library which is loaded into Scilab. This number can then be used as the first argument of the link function in order to link additional  function from the linked shared library. The shared library is  removed with the <VERB>ulink</VERB> command.  for example to link functions <VERB>f</VERB> and <VERB>g</VERB> form binary file  <VERB>test.o</VERB> the two following command can be used :</SP>
 
127
        <VERBATIM>
 
128
<![CDATA[
 
129
link('test.o',['f','g'])
 
130
   ]]>
 
131
        </VERBATIM>
 
132
        <P>
 
133
    or
 
134
  </P>
 
135
        <VERBATIM>
 
136
<![CDATA[
 
137
x=link('test.o','f');
 
138
link(x,'g');
 
139
   ]]>
 
140
        </VERBATIM>
 
141
        <P>
 
142
    But 
 
143
  </P>
 
144
        <VERBATIM>
 
145
<![CDATA[
 
146
link('test.o','f');
 
147
link('test.o','g');
 
148
   ]]>
 
149
        </VERBATIM>
 
150
        <P>
 
151
    will also work but <VERB>f</VERB> and <VERB>g</VERB> will be loaded from two different shared libraries and won't be able to share data.  
 
152
  </P>
 
153
      </ITEM>
 
154
      <ITEM label="show:">
 
155
        <SP>The command <VERB>lst=link('show')</VERB> will report information about  linked shared libraries and linked functions. The return value of the function <VERB>lst</VERB> is <VERB>1</VERB> or <VERB>0</VERB>.  If the return value is <VERB>1</VERB> then the extended calling sequence  described as <VERB>Link extensions for machines using ``dlopen'' </VERB> are  accepted.</SP>
 
156
      </ITEM>
 
157
      <ITEM label="unlink :">
 
158
        <SP>(dlopen version) If the function <VERB>f</VERB> is changed and one wants to link  the new version, it is necessary to use unlink to get rid of  previous loaded versions of the function <VERB>f</VERB></SP>
 
159
        <VERBATIM>
 
160
<![CDATA[
 
161
x=link('test.o','f');
 
162
// if I need to reload a new definition of f a call to unlink
 
163
// is necessary.
 
164
ulink(x);
 
165
link('test.o','f');
 
166
   ]]>
 
167
        </VERBATIM>
 
168
      </ITEM>
 
169
      <ITEM label="scilab symbols:">
 
170
        <SP>In order to load a symbol from the Scilab code on can use</SP>
 
171
        <VERBATIM>
 
172
<![CDATA[
 
173
link("Scilab",['Scilab-entry-point'])
 
174
   ]]>
 
175
        </VERBATIM>
 
176
        <P>
 
177
    This does not work on all architectures. On some machines, on can  link a Scilab internal function after a first call to link ( with  a default binary file )</P>
 
178
        <VERBATIM>
 
179
<![CDATA[
 
180
link("test.o",['Scilab-entry-point'])
 
181
   ]]>
 
182
        </VERBATIM>
 
183
        <P>
 
184
    Note that with <VERB>dld</VERB> (Linux machine aout) you can use an empty string</P>
 
185
        <VERBATIM>
 
186
<![CDATA[
 
187
link(" ",['Scilab-entry-point'])
 
188
   ]]>
 
189
        </VERBATIM>
 
190
      </ITEM>
 
191
    </ITEMIZE>
 
192
  </SECTION>
 
193
  <SEE_ALSO>
 
194
    <SEE_ALSO_ITEM>
 
195
      <LINK>fort</LINK>
 
196
    </SEE_ALSO_ITEM>
 
197
    <SEE_ALSO_ITEM>
 
198
      <LINK>c_link</LINK>
 
199
    </SEE_ALSO_ITEM>
 
200
    <SEE_ALSO_ITEM>
 
201
      <LINK>addinter</LINK>
 
202
    </SEE_ALSO_ITEM>
 
203
  </SEE_ALSO>
 
204
</MAN>