1Function: install
2Section: programming/specific
3C-Name: gpinstall
4Prototype: vrrD"",r,D"",s,
5Help: install(name,code,{gpname},{lib}): load from dynamic library 'lib' the
6 function 'name'. Assign to it the name 'gpname' in this GP session, with
7 prototype 'code'. If 'lib' is omitted, all symbols known to gp
8 (includes the whole 'libpari.so' and possibly others) are available.
9 If 'gpname' is omitted, use 'name'.
10Doc: loads from dynamic library \var{lib} the function \var{name}. Assigns to it
11 the name \var{gpname} in this \kbd{gp} session, with \emph{prototype}
12 \var{code} (see below). If \var{gpname} is omitted, uses \var{name}.
13 If \var{lib} is omitted, all symbols known to \kbd{gp} are available: this
14 includes the whole of \kbd{libpari.so} and possibly others (such as
15 \kbd{libc.so}).
16
17 Most importantly, \kbd{install} gives you access to all nonstatic functions
18 defined in the PARI library. For instance, the function
19 \bprog
20   GEN addii(GEN x, GEN y)
21 @eprog\noindent adds two PARI integers, and is not directly accessible under
22 \kbd{gp} (it is eventually called by the \kbd{+} operator of course):
23 \bprog
24 ? install("addii", "GG")
25 ? addii(1, 2)
26 %1 = 3
27 @eprog\noindent
28 It also allows to add external functions to the \kbd{gp} interpreter.
29 For instance, it makes the function \tet{system} obsolete:
30 \bprog
31 ? install(system, vs, sys,/*omitted*/)
32 ? sys("ls gp*")
33 gp.c            gp.h            gp_rl.c
34 @eprog\noindent This works because \kbd{system} is part of \kbd{libc.so},
35 which is linked to \kbd{gp}. It is also possible to compile a shared library
36 yourself and provide it to gp in this way: use \kbd{gp2c}, or do it manually
37 (see the \kbd{modules\_build} variable in \kbd{pari.cfg} for hints).
38
39 Re-installing a function will print a warning and update the prototype code
40 if needed. However, it will not reload a symbol from the library, even if the
41 latter has been recompiled.
42
43 \misctitle{Prototype} We only give a simplified description here, covering
44 most functions, but there are many more possibilities. The full documentation
45 is available in \kbd{libpari.dvi}, see
46 \bprog
47   ??prototype
48 @eprog
49
50 \item First character \kbd{i}, \kbd{l}, \kbd{u}, \kbd{v} : return type
51 \kbd{int} / \kbd{long} / \kbd{ulong} / \kbd{void}. (Default: \kbd{GEN})
52
53 \item One letter for each mandatory argument, in the same order as they appear
54 in the argument list: \kbd{G} (\kbd{GEN}), \kbd{\&}
55 (\kbd{GEN*}), \kbd{L} (\kbd{long}), \kbd{U} (\kbd{ulong}),
56 \kbd{s} (\kbd{char *}), \kbd{n} (variable).
57
58  \item \kbd{p} to supply \kbd{realprecision} (usually \kbd{long prec} in the
59  argument list), \kbd{b} to supply \kbd{realbitprecision}
60  (usually \kbd{long bitprec}), \kbd{P} to supply \kbd{seriesprecision}
61  (usually \kbd{long precdl}).
62
63  \noindent We also have special constructs for optional arguments and default
64  values:
65
66  \item \kbd{DG} (optional \kbd{GEN}, \kbd{NULL} if omitted),
67
68  \item \kbd{D\&} (optional \kbd{GEN*}, \kbd{NULL} if omitted),
69
70  \item \kbd{Dn} (optional variable, $-1$ if omitted),
71
72 For instance the prototype corresponding to
73 \bprog
74   long issquareall(GEN x, GEN *n = NULL)
75 @eprog\noindent is \kbd{lGD\&}.
76
77 \misctitle{Caution} This function may not work on all systems, especially
78 when \kbd{gp} has been compiled statically. In that case, the first use of an
79 installed function will provoke a Segmentation Fault (this should never
80 happen with a dynamically linked executable). If you intend to use this
81 function, please check first on some harmless example such as the one above
82 that it works properly on your machine.
83