Socket::my_inet_aton() tweak
[p5sagit/p5-mst-13.2.git] / README.mpeix
1 If you read this file _as_is_, just ignore the funny characters you
2 see. It is written in the POD format (see perlpod manpage) which is
3 specially designed to be readable as is.
4
5 =head1 NAME
6
7 README.mpeix - Perl/iX for HP e3000 MPE
8
9 =head1 SYNOPSIS
10
11    http://www.bixby.org/mark/perlix.html
12    Perl language for MPE
13    Last updated June 2, 2000 @ 0400 UTC
14
15 =head1 NOTE
16
17 This is a podified version of the above-mentioned web page,
18 podified by Jarkko Hietaniemi 2001-Jan-01.
19
20 =head1 What's New in Perl for MPE/iX
21
22 June 1, 2000
23
24 =over 4
25
26 =item *
27
28 Rebuilt to be compatible with mod_perl.  If you plan on using
29 mod_perl, you MUST download and install this version of Perl/iX!
30
31 =item *
32
33 bincompat5005="undef": sorry, but you will have to recompile any
34 binary 5.005 extensions that you may be using (if any; there is no
35 5.005 code in what you download from bixby.org)
36 uselargefiles="undef": not available in MPE for POSIX files yet.
37
38 =item *
39
40 Now bundled with various add-on packages:
41
42 =over 8
43
44 =item *
45
46 libnet (http://www.gbarr.demon.co.uk/libnet/FAQ.html)
47
48 =item *
49
50 libwww-perl (LWP) which lets Perl programs behave like web browsers:
51
52     1. #!/PERL/PUB/perl
53     2. use LWP::Simple;
54     3. $doc = get('http://www.bixby.org/mark/perlix.html');  # reads the
55        web page into variable $doc
56
57 (http://www.bixby.org/mark/perlix.html)
58
59 =item *
60
61 mod_perl (just the perl portion; the actual DSO will be released
62 soon with Apache/iX 1.3.12 from bixby.org).  This module allows you to
63 write high performance persistent Perl CGI scripts and all sorts of
64 cool things. (http://perl.apache.org/)
65
66 and much much more hiding under /PERL/PUB/.cpan/
67
68 =item *
69
70 The CPAN module now works for automatic downloading and
71 installing of add-on packages:
72
73     1. export FTP_PASSIVE=1
74     2. perl -MCPAN -e shell
75     3. Ignore any terminal I/O related complaints!
76
77 (http://theoryx5.uwinnipeg.ca/CPAN/data/perl/CPAN.html)
78
79 =back
80
81 =back
82
83 May 20, 2000
84
85 =over 4
86
87 =item *
88
89 Updated to version 5.6.0.  Builds straight out of the box on MPE/iX.
90
91 =item *
92
93 Perl's getpwnam() function which had regressed to being
94 unimplemented on MPE is now implemented once again.
95
96 =back
97
98 September 17, 1999
99
100 =over 4
101
102 =item *
103
104 Migrated from cccd.edu to bixby.org.
105
106 =back
107
108 =head1 Welcome to Perl/iX
109
110 This is the official home page for the HP e3000 MPE/iX
111 (http://www.businessservers.hp.com/) port of the Perl scripting
112 language (http://www.perl.com/) which gives you all of the power of C,
113 awk, sed, and sh in a single language. Check here for the latest news,
114 implemented functionality, known bugs, to-do list, etc. Status reports
115 about major milestones will also be posted to the HP3000-L mailing list
116 (http://www.lsoft.com/scripts/wl.exe?SL1=HP3000-L&H=RAVEN.UTC.EDU) and
117 its associated gatewayed newsgroup comp.sys.hp.mpe.
118
119 I'm doing this port because I can't live without Perl on the Unix
120 machines that I administer, and I want to have the same power
121 available to me on MPE.
122
123 Please send your comments, questions, and bug reports directly to me,
124 Mark Bixby (http://www.bixby.org/mark/), by e-mailing to
125 mark@bixby.org. Or just post them to HP3000-L.
126
127 The platform I'm using to do this port is an HP 3000 957RX running
128 MPE/iX 6.0 and using the GNU gcc C compiler
129 (http://jazz.external.hp.com/src/gnu/gnuframe.html).
130
131 The combined porting wisdom from all of my ports can be found in my
132 MPE/iX Porting Guide (http://www.bixby.org/mark/porting.html).
133
134 IMPORTANT NOTICE: Yes, I do work for the HP CSY R&D lab, but ALL of
135 the software you download from bixby.org is my personal freeware that
136 is NOT supported by HP.
137
138 =head1 System Requirements for Perl/iX
139
140 =over 4
141
142 =item *
143
144 MPE/iX 5.5 or later. This version of Perl/iX does NOT run on
145 MPE/iX 5.0 or earlier, nor does it run on "classic" MPE/V machines.
146
147 =item *
148
149 If you wish to recompile Perl, you must install both GNUCORE and
150 GNUGCC from jazz (http://jazz.external.hp.com/src/gnu/gnuframe.html).
151
152 =item *
153
154 Perl/iX will be happier on MPE/iX 5.5 if you install the MPEKX40B
155 extended POSIX filename characters patch, but this is optional.
156
157 =item *
158
159 Patch LBCJXT6A is required on MPE/iX 5.5 machines in order to
160 prevent Perl/iX from dying with an unresolved external reference
161 to _getenv_libc.
162
163 =item *
164
165 If you will be compiling Perl/iX yourself, you will also need
166 Syslog/iX (http://www.bixby.org/mark/syslogix.html) and the
167 /BIND/PUB/include and /BIND/PUB/lib portions of BIND/iX
168 (http://www.bixby.org/mark/bindix.html).
169
170 =back
171
172 =head1 How to Obtain Perl/iX
173
174 =over 4
175
176 =item 1.
177
178 Download Perl using either FTP.ARPA.SYS or some other client
179
180 =item 2.
181
182 Extract the installation script
183
184 =item 3.
185
186 Edit the installation script
187
188 =item 4.
189
190 Run the installation script
191
192 =item 5.
193
194 Convert your *.a system archive libraries to *.sl shared libraries
195
196 =back
197
198 Download Perl using FTP.ARPA.SYS from your HP 3000 (the preferred
199 method).....
200
201     :HELLO MANAGER.SYS
202     :XEQ FTP.ARPA.SYS
203     open ftp.bixby.org
204     anonymous
205     your@email.address
206     bytestream
207     cd /pub/mpe
208     get perl-5.6.0-mpe.tar.Z /tmp/perl.tar.Z;disc=2147483647
209     exit
210
211 .....Or download using some other generic web or ftp client (the alternate
212 method)
213
214 Download the following files (make sure that you use "binary mode" or
215 whatever client feature that is 8-bit clean):
216
217 =over 4
218
219 =item *
220
221 Perl from
222
223     http://www.bixby.org/ftp/pub/mpe/perl-5.6.0-mpe.tar.Z
224
225 or
226
227     ftp://ftp.bixby.org/pub/mpe/perl-5.6.0-mpe.tar.Z
228
229 =item *
230
231 Upload those files to your HP 3000 in an 8-bit clean bytestream manner to:
232
233     /tmp/perl.tar.Z
234
235 =item *
236
237 Then extract the installation script (after both download methods)
238
239     :CHDIR /tmp
240     :XEQ TAR.HPBIN.SYS 'xvfopz /tmp/perl.tar.Z INSTALL'
241
242 =item *
243
244 Edit the installation script
245
246 Examine the accounting structure creation commands and modify if
247 necessary (adding additional capabilities, choosing a non-system
248 volume set, etc).
249
250     :XEQ VI.HPBIN.SYS /tmp/INSTALL
251
252 =item *
253
254 Run the installation script.
255
256 The accounting structure will be created and then all files will be
257 extracted from the archive.
258
259     :XEQ SH.HPBIN.SYS /tmp/INSTALL
260
261 =item *
262
263 Convert your *.a system archive libraries to *.sl shared libraries
264
265 You only have to do this ONCE on your MPE/iX 5.5 machine in order to
266 convert /lib/lib*.a and /usr/lib/lib*.a libraries to their *.sl
267 equivalents.  This step should not be necessary on MPE/iX 6.0 or later
268 machines because the 6.0 or later update process does it for you.
269
270     :XEQ SH.HPBIN.SYS /PERL/PUB/LIBSHP3K
271
272 =back
273
274 =head1 Perl/iX Distribution Contents Highlights
275
276 =over 4
277
278 =item README
279
280 The file you're reading now.
281
282 =item INSTALL
283
284 Perl/iX Installation script.
285
286 =item LIBSHP3K
287
288 Script to convert *.a system archive libraries to *.sl shared libraries.
289
290 =item PERL
291
292 Perl NMPRG executable.  A version-numbered backup copy also
293 exists.  You might wish to "ln -s /PERL/PUB/PERL /usr/local/bin/perl".
294
295 =item .cpan/
296
297 Much add-on source code downloaded with the CPAN module.
298
299 =item lib/
300
301 Perl libraries, both core and add-on.
302
303 =item man/
304
305 Perl man page documentation.
306
307 =item public_html/feedback.cgi
308
309 Sample feedback CGI form written in Perl.
310
311 =item src/perl-5.6.0-mpe
312
313 Source code.
314
315 =back
316
317 =head1 How to Compile Perl/iX
318
319 =over 4
320
321 =item 1.
322
323 cd src/perl-5.6.0-mpe
324
325 =item 2.
326
327 Read the INSTALL file for the official instructions
328
329 =item 3.
330
331 ./Configure -d
332
333 =item  4.
334
335 make
336
337 =item 5.
338
339 ./mpeix/relink
340
341 =item  6.
342
343 make test (expect approximately 15 out of 11306 subtests to fail,
344 mostly due to MPE not supporting hard links, UDP socket problems,
345 and handling exit() return codes improperly)
346
347 =item 7.
348
349 make install
350
351 =item 8.
352
353 Optionally create symbolic links that point to the Perl
354 executable, i.e. ln -s /PERL/PUB/PERL /usr/local/bin/perl
355
356 =back
357
358 The summary test results from "cd t; ./perl -I../lib harness":
359
360   Failed Test  Status Wstat Total Fail  Failed  List of failed
361   ---------------------------------------------------------------------------
362   io/fs.t                      29    8  27.59%  2-5, 7-9, 11
363   io/openpid.t                 10    1  10.00%  7
364   lib/io_sock.t                14    1   7.14%  13
365   lib/io_udp.t                  7    2  28.57%  3, 5
366   lib/posix.t                  27    1   3.70%  12
367   op/lex_assign.t             187    1   0.53%  13
368   op/stat.t                    58    1   1.72%  3
369   15 tests and 94 subtests skipped.
370   Failed 7/236 test scripts, 97.03% okay. 15/11306 subtests failed, 99.87% okay.
371
372 =head1 Getting Started with Perl/iX
373
374 Create your Perl script files with "#!/PERL/PUB/perl" (or an
375 equivalent symbolic link) as the first line.  Use the chmod command to
376 make sure that your script has execute permission. Run your script!
377
378 Be sure to take a look at the CPAN module list
379 (http://www.cpan.org/CPAN.html). A wide variety of free Perl software
380 is available.  You can automatically download these packages by using
381 the CPAN module (http://theoryx5.uwinnipeg.ca/CPAN/data/perl/CPAN.html).
382
383 =head1 MPE/iX Implementation Considerations
384
385 There some minor functionality issues to be aware of when comparing
386 Perl for Unix (Perl/UX) to Perl/iX:
387
388 =over 4
389
390 =item *
391
392 MPE gcc/ld doesn't properly support linking NMPRG executables against
393 NMXL dynamic libraries, so you must manually run mpeix/relink after
394 each re-build of Perl.
395
396 =item *
397
398 Perl/iX File::Copy will use MPE's /bin/cp command to copy files by
399 name in order to preserve file attributes like file code.
400
401 =item *
402
403 MPE (and thus Perl/iX) lacks support for setgrent(), endgrent(),
404 setpwent(), endpwent().
405
406 =item *
407
408 MPE (and thus Perl/iX) lacks support for hard links.
409
410 =item *
411
412 MPE requires GETPRIVMODE() in order to bind() to ports less than 1024.
413 Perl/iX will call GETPRIVMODE() automatically on your behalf if you
414 attempt to bind() to these low-numbered ports.  Note that the Perl/iX
415 executable and the PERL account do not normally have CAP=PM, so if you
416 will be bind()-ing to these privileged ports, you will manually need
417 to add PM capability as appropriate.
418
419 =item *
420
421 MPE requires that you bind() to an IP address of zero.  Perl/iX
422 automatically replaces the IP address that you pass to bind() with
423 a zero.
424
425 =item *
426
427 If you use Perl/iX fcntl() against a socket it will fail, because MPE
428 requires that you use sfcntl() instead.  Perl/iX does not presently
429 support sfcntl().
430
431 =item *
432
433 MPE requires GETPRIVMODE() in order to setuid().  There are too many
434 calls to setuid() within Perl/iX, so I have not attempted an automatic
435 GETPRIVMODE() solution similar to bind().
436
437 =back
438
439 =head1 Known Perl/iX Bugs Under Investigation
440
441 None.
442
443 =head1 Perl/iX To-Do List
444
445 =over 4
446
447 =item *
448
449 Make setuid()/setgid() support work.
450
451 =item *
452
453 Make sure that fcntl() against a socket descriptor is redirected to sfcntl().
454
455 =item *
456
457 Add support for Berkeley DB once I've finished porting Berkeley DB.
458
459 =item *
460
461 Write an MPE XS extension library containing miscellaneous important
462 MPE functions like GETPRIVMODE(), GETUSERMODE(), and sfcntl().
463
464 =back
465
466 =head1 Perl/iX Change History
467
468 May 6, 1999
469
470 =over 4
471
472 =item *
473
474 Patch LBCJXT6A is required on MPE/iX 5.5 machines in order to prevent
475 Perl/iX from dying with an unresolved external reference to _getenv_libc.
476
477 =back
478
479 April 7, 1999
480
481 =over 4
482
483 =item *
484
485 Updated to version 5.005_03.
486
487 =item *
488
489 The official source distribution once again compiles "straight out
490 of the box" for MPE.
491
492 =item *
493
494 The current incarnation of the 5.5 POSIX filename extended
495 characters patch is now MPEKX40B.
496
497 =item *
498
499 The LIBSHP3K *.a -> *.sl library conversion script is now included
500 as /PERL/PUB/LIBSHP3K.
501
502 =back
503
504 November 20, 1998
505
506 =over 4
507
508 =item *
509
510 Updated to version 5.005_02.
511
512 =item *
513
514 Fixed a DynaLoader bug that was unable to load symbols from relative
515 path name libraries.
516
517 =item *
518
519 Fixed a .xs compilation bug where the mpeixish.sh include file wasn't
520 being installed into the proper directory.
521
522 =item *
523
524 All bugfixes will be submitted back to the official Perl developers.
525
526 =item *
527
528 The current incarnation of the POSIX filename extended characters
529 patch is now MPEKXJ3A.
530
531 =back
532
533 August 14, 1998
534
535 =over 4
536
537 =item *
538
539 The previous POSIX filename extended characters patch MPEKX44C has
540 been superseded by MPEKXB5A.
541
542 =back
543
544 August 7, 1998
545
546 =over 4
547
548 =item *
549
550 The previous POSIX filename extended characters patch MPEKX76A has
551 been superseded by MPEKX44C.
552
553 =back
554
555 July 28, 1998
556
557 =over 4
558
559 =item *
560
561 Updated to version 5.005_01.
562
563 =back
564
565 July 23, 1998
566
567 =over 4
568
569 =item *
570
571 Updated to version 5.005 (production release).  The public
572 freeware sources are now 100% MPE-ready "straight out of the box".
573
574 =back
575
576 July 17, 1998
577
578 =over 4
579
580 =item *
581
582 Updated to version 5.005b1 (public beta release).  The public
583 freeware sources are now 99.9% MPE-ready.  By installing and
584 testing this beta on your own HP3000, you will be helping to
585 insure that the final release of 5.005 will be 100% MPE-ready and
586 100% bug free.
587
588 =item *
589
590 My MPE binary release is now extracted using my standard INSTALL script.
591
592 =back
593
594 July 15, 1998
595
596 =over 4
597
598 =item *
599
600 Changed startperl to #!/PERL/PUB/perl so that Perl will recognize
601 scripts more easily and efficiently.
602
603 =back
604
605 July 8, 1998
606
607 =over 4
608
609 =item *
610
611 Updated to version 5.004_70 (internal developer release) which is now
612 MPE-ready.  The next public freeware release of Perl should compile
613 "straight out of the box" on MPE.  Note that this version of Perl/iX
614 was strictly internal to me and never publicly released.  Note that
615 [21]BIND/iX is now required (well, the include files and libbind.a) if
616 you wish to compile Perl/iX.
617
618 =back
619
620 November 6, 1997
621
622 =over 4
623
624 =item *
625
626 Updated to version 5.004_04.  No changes in MPE-specific functionality.
627
628 =back
629
630 October 16, 1997
631
632 =over 4
633
634 =item *
635
636 Added Demos section to the Perl/iX home page so you can see some
637 sample Perl applications running on my 3000.
638
639 =back
640
641 October 3, 1997
642
643 =over 4
644
645 =item *
646
647 Added System Requirements section to the Perl/iX home page just so the
648 prerequisites stand out more. Various other home page tweaks.
649
650 =back
651
652 October 2, 1997
653
654 =over 4
655
656 =item *
657
658 Initial public release.
659
660 =back
661
662 September 1997
663
664 =over 4
665
666 =item *
667
668 Porting begins.
669
670 =back
671
672 =head1 AUTHOR
673
674 Mark Bixby, mark@bixby.org
675