+cruft

1 files changed, 529 insertions, 0 deletions

diff --git a/gnu/usr.bin/perl/os2/README.old b/gnu/usr.bin/perl/os2/README.old
new file mode 100644
index 00000000000..f49d6be1fa6
--- /dev/null
+++ b/gnu/usr.bin/perl/os2/README.old
@@ -0,0 +1,529 @@
+This documentation to the previous version is somewhat applicable yet.
+No system() extensions, no -R option, the exec/system with one argument
+will use sh.exe only (if required). IZ
+
+			Perl 5.001 for OS/2.
+			   Patchlevel "m"
+
+        Copyright (c) 1989,1990,1991,1992,1993,1994  Larry Wall
+                       All rights reserved.
+
+		OS/2 port Copyright (c) 1990, 1991, 1994-95
+	       Raymond Chen, Kai Uwe Rommel, Andreas Kaiser
+                            
+Version 5 port (this package) by Andreas Kaiser <ak@ananke.s.bawue.de>
+(2:246/8506.9@fidonet).
+
+To run the executables supplied with this file, you have to install the
+EMX runtime package emxrt.zip of version 0.9a05 (0.9a, fixlevel 5) or
+later.
+
+The file emxrt.zip is available at ftp.rus.uni-stuttgart.de (the
+origin), ftp-os2.nmsu.edu and many other places.
+
+The source code of the original Perl 5.0 distribution is not included
+here. You can get it at ftp://ftp.wpi.edu:/perl5/perl5.001.tar.gz (and
+many other places).
+
+For documentation of Perl 5, look at the files into the directory tree
+"pod". For TeX or Postscript docs, get perlref-5.000.0.tar.gz. A LaTeX
+and postscript reference card is available at
+  ftp.NL.net:/pub/comp/programming/languages/perl/perlref-5.000.0.tar.gz
+  prep.ai.mit.edu:/pub/gnu/perlref-5.000.0.tar.gz
+
+Many REXX DLLs complement the features available by standard Perl,
+supporting system calls (YdbaUtil - RXU??.ZIP), xBase (RexxBase,
+shareware), serial I/O (RxAsync) and basic PM dialogs (VRexx). These
+packages can be found at many OS/2 FTP servers.
+
+-----------------------------------------------------------------------------
+Installation:
+-------------
+
+If you did not have HPFS up to now, this is the right time to reformat
+your filesystem(s)... While Perl itself does not require HPFS, a lot
+of Perl library files do. Or try EMXOPT=-t.
+
+copy perl5.exe perl5x.exe `some PATH dir`
+copy os2\perlglob.exe `some PATH dir`
+copy perl5.dll `some LIBPATH dir`
+
+set PERL5LIB=x:/your/own/perl/lib;y:/somewhere/perl5/lib
+
+The perl5 extension DLLs (POSIX_.DLL, REXX_.DLL, ...) do not need a
+LIBPATH entry.
+
+Executables:
+------------
+
+perl5.exe,perl5.dll :	DynaLoader, REXX support, external DLLs
+
+			No fork. Running a command via open() returns 1
+			instead of the child process id.
+
+			Other modules supported via extension DLLs, no
+			builtins other than DynaLoader.
+
+perl5x.exe :		No Dynaloader, no REXX.
+
+			Supports fork. Running a command via open() uses fork
+			(slow) and correctly returns the child process id.
+
+			POSIX and Socket modules builtin. No other extension
+			modules supported.
+
+			Note that lib/Socket.pm and lib/POSIX.pm reflect
+			DLL use. If you need them with perl5x.exe, you
+			have to remove the "bootstrap" line.
+
+-----------------------------------------------------------------------------
+Building:
+---------
+
+Requires:
+- Perl5.001.tar.gz (Perl 5.001 sources).
+- EMX 0.9a05 or later (Compiler).
+- OS/2 Development Toolkit (or change REXX inc/lib references).
+- Korn shell (ksh) or some other Unix-like shell named ksh.
+- DMake, with group recipes configured for a Unix shell.
+- Larry Walls "patch" program.
+- Several Unix-like tools, such as cp, cat, touch, find, ...
+
+get Perl 5.001 source
+apply patches\*		-- "official unofficial" patches to 5.001
+apply os2\patches	-- OS/2 platform patches
+copy ext\DynaLoader\dl_os2.xs ext\DynaLoader\DynaLoader.xs
+copy os2\config.sh .
+copy os2\makefile.mk .
+
+If you do not have UPM (User Profile Management), remove "UPM" from
+makefile.mk.
+
+-----------------------------------------------------------------------------
+Not supported, bugs, "OS/2 is Not Unix":
+----------------------------------------
+
+Depending on whether you run perl5.exe or perl5x.exe, you can either
+use extension modules and REXX, or fork, since the EMX implementation
+of fork conflicts with DLL support. Remember that there is a hidden
+fork in open(F, "-|") and open(F, "|-").
+
+config.sh (Config.pm) lies. It shows d_fork='undef' even though it is
+available in perl5x.exe. "dynamic_ext" and "extensions" are incorrect
+for perl5x.exe.
+
+flock is available but does not yet work in EMX 0.9a.
+
+ttyname and ctermid do not work (return NULL).
+
+... and of course a lot of Unix-isms like process group, user and group
+management, links, ...
+
+For details, look into config.sh and the EMX library reference.
+
+I did not test SDBM. I just added a lot of O_BINARY flags and compiled it.
+
+Several scripts of the test suite (see source distribution) fail due to
+Unix-isms like /bin/sh, `echo *`, different quoting requirements, ...
+
+When opening a command pipe [such as open(F,"cat|")], perl5.exe
+returns 1 instead of the child's process id. Perl5x.exe correctly
+returns the process id.
+
+OS/2 does not have a true exec API (which is used both by the exec
+function and when opening a command pipe with perl5x.exe). What
+actually happens is the call of a subprocess with the father waiting
+for the termination of its child. While waiting, the father still owns
+all its resources (it passes signals to the child however) and there
+may be some other side effects as well.
+
+-----------------------------------------------------------------------------
+OS2::REXX Module (external library):
+------------------------------------
+
+NOTE: By default, the REXX variable pool is not available, neither to
+Perl, nor to external REXX functions. To enable it, you have to start
+Perl with the switch -R, which makes Perl call its interpreter through
+REXX. REXX functions which do not use variables may be usable even
+without -R though.
+
+Load REXX DLL:
+
+	$dll = load OS2::REXX NAME [, WHERE];
+
+	NAME is DLL name, without path and extension.
+
+	Directories are searched WHERE first (list of dirs), then
+	environment paths PERL5REXX, PERLREXX or, as last resort, PATH.
+
+	The DLL is not unloaded when the variable dies.
+
+	Returns DLL object reference, or undef on failure.
+
+Define function prefix:
+
+	$dll->prefix(NAME);
+
+	Define the prefix of external functions, prepended to the
+	function names used within your program, when looking for
+	the entries in the DLL.
+
+	Example:
+		$dll = load OS2::REXX "RexxBase";
+		$dll->prefix("RexxBase_");
+		$dll->Init();
+	is the same as
+		$dll = load OS2::REXX "RexxBase";
+		$dll->RexxBase_Init();
+
+Define queue:
+
+	$dll->queue(NAME);
+
+	Define the name of the REXX queue passed to all external
+	functions of this module. Defaults to "SESSION".
+
+Check for functions (optional):
+
+	BOOL = $dll->find(NAME [, NAME [, ...]]);
+
+	Returns true if all functions are available.
+
+Call external REXX function:
+
+	$dll->function(arguments);
+
+	Returns the return string if the return code is 0, else undef.
+	Dies with error message if the function is not available.
+
+Bind scalar variable to REXX variable:
+
+	tie $var, OS2::REXX, "NAME";
+
+Bind array variable to REXX stem variable:
+
+	tie @var, OS2::REXX, "NAME.";
+
+	Only scalar operations work so far. No array assignments,
+	no array operations, ... FORGET IT.
+
+Bind hash array variable to REXX stem variable:
+
+	tie %var, OS2::REXX, "NAME.";
+
+	To access all visible REXX variables via hash array, bind to "";
+
+	No array assignments. No array operations, other than hash array
+	operations. Just like the *dbm based implementations.
+
+	For the usual REXX stem variables, append a "." to the name,
+	as shown above. If the hash key is part of the stem name, for
+	example if you bind to "", you cannot use lower case in the stem
+	part of the key and it is subject to character set restrictions.
+
+Erase individual REXX variables (bound or not):
+
+	OS2::REXX::drop("NAME" [, "NAME" [, ...]]);
+
+Note that while function and variable names are case insensitive in the
+REXX language, function names exported by a DLL and the REXX variables
+(as seen by Perl through the chosen API) are all case sensitive!
+
+Most REXX DLLs export function names all upper case, but there are a
+few which export mixed case names (such as RxExtras). When trying to
+find the entry point, both exact case and all upper case are searched.
+If the DLL exports "RxNap", you have to specify the exact case, if it
+exports "RXOPEN", you can use any case.
+
+To avoid interfering with subroutine names defined by Perl (DESTROY)
+or used within the REXX module (prefix, find), it is best to use mixed
+case and to avoid lowercase only or uppercase only names when calling
+REXX functions. Be consistent. The same function written in different
+ways results in different Perl stubs.
+
+There is no REXX interpolation on variable names, so the REXX variable
+name TEST.ONE is not affected by some other REXX variable ONE. And it
+is not the same variable as TEXT.one!
+
+You cannot call REXX functions which are not exported by the DLL.
+While most DLLs export all their functions, some, like RxFTP, export
+only "...LoadFuncs", which registers the functions within REXX only.
+
+You cannot call 16-bit DLLs. The few interesting ones I found
+(FTP,NETB,APPC) do not export their functions.
+
+I do not know whether the REXX API is reentrant with respect to
+exceptions (signals) when the REXX top-level exception handler is
+overridden. So unless you know better than I do, do not access REXX
+variables (probably tied to Perl variables) or call REXX functions
+which access REXX queues or REXX variables in signal handlers.
+
+See ext/OS2/REXX/rx*.pl for examples.
+
+-----------------------------------------------------------------------------
+OS2::UPM (external library):
+----------------------------
+
+UPM constants (see <upm.h>) are exported automatically, functions only
+on request.
+
+(USERID, TYPE) = local_user ()
+
+	return local user
+
+LIST = user_list (REMOTENODE="", REMOTETYPE_UPM_LOCAL)
+	LIST = 4 items per logged on user
+		[0] = user id
+		[1] = remote node name
+		[2] = remote node type (INT)
+		[3] = session id (INT)
+
+(USERID, TYPE) = local_logon ()
+
+	do a local logon, PM window, if not already logged on
+
+BOOL = logon (USERID, PASSWORD, AUTHCHECK=UPM_USER, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
+BOOL = logoff (USERID, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
+
+	logon/logoff process (DB2/2)
+
+BOOL = logon_user (USERID, PASSWORD, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
+BOOL = logoff_user (USERID, REMOTENODE="", REMOTETYPE=UPM_LOCAL)
+
+	logon/logoff user
+
+ERRCODE = error ()
+
+	return UPM error code of last failure
+
+STRING = message (ERRCODE)
+
+	return message text for supplied UPM error code
+
+Defaults:
+	REMOTETYPE = UPM_LOCAL
+	REMOTENODE = ""
+	AUTHCHECK  = UPM_USER
+
+-----------------------------------------------------------------------------
+OS2::FTP (external library):
+----------------------------
+
+$acct = new FTP "host", "userid", "passwd" [, "acct"]
+
+	Create virtual FTP session - no login.
+
+FTP::logoff()
+
+	Logoff all sessions.
+
+($msec, $address) = FTP::ping("host", pktlen);
+$msec = FTP::ping($address, pktlen);
+
+	Ping host. Returns milliseconds or negative error code.
+	$address is 32-bit number.
+
+$errno = $acct->errno();
+
+	Return last error code (FTP*).
+
+$text = FTP::message($errno);
+
+	Return message test of last error.
+
+$status:  <0 on error, >=0 on success.
+$tfrtype: T_BINARY, T_ASCII, T_EBCDIC
+"mode":   "w" for overwrite, "a" for append
+
+$status = $acct->dir("local", "pattern"="*");
+$status = $acct->ls("local", "pattern"="*");
+
+$status = $acct->chdir("dir");
+$status = $acct->mkdir("dir");
+$status = $acct->rmdir("dir");
+($status, $cwd) = $acct->getcwd();
+
+$status = $acct->get("local", "remote"=local, "mode"="w", $tfrtype=T_BINARY);
+
+$status = $acct->put("local", "remote"=local, $tfrtype=T_BINARY);
+$status = $acct->putunique("local", "remote"=local, $tfrtype=T_BINARY);
+$status = $acct->append("local", "remote"=local, $tfrtype=T_BINARY);
+
+$status = $acct->rename("from", "to");
+$status = $acct->delete("name");
+
+$status = $acct->proxy($source_acct, "dst_file", "src_file", $tfrtype=T_BINARY);
+
+$status = $acct->quote("string");
+$status = $acct->site("string");
+($status, $infostring) = $acct->sys();
+
+-----------------------------------------------------------------------------
+Other:
+------
+
+  setpriority CLASS,PID,DELTA
+
+	Set priority of process or process tree.
+
+	PID:
+		>= 0:	process only
+		<  0:	process tree
+
+	CLASS:
+		0	no change
+ 		1	idle-time	(lowest)
+  		2	regular		(dynamic priority)
+  		3	time-critical	(highest)
+  		4	fixed-high	(between regular and time-critical)
+
+	DELTA:
+		-31..+31
+
+  getpriority IGNORED,PID
+
+  	Return priority of process or process tree.
+
+		Bits 8..15	priority class (1..4)
+		Bits 0..7	priority within class (0..31)
+
+  system LIST
+
+	If the first element of LIST is an integer, it controls the
+	started child process or session as follows:
+
+		0	= wait until child terminates (default)
+		1	= do not wait, use wait() or waitpid() for status
+		4	= new session
+		5	= detached
+		6	= PM program
+
+	PM and session options, or-ed in:
+
+		0x00000	= default
+		0x00100	= minimized
+		0x00200	= maximized
+		0x00300	= fullscreen (session only)
+		0x00400	= windowed (session only)
+
+		0x00000	= foreground (only if running in foreground)
+		0x01000	= background
+
+		0x02000	= don't close window on exit (session only)
+
+		0x10000 = quote all arguments
+		0x20000	= MKS argument passing convention
+
+	If the control is not zero, system() does not wait until
+	the child terminates and the return code is the id of the
+	child process.
+
+	If the control is not zero, and you do not call wait or
+	waitpid, the child status fills up memory.
+
+	Note: If the program is started with a mode of 4 or 6, it may
+	be aborted when the starting program (perl) terminates. Later
+	releases of EMX.DLL will probably know yet another flag bit
+	to cut this fatal relationship.
+
+  system STRING
+  exec STRING
+
+	If the string starts with "@" or contains any of "%&|<>",
+	it is called as a shell command. Else the program is called
+	directly.
+
+	If the environment variable SHELL is defined, it is used
+	instead of COMSPEC when running shell commands. It should
+	be a Unix-style shell.
+
+  file checks (-X), stat(), ...
+
+  	When testing filenames, not handles, char-devices are detected
+  	only when prefixed by "/dev/", so "/dev/con" is valid, "con" is
+  	not.
+
+	Currently, only /dev/con and /dev/tty are recognized.
+
+-----------------------------------------------------------------------------
+History:
+
+15.12.94 	Initial release (perl5000.zip).
+
+17.12.94	Moved REXX sub defn to find(). Hash array for functions no
+		longer required, allows overriding subs like "find".
+
+		DLL entries are case sensitive, try both upper case and
+		exact case.
+
+18.12.94	Detect char- and block-devices (stat() hack). Some future
+		release may probably remove block device support, once
+		char-device support is built into EMX.
+
+		Fixed perl5db tty check.
+
+22.12.94	EMX fixlevel 2 exports its exception handler, so now
+		signals work even when the REXX variable pool is enabled.
+
+		Disabled error and exception popups.
+
+27.12.94	Case conversions of tied variables cleaned up.
+
+		REXX (REXX.DLL, REXXAPI.DLL) now loaded on demand.
+
+7.1.95		Fixed Shell module (did not allow more than one argument).
+
+11.1.95		Accept drive letter as absolute path in do/require/use.
+
+13.1.95		Larrys memory-leak patches (#1, dated Friday 13).
+
+26.1.95		fcntl and ioctl were missing. fcntl was explicitly disabled
+		in its source code (ifndef DOSISH) and the ioctl enabler is
+		in the wrong place (unixish.h instead of config.sh).
+
+16.3.95 	DosQueryFSAttach (stat hack) may crash the system. Now just
+		look for /dev/con and /dev/tty.
+
+		Applied "pad_findlex" patch (patches/1).
+
+23.3.95		Support fork. Two executables, one for DLLs and one for fork.
+
+24.3.95	5.001
+
+13.4.95		Patchlevel "c".
+
+21.4.95		Truncate names of extension DLLs to 8 chars - Warp no longer
+		accepts them (2.x did).
+
+22.4.95		Replaced EMX dirent by my own to get all directory entries
+		even when HPFS386 is used. Additionally, my implementation
+		is not restricted in the total size of the directory (a
+		conflict between Perls memory allocator and the one of the
+		EMX library DLL).
+
+27.4.95		Support for fork() disabled system() in DLL version.
+
+7.5.95		Added Tye McQueen's FileGlob. See File::KGlob*.
+
+12.5.95		Fixed Cwd. Fixed OS/2 dependencies in MakeMaker, with
+		a few Config.sh items added (separators, exe-extension).
+
+		Moved UPM and REXX to OS2::. Combined REXXCALL and REXX.
+		Plain old REXX module is still available as passthru though.
+
+		Perl DLLs now have an underscore appended to avoid name
+		conflicts with standard OS/2 DLLs (see DynaLoader.pm).
+
+13.5.95		Added FTP API support (OS2::FTP).
+		
+2.7.95		Applied "official unofficial" patches up to level "m".
+		The modpods documentation now is in the modules themselves.
+
+4.7.95		Implement command pipes (my_popen) using fork instead of
+		standard popen in the fork version (perl5x.exe). While this
+		is a lot slower, it correctly returns the process id and
+		supports open(F,"-|") and open(F,"|-").
+
+		Use the same code for exec(CMD) as for system(CMD).
+
+		Support socket functions (set|get|end)(host|net|proto|serv)ent.