This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perl 4.0.00: (no release announcement available)
[perl5.git] / usub / README
CommitLineData
fe14fcc3
LW
1This directory contains an example of how you might link in C subroutines
2with perl to make your own special copy of perl. In the perl distribution
3directory, there will be (after make is run) a file called uperl.o, which
4is all of perl except for a single undefined subroutine, named userinit().
5See usersub.c.
6
7The sole purpose of the userinit() routine is to call the initialization
8routines for any modules that you want to link in. In this example, we just
9call init_curses(), which sets up to link in the BSD curses routines.
10You'll find this in the file curses.c, which is the processed output of
11curses.mus.
12
13The magicname() routine adds variable names into the symbol table. Along
14with the name of the variable as Perl knows it, we pass a structure containing
15an index identifying the variable, and the names of two C functions that
16know how to set or evaluate a variable given the index of the variable.
17Our example uses a macro to handle this conveniently.
18
19The init routine calls make_usub() to add user-defined subroutine names
20into the symbol table. The arguments are
21
22 make_usub(subname, subindex, subfunc, filename);
23 char *subname;
24 int subindex;
25 int subfunc();
26 char *filename;
27
28The subname is the name that will be used in the Perl program. The subindex
29will be passed to subfunc() when it is called to tell it which C function
30is desired. subfunc() is a glue routine that translates the arguments
31from Perl internal stack form to the form required by the routine in
32question, calls the desired C function, and then translates any return
33value back into the stack format. The glue routine used by curses just
34has a large switch statement, each branch of which does the processing
35for a particular C function. The subindex could, however, be used to look
36up a function in a dynamically linked library. No example of this is
37provided.
38
39As a help in producing the glue routine, a preprocessor called "mus" lets
40you specify argument and return value types in a tabular format. An entry
41such as:
42
43 CASE int waddstr
44 I WINDOW* win
45 I char* str
46 END
47
48indicates that waddstr takes two input arguments, the first of which is a
49pointer to a window, and the second of which is an ordinary C string. It
50also indicates that an integer is returned. The mus program turns this into:
51
52 case US_waddstr:
53 if (items != 2)
54 fatal("Usage: &waddstr($win, $str)");
55 else {
56 int retval;
57 WINDOW* win = *(WINDOW**) str_get(st[1]);
58 char* str = (char*) str_get(st[2]);
59
60 retval = waddstr(win, str);
61 str_numset(st[0], (double) retval);
62 }
63 return sp;
64
65It's also possible to have output parameters, indicated by O, and input/ouput
66parameters indicated by IO.
67
68The mus program isn't perfect. You'll note that curses.mus has some
69cases which are hand coded. They'll be passed straight through unmodified.
70You can produce similar cases by analogy to what's in curses.c, as well
71as similar routines in the doarg.c, dolist.c and doio.c routines of Perl.
72The mus program is only intended to get you about 90% there. It's not clear,
73for instance, how a given structure should be passed to Perl. But that
74shouldn't bother you--if you've gotten this far, it's already obvious
75that you are totally mad.
76
77Here's an example of how to return an array value:
78
79 case US_appl_errlist:
80 if (!wantarray) {
81 str_numset(st[0], (double) appl_nerr);
82 return sp;
83 }
84 astore(stack, sp + appl_nerr, Nullstr); /* extend stack */
85 st = stack->ary_array + sp; /* possibly realloced */
86 for (i = 0; i < appl_nerr; i++) {
87 tmps = appl_errlist[i];
88 st[i] = str_2mortal(str_make(tmps,strlen(tmps)));
89 }
90 return sp + appl_nerr - 1;
91
92
93In addition, there is a program, man2mus, that will scan a man page for
94function prototypes and attempt to construct a mus CASE entry for you. It has
95to guess about input/output parameters, so you'll have to tidy up after it.
96But it can save you a lot of time if the man pages for a library are
97reasonably well formed.
98
99If you happen to have BSD curses on your machine, you might try compiling
100a copy of curseperl. The "pager" program in this directory is a rudimentary
101start on writing a pager--don't believe the help message, which is stolen
102from the less program.
103
104There is currently no official way to call a Perl routine back from C,
105but we're working on it. It might be easiest to fake up a call to do_eval()
106or do_subr(). This is not for the faint of heart. If you come up with
107such a glue routine, I'll be glad to add it into the distribution.
108
109User-defined subroutines may not currently be called as a signal handler,
110though a signal handler may itself call a user-defined subroutine.