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