1SNOBOL4LOAD(3) CSNOBOL4 Manual SNOBOL4LOAD(3)
2
6 snobol4load - Loading extension modules into SNOBOL4
7
9 modulename.c:
10 #ifdef HAVE_CONFIG_H
11 #include "config.h"
12 #endif
13 #include "h.h"
15 #include "snotypes.h"
16 #include "macros.h"
17 #include "load.h"
18 #include "equ.h"
19 SNOBOL_MODULE(modulename)
21 /*
23 **=pea
24 **=sect NAME
25 **modulename \- A SNOBOL4 extension module
26 **=sect SYNOPSYS
27 **=code
28 **-INCLUDE 'modulename.sno'
29 **=cut
30 */
31 /*
33 * LOAD("FUNC_NAME(ARG_TYPES,....)RET_TYPE", MODULENAME_DL)
34 */
35 /*
36 **=code
37 ** result = B<FUNC_NAME(ARG_TYPES,....)>
38 **=ecode
39 */
40 lret_t
41 FUNC_NAME(LA_ALIST) {
42 /* function body */
43 }
44
46 External C functions are loaded into SNOBOL4 via the LOAD() function.
47 LOAD() is passed a prototype which names the function and may describe
48 the minimum number and types of the parameters the function will be
49 passed, as well as the return type.
50 The typedefs int_t and real_t should be used in C code for all SNOBOL4
52 INTEGER and REAL values, or value truncation may occur.
53 The function should use one of the following macros to return a value
55 (the type of which should be compatible with the type in the prototype
56 passed to the LOAD() function:
57 RETINT(i) /* return INTEGER (int_t) value */
59 RETREAL(a) /* return REAL (real_t) value */
60 RETNULL /* return null string */
61 RETSTR_FREE(buf) /* return C string and free malloc'ed buf */
62 RETSTR2_FREE(buf,len) /* return counted str and free malloc'ed buf */
63 RETSTR(buf) /* return C string from static buffer */
64 RETSTR2(buf,len) /* return counted string from static buf */
65 RETPRED(success) /* return predicate value (NULL or failure) */
66 RETFAIL /* return failure */
67 Parameters are accessed positionally via the following macros. When a
69 data type is specified in the LOAD() prototype, values passed to the
70 function will automatically be converted to the specified data type.
71 The following macros do NOT perform data type conversion, and using the
72 wrong macro to access a parameter will return garbage, or worse.
73 int_t i = LA_INT(0); /* gets value of 1st parameter; returns int_t */
75 real_t a = LA_REAL(1); /* gets value of 2nd parameter; returns real_t */
76 char *s = mgetstring(LA_PTR(2)); /* get string argument as C string
77 * in malloc'ed buffer. MUST be free'ed */
78 const char *sp = LA_STR_PTR(2); /* get pointer (or NULL) */
79 int sl = LA_STR_LEN(2); /* returns string length. */
80 External functions can be written to take polymorphic parameters by
82 leaving the type name blank in the prototype, or passing arguments in
83 excess of those described in the prototype. For example
84 "FOO(,STRING)INTEGER" is a function with two parameters, the first is
85 polymorphic. The LA_TYPE(n) macro must be used to determine the actual
86 parameter data type;
87 I arg n is an integer of C type int_t (fetch with LA_INT(n))
89 R arg n is a real of C type real_t (fetch with LA_REAL(n))
91 S arg n references a string (fetch with mgetstring etc).
93 Loadable code can be compiled and installed using snobol4setup(3),
95 which generates a modulename.sno include file.
96
98 snobol4(1), snobol4setup(3), snopea(7)
99CSNOBOL4B 2.3.1 March 31, 2022 SNOBOL4LOAD(3)