This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perl 3.0 patch #29 (combined patch)
[perl5.git] / os2 / README.OS2
1                    Notes on the OS/2 Perl port
2
3                         Raymond Chen
4                  (rjc@math.princeton.edu)
5
6                         Kai Uwe Rommel
7           (rommel@lan.informatik.tu-muenchen.dbp.de)
8
9 -1.  Background.
10
11 This port was based on the MS-DOS port by Diomidis Spinellis.
12
13 0.  Set-up.
14
15 First copy the files in the os2 directory into the parent
16 directory.  Also install the file msdos/dir.h in your include
17 directory.
18
19 1.  Compiling.
20
21 Perl has been compiled under MS-DOS using the Microsoft C compiler
22 version 6.0.  Before compiling install dir.h as <sys/dir.h>.  You will
23 need a Unix-like make program and something like yacc (e.g. bison).  I
24 just ran yacc on my UNIX box and downloaded the resulting y.tab.[ch]
25 files.  Compilation takes 45 minutes on a 16MHz 386 machine running
26 no jobs other than the compiler, so you will probably need something to
27 do in the meantime.  Like, say, lunch.  (Compilation time does not
28 include formatting the manual.)  If you compile with optimization
29 turned off, it takes about half as long.
30
31 The executable is 270k (perlsym.exe is 473k; if you compile
32 without optimization, the sizes are 329K/531K), and the top level
33 directory needs 800K for sources, 550K for object code, and 800K for the
34 executables, assuming you want to build both perl.exe and perlsym.exe
35 with full optimization.
36
37 The makefile will compile glob for you which you will need to place
38 somewhere in your path so that perl globbing will work correctly.  All
39 the tests were run, although some modifications were necessary because
40 OS/2 isn't UNIX. The tests that failed failed because of limitations of
41 the operating system and aren't the fault of the compiler.  a2p and s2p
42 were not tested.
43
44 In the eg directory you will find the syscalls.pl header file,
45 and a sample program that demonstrates some of the improvements
46 of the OS/2 version over the MS-DOS version and some of the
47 system calls.
48
49 2.  Using OS/2 Perl
50
51 The OS/2 version of perl has much of the functionality of the Unix
52 version.  Here are some things that don't work:  sockets, password
53 functions, [gs]et[eug]id, dbm functions, fork.
54
55 One thing that doesn't work is "split" with no arguments.  Somehow,
56 yylval.arg is empty ...  [[ Wait, sorry, I fixed that. --rjc ]]
57
58 Care has been taken to implement the rest, although the implementation
59 might not be the best possible.  Here are short notes on the tricky
60 bits:
61
62 2.1.  In-place editing.
63
64 Files currently can be edited in-place provided you are creating a
65 backup.  Considerable effort is made to ensure that a reasonable
66 name for the backup is selected, while still remaining within
67 the 8.3 contraints of the FAT filesystem.  (HPFS users have nothing
68 to worry about, since HPFS doesn't have the stupid 8.3 rule.)
69
70 The rules for how OS/2 perl combines your filename with the suffix
71 (the thing passed to "-i") are rather complicated, but the basic
72 idea is that the "obvious" name is chosen.
73
74 Here are the rules:
75
76 Style 0:  Append the suffix exactly as UNIX perl would do it.
77           If the filesystem likes it, use it.  (HPFS will always
78           swallow it.  FAT will rarely accept it.)
79
80 Style 1:  If the suffix begins with a '.', change the file extension
81           to whatever you supplied.  If the name matches the original
82           name, use the fallback method.
83
84 Style 2:  If the suffix is a single character, not a '.', try to add the
85           suffix to the following places, using the first one that works.
86               [1] Append to extension.
87               [2] Append to filename,
88               [3] Replace end of extension,
89               [4] Replace end of filename.
90           If the name matches the original name, use the fallback method.
91
92 Style 3:  Any other case:  Ignore the suffix completely and use the
93           fallback method.
94
95 Fallback method:  Change the extension to ".$$$".  If that matches the
96           original name, then change the extension to ".~~~".
97
98 If filename is more than 1000 characters long, we die a horrible
99 death.  Sorry.
100
101 Examples, assuming style 0 failed.
102
103 suffix = ".bak" (style 1)
104                foo.bar => foo.bak
105                foo.bak => foo.$$$       (fallback)
106                foo.$$$ => foo.~~~       (fallback)
107                makefile => makefile.bak
108
109 suffix = "~" (style 2)
110                foo.c => foo.c~
111                foo.c~ => foo.c~~
112                foo.c~~ => foo~.c~~
113                foo~.c~~ => foo~~.c~~
114                foo~~~~~.c~~ => foo~~~~~.$$$ (fallback)
115
116                foo.pas => foo~.pas
117                makefile => makefile.~
118                longname.fil => longname.fi~
119                longname.fi~ => longnam~.fi~
120                longnam~.fi~ => longnam~.$$$
121
122 2.2.  Directory access.
123
124 Are implemented, but in order to support telldir() and seekdir(),
125 they operate by reading in the entire directory at opendir(),
126 then handing out pieces of it each time you do a readdir().
127
128 2.3.  Pipes and redirection.
129
130 Pipes and redirection are supported.  Although OS/2 does not
131 terminate programs which try to write to closed pipes, perl will
132 kill them for you if you do it like this:
133
134         open(I, "long-running-program|");
135         ... process a few lines ...
136         close(I);       # discard the rest ...
137
138 The killing works like this:  We wait until the child program either
139 closes its stdout or tries to write to it.  If it writes to its stdout,
140 we kill it.  Otherwise, we cwait for it.  This is pretty much what UNIX
141 does by default.
142
143 All pipe commands are given to cmd.exe (or your COMSPEC) for execution as
144
145         CMD /c your-command-line
146
147 so you can go ahead and load it up with any goofy things you want,
148 like 2>1 redirection, more pipes, && || etc.
149
150 The pipe() function is also supported, so you can go ahead and
151 make your own funky file descriptor connections before piping off
152 a process.  However, you have to mark the descriptor you are
153 retaining as NOINHERIT before spawning, else you are in deadlock city.
154 Unfortunately, there's no way to mark the handle as NOINHERIT yet.
155 It's on my wish list.
156
157 2.4.  Syscall and Ioctl
158
159 IOCtl is not supported because the API is very different from the
160 UNIX API.  Instead, IOCtl is supported as a syscall.  Here are
161 the syscalls I've written so far:
162
163         $OS2_GetVersion = 0;
164         $OS2_Shutdown = 1;
165         $OS2_Beep = 2;
166         $OS2_PhysicalDisk = 3;
167         $OS2_Config = 4;
168         $OS2_IOCtl = 5;
169         $OS2_QCurDisk = 6;
170         $OS2_SelectDisk = 7;
171         $OS2_SetMaxFH = 8;
172         $OS2_Sleep = 9;
173         $OS2_StartSession = 10;
174         $OS2_StopSession = 11;
175         $OS2_SelectSession = 12;
176
177 The arguments you pass are handed off to OS/2 without interpretation,
178 and the return value is returned straight to you.  However, you don't
179 have to supply arguments for the ones whose descriptions are "must be
180 zero"; perl will supply the mandatory zeros for you.
181
182 2.5.  Binary file access
183
184 Files are opened in text mode by default.  This means that CR LF pairs
185 are translated to LF. If binary access is needed the `binarymode'
186 function should be used.  There is currently no way to reverse the
187 effect of the binary function.  If that is needed close and reopen the
188 file.
189
190 2.6.  Priority
191
192 The getpriority and setpriority functions are implemented, but since
193 OS/2 priorities are different from UNIX priorities, the arguments aren't
194 the same.  Basically, the arguments you pass are handed directly to
195 OS/2. The only exception is the last argument to setpriority.  To make
196 it easier to make delta priorities, if the priority class is 0xff, it
197 is changed to 0.  That way, you can write
198
199         setpriority(0,0,-2)
200
201 instead of
202
203         setpriority(0,0,0xfe)
204
205 to decrease the delta by 2.
206
207 2.7.  Interpreter startup.
208
209 The effect of the Unix #!/bin/perl interpreter startup can be obtained
210 under OS/2 by giving the script a .cmd extension and beginning the script
211 with the line
212
213         extproc C:\binp\perl.exe -S
214
215 You should provide the appropriate path to your executable, and
216 the -S option is necessary so that perl can find your script.
217
218 2.8.  The kill function.
219
220 UNIX and OS/2 have different ideas about the kill function.  I've
221 done a pretty feeble job of taking perl's UNIXish approach and
222 trying to jam it into the OS/2 way.  No doubt you'll find that
223 your kill()s aren't working.  My apologies in advance.
224
225 3.  Bug reports.
226
227 I don't normally have access to an OS/2 machine, so if you find
228 a bug, you can go ahead and tell me about it, but the odds that
229 I'd be able to fix it are slim.
230
231 4.  Wish list.
232
233 4.1.  OS/2.
234
235 Make ENOPIPE a fatal error.
236
237 Permit linking of files.  (Allegedly, they're working on this.)
238
239 Get a fork.
240
241 Make CMD.EXE pass through the return code of its child.
242
243 4.2 perl.
244
245 Provide a nice way to add new functions to perl without having
246 to understand the innards of perl.  Not being fluent in perl
247 innards hacking, I added my extra functions via syscall.
248
249 4.3. My port.
250
251 4.3.1.  In-place editing.
252
253 Make more idiot-proof.
254
255 Allow in-place editing without backup.  (How?)
256
257 4.3.2.  Spawning and piping.
258
259 Make popen() cleverer.  Currently, it blindly hands everything
260 off to CMD.EXE.  This wastes an exec if the command line didn't
261 have any shell metacharacters and if the program being run
262 is not a batch file.
263
264 Clever spawning is carried out by do_spawn.  We should try
265 to make popen() do much of the same sort of preprocessing
266 as do_spawn does (which means, of course, that we probably
267 should yank out code to be dished off into a subroutine).
268
269 In do_spawn(), use DosExecPgm instead of spawnl in order to get more
270 precise reasons why the child terminated (RESULTCODES).
271
272
273                                 July 1990
274
275                                 Raymond Chen <rjc@math.princeton.edu>
276                                 1817 Oxford St. Apt 6
277                                 Berkeley, CA 94709-1828 USA
278
279 -----------------------
280 I picked up the OS/2 port with patches 19-28. When compiling, I found
281 out that os2.c and director.c were missing. I had to rewrite them because
282 even the original author of the port (Raymond Chen) did no longer have them.
283
284 I had directory routines laying around, this was no big deal.
285 I rewrote os2.c, but did not implement the syscall() as described above.
286 I had not the time and did not really need it. Feel free ...
287
288 Changes to above described port:
289
290 - the small program GLOB is now named PERLGLOB for better ordering in
291   my /bin directory
292
293 - added help page (well, a graphical user interface would be overkill
294   but a simple help page should be in every program :-)
295
296 - several cosmetic changes in standard distribution files because of
297   naming conventions etc., #ifdef'd OS2
298
299 - syscall() not supported as noted above
300
301 - chdir now recognizes also drive letters and changes also the drive
302
303 - new mypopen(), mypclose() functions and simulation routines for DOS mode,
304   they are selected automatically in real mode
305 - the new pclose() does not kill the child, my experience is that this is
306   not needed.
307
308 - setpriority is now:   setpriority(class, pid, val)
309   see description of DosSetPrty() for class and val meanings
310 - getpriority is now:   getpriority(dummy, pid)
311   see description of DosGetPrty()
312
313 - kill is now:          kill(pid, sig)
314   where sig can be 0 (kill process)
315                    1-3 (send process flags A-C, see DosFlagProcess())
316   if pid is less than zero, the signal is sent to the whole
317   process tree originating at -pid.
318
319 The following files are now new with patch >=29:
320
321 readme.os2        this file
322
323 dir.h             sys/dir.h
324 director.c        directory routines
325 os2.c             kernel of OS/2 port (see below)
326 popen.c           new popen.c
327 mktemp.c          enhanced mktemp(), uses TMP env. variable, used by popen.c
328
329 perl.cs           Compiler Shell script for perl itself
330 perl.def          linker definition file for perl
331 perl.bad          names of protect-only API calls for BIND
332 perlglob.cs       Compiler Shell script for perl globbing program
333 perlglob.def      linker definition file for perlglob
334 a2p.cs            Compiler Shell script for a2p (see below)
335 a2p.def           linker definition file for a2p
336 makefile          Makefile, not tested
337
338 perlsh.cmd        the converted perlsh
339 selfrun.cmd       sample selfrunning perl script for OS/2
340 selfrun.bat       sample selfrunning perl script for DOS mode
341
342 Note: I don't use make but my own utility, the Compiler Shell CS.
343 It was posted in comp.binaries.os2 or you can ask me for the newest
344 version. The .CS files are the "makefiles" for it.
345
346 Note: MS C 6.00 is required. C 5.1 is not capable of compiling perl,
347 especially not with -DDEBUGGING
348
349
350                                 August 1990
351
352                                 Kai Uwe Rommel
353                                 rommel@lan.informatik.tu-muenchen.dbp.de
354                                 Breslauer Str. 25
355                                 D-8756 Kahl/Main
356                                 West (yes, still!) Germany