This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
better diagnostic for do{} used as lvalue
[perl5.git] / README.win32
CommitLineData
68dc0745
PP
1If you read this file _as_is_, just ignore the funny characters you
2see. It is written in the POD format (see pod/perlpod.pod) which is
3specially designed to be readable as is.
4
5=head1 NAME
6
5aabfad6 7perlwin32 - Perl under Win32
68dc0745
PP
8
9=head1 SYNOPSIS
10
7bac28a0 11These are instructions for building Perl under Windows NT (versions
9036c72f 123.51 or 4.0). Currently, this port is reported to build
26618a56
GS
13under Windows95 using the 4DOS shell--the default shell that infests
14Windows95 will not work (see below). Note this caveat is only about
3e3baf6d
TB
15B<building> perl. Once built, you should be able to B<use> it on
16either Win32 platform (modulo the problems arising from the inferior
17command shell).
68dc0745
PP
18
19=head1 DESCRIPTION
20
3fe9a6f1 21Before you start, you should glance through the README file
68dc0745
PP
22found in the top-level directory where the Perl distribution
23was extracted. Make sure you read and understand the terms under
24which this software is being distributed.
25
f7c603cb 26Also make sure you read L<BUGS AND CAVEATS> below for the
68dc0745
PP
27known limitations of this port.
28
29The INSTALL file in the perl top-level has much information that is
30only relevant to people building Perl on Unix-like systems. In
31particular, you can safely ignore any information that talks about
32"Configure".
33
7bac28a0
PP
34You may also want to look at two other options for building
35a perl that will work on Windows NT: the README.cygwin32 and
3e3baf6d
TB
36README.os2 files, which each give a different set of rules to build
37a Perl that will work on Win32 platforms. Those two methods will
7bac28a0
PP
38probably enable you to build a more Unix-compatible perl, but you
39will also need to download and use various other build-time and
40run-time support software described in those files.
68dc0745
PP
41
42This set of instructions is meant to describe a so-called "native"
43port of Perl to Win32 platforms. The resulting Perl requires no
44additional software to run (other than what came with your operating
9036c72f
GS
45system). Currently, this port is capable of using one of the
46following compilers:
47
48 Borland C++ version 5.02 or later
49 Microsoft Visual C++ version 4.2 or later
50 Mingw32 with EGCS version 1.0.2
51 Mingw32 with GCC version 2.8.1
52
a29d2910
A
53The last two of these are high quality freeware compilers. Support
54for them is still experimental.
5aabfad6
PP
55
56This port currently supports MakeMaker (the set of modules that
57is used to build extensions to perl). Therefore, you should be
58able to build and install most extensions found in the CPAN sites.
c90c0ff4 59See L<Usage Hints> below for general hints about this.
68dc0745
PP
60
61=head2 Setting Up
62
63=over 4
64
3e3baf6d 65=item Command Shell
68dc0745 66
26618a56
GS
67Use the default "cmd" shell that comes with NT. Some versions of the
68popular 4DOS/NT shell have incompatibilities that may cause you trouble.
69If the build fails under that shell, try building again with the cmd
70shell. The Makefile also has known incompatibilites with the "command.com"
71shell that comes with Windows95, so building under Windows95 should
72be considered "unsupported". However, there have been reports of successful
b8957cf1 73build attempts using 4DOS/NT version 6.01 under Windows95, using dmake, but
26618a56
GS
74your mileage may vary.
75
76The surest way to build it is on WindowsNT, using the cmd shell.
68dc0745 77
3e3baf6d
TB
78=item Borland C++
79
80If you are using the Borland compiler, you will need dmake, a freely
81available make that has very nice macro features and parallelability.
82(The make that Borland supplies is seriously crippled, and will not
26618a56
GS
83work for MakeMaker builds.)
84
85A port of dmake for win32 platforms is available from:
3e3baf6d 86
26618a56
GS
87 http://www-personal.umich.edu/~gsar/dmake-4.1-win32.zip
88
89Fetch and install dmake somewhere on your path (follow the instructions
90in the README.NOW file).
3e3baf6d
TB
91
92=item Microsoft Visual C++
68dc0745 93
3e3baf6d 94The NMAKE that comes with Visual C++ will suffice for building.
9036c72f
GS
95You will need to run the VCVARS32.BAT file usually found somewhere
96like C:\MSDEV4.2\BIN. This will set your build environment.
68dc0745 97
26618a56
GS
98You can also use dmake to build using Visual C++, provided:
99you set OSRELEASE to "microsft" (or whatever the directory name
100under which the Visual C dmake configuration lives) in your environment,
101and edit win32/config.vc to change "make=nmake" into "make=dmake". The
102latter step is only essential if you want to use dmake as your default
103make for building extensions using MakeMaker.
3e3baf6d 104
9036c72f
GS
105=item Mingw32 with EGCS or GCC
106
107ECGS-1.0.2 binaries can be downloaded from:
108
109 ftp://ftp.xraylith.wisc.edu/pub/khan/gnu-win32/mingw32/
68dc0745 110
9036c72f 111GCC-2.8.1 binaries are available from:
68dc0745 112
9036c72f 113 http://agnes.dida.physik.uni-essen.de/~janjaap/mingw32/
68dc0745 114
9036c72f
GS
115You only need either one of those, not both. Both bundles come with
116Mingw32 libraries and headers. While both of them work to build perl,
117the EGCS binaries are currently favored by the maintainers, since they
118come with more up-to-date Mingw32 libraries.
119
120Make sure you install the binaries as indicated in the web sites
121above. You will need to set up a few environment variables (usually
122run from a batch file).
68dc0745
PP
123
124=back
125
137443ea 126=head2 Building
68dc0745
PP
127
128=over 4
129
130=item *
131
68dc0745 132Make sure you are in the "win32" subdirectory under the perl toplevel.
137443ea 133This directory contains a "Makefile" that will work with
9036c72f
GS
134versions of NMAKE that come with Visual C++, and a dmake "makefile.mk"
135that will work for all supported compilers. The defaults in the dmake
136makefile are setup to build using the Borland compiler.
68dc0745
PP
137
138=item *
139
9036c72f
GS
140Edit the makefile.mk (or Makefile, if using nmake) and change the values
141of INST_DRV and INST_TOP. You can also enable various build
26618a56
GS
142flags.
143
9036c72f
GS
144Beginning with version 5.005, there is experimental support for building
145a perl interpreter that supports the Perl Object abstraction (courtesy
146ActiveState Tool Corp.) PERL_OBJECT uses C++, and the binaries are
147therefore incompatible with the regular C build. However, the
148PERL_OBJECT build does provide something called the C-API, for linking
a29d2910 149it with extensions that won't compile under PERL_OBJECT. PERL_OBJECT
9cde0e7f
GS
150is not yet supported under GCC or EGCS. WARNING: Binaries built with
151PERL_OBJECT enabled are B<not> compatible with binaries built without.
152Perl installs PERL_OBJECT binaries under a distinct architecture name,
153so they B<can> coexist, though.
9036c72f
GS
154
155Beginning with version 5.005, there is experimental support for building
156a perl interpreter that is capable of native threading. Binaries built
157with thread support enabled are also incompatible with the vanilla C
9cde0e7f
GS
158build. WARNING: Binaries built with threads enabled are B<not> compatible
159with binaries built without. Perl installs threads enabled binaries under
160a distinct architecture name, so they B<can> coexist, though.
9036c72f
GS
161
162At the present time, you cannot enable both threading and PERL_OBJECT.
163You can get only one of them in a Perl interpreter.
164
26618a56
GS
165If you have either the source or a library that contains des_fcrypt(),
166enable the appropriate option in the makefile. des_fcrypt() is not
167bundled with the distribution due to US Government restrictions
168on the export of cryptographic software. Nevertheless, this routine
169is part of the "libdes" library (written by Ed Young) which is widely
170available worldwide, usually along with SSLeay (for example:
171"ftp://fractal.mta.ca/pub/crypto/SSLeay/DES/"). Set CRYPT_SRC to the
172name of the file that implements des_fcrypt(). Alternatively, if
173you have built a library that contains des_fcrypt(), you can set
2d77217b
GS
174CRYPT_LIB to point to the library name. The location above contains
175many versions of the "libdes" library, all with slightly different
176implementations of des_fcrypt(). Older versions have a single,
177self-contained file (fcrypt.c) that implements crypt(), so they may be
178easier to use. A patch against the fcrypt.c found in libdes-3.06 is
179in des_fcrypt.patch.
26618a56
GS
180
181Perl will also build without des_fcrypt(), but the crypt() builtin will
182fail at run time.
c90c0ff4 183
3e3baf6d
TB
184You will also have to make sure CCHOME points to wherever you installed
185your compiler.
c90c0ff4 186
9036c72f
GS
187Other options are explained in the makefiles. Be sure to read the
188instructions carefully.
189
68dc0745
PP
190=item *
191
9036c72f 192Type "dmake" (or "nmake" if you are using that make).
68dc0745 193
137443ea 194This should build everything. Specifically, it will create perl.exe,
9036c72f
GS
195perl.dll (or perlcore.dll), and perlglob.exe at the perl toplevel, and
196various other extension dll's under the lib\auto directory. If the build
197fails for any reason, make sure you have done the previous steps correctly.
68dc0745 198
156a3eb7
GS
199The build process may produce "harmless" compiler warnings (more or
200less copiously, depending on how picky your compiler gets). The
201maintainers are aware of these warnings, thankyouverymuch. :)
202
3e3baf6d
TB
203When building using Visual C++, a perl95.exe will also get built. This
204executable is only needed on Windows95, and should be used instead of
205perl.exe, and then only if you want sockets to work properly on Windows95.
206This is necessitated by a bug in the Microsoft C Runtime that cannot be
26618a56
GS
207worked around in the "normal" perl.exe. perl95.exe gets built with its
208own private copy of the C Runtime that is not accessible to extensions
209(which see the DLL version of the CRT). Be aware, therefore, that this
210perl95.exe will have esoteric problems with extensions like perl/Tk that
211themselves use the C Runtime heavily, or want to free() pointers
212malloc()-ed by perl.
3e3baf6d
TB
213
214You can avoid the perl95.exe problems completely if you use Borland
215C++ for building perl (perl95.exe is not needed and will not be built
216in that case).
217
68dc0745
PP
218=back
219
220=head2 Testing
221
9036c72f 222Type "dmake test" (or "nmake test"). This will run most of the tests from
3e3baf6d 223the testsuite (many tests will be skipped, and but no test should fail).
68dc0745 224
8b88ae92 225If some tests do fail, it may be because you are using a different command
137443ea 226shell than the native "cmd.exe".
68dc0745 227
3e3baf6d
TB
228If you used the Borland compiler, you may see a failure in op/taint.t
229arising from the inability to find the Borland Runtime DLLs on the system
230default path. You will need to copy the DLLs reported by the messages
231from where Borland chose to install it, into the Windows system directory
232(usually somewhere like C:\WINNT\SYSTEM32), and rerun the test.
233
9036c72f
GS
234The Visual C runtime apparently has a bug that causes posix.t to fail
235one it test#2. This usually happens only if you extracted the files in
236text mode.
237
3e3baf6d 238Please report any other failures as described under L<BUGS AND CAVEATS>.
68dc0745 239
137443ea
PP
240=head2 Installation
241
9036c72f 242Type "dmake install" (or "nmake install"). This will put the newly
26618a56
GS
243built perl and the libraries under whatever C<INST_TOP> points to in the
244Makefile. It will also install the pod documentation under
9036c72f
GS
245C<$INST_TOP\$VERSION\lib\pod> and HTML versions of the same under
246C<$INST_TOP\$VERSION\lib\pod\html>. To use the Perl you just installed,
247you will need to add two components to your PATH environment variable,
248C<$INST_TOP\$VERSION\bin>, and C<$INST_TOP\$VERSION\bin\$ARCHNAME>.
249For example:
250
251 set PATH c:\perl\5.005\bin;c:\perl\5.005\bin\MSWin32-x6;%PATH%
252
137443ea 253
7bac28a0
PP
254=head2 Usage Hints
255
256=over 4
257
258=item Environment Variables
259
260The installation paths that you set during the build get compiled
261into perl, so you don't have to do anything additional to start
262using that perl (except add its location to your PATH variable).
263
264If you put extensions in unusual places, you can set PERL5LIB
265to a list of paths separated by semicolons where you want perl
266to look for libraries. Look for descriptions of other environment
26618a56
GS
267variables you can set in L<perlrun>.
268
269You can also control the shell that perl uses to run system() and
270backtick commands via PERL5SHELL. See L<perlrun>.
7bac28a0 271
9036c72f
GS
272Currently, Perl does not depend on the registry, but can look up
273values if you choose to put them there. [XXX add registry locations
274that perl looks at here.]
7bac28a0 275
3e3baf6d
TB
276=item File Globbing
277
278By default, perl spawns an external program to do file globbing.
279The install process installs both a perlglob.exe and a perlglob.bat
280that perl can use for this purpose. Note that with the default
281installation, perlglob.exe will be found by the system before
282perlglob.bat.
283
284perlglob.exe relies on the argv expansion done by the C Runtime of
285the particular compiler you used, and therefore behaves very
286differently depending on the Runtime used to build it. To preserve
dfb634a9
GS
287compatiblity, perlglob.bat (a perl script that can be used portably)
288is installed. Besides being portable, perlglob.bat also offers
289enhanced globbing functionality.
3e3baf6d
TB
290
291If you want perl to use perlglob.bat instead of perlglob.exe, just
292delete perlglob.exe from the install location (or move it somewhere
dfb634a9
GS
293perl cannot find). Using File::DosGlob.pm (which implements the core
294functionality of perlglob.bat) to override the internal CORE::glob()
295works about 10 times faster than spawing perlglob.exe, and you should
296take this approach when writing new modules. See File::DosGlob for
297details.
3e3baf6d 298
7bac28a0
PP
299=item Using perl from the command line
300
301If you are accustomed to using perl from various command-line
302shells found in UNIX environments, you will be less than pleased
303with what Windows NT offers by way of a command shell.
304
305The crucial thing to understand about the "cmd" shell (which is
306the default on Windows NT) is that it does not do any wildcard
307expansions of command-line arguments (so wildcards need not be
308quoted). It also provides only rudimentary quoting. The only
309(useful) quote character is the double quote ("). It can be used to
310protect spaces in arguments and other special characters. The
311Windows NT documentation has almost no description of how the
312quoting rules are implemented, but here are some general observations
313based on experiments: The shell breaks arguments at spaces and
314passes them to programs in argc/argv. Doublequotes can be used
315to prevent arguments with spaces in them from being split up.
316You can put a double quote in an argument by escaping it with
317a backslash and enclosing the whole argument within double quotes.
318The backslash and the pair of double quotes surrounding the
319argument will be stripped by the shell.
320
321The file redirection characters "<", ">", and "|" cannot be quoted
322by double quotes (there are probably more such). Single quotes
323will protect those three file redirection characters, but the
324single quotes don't get stripped by the shell (just to make this
325type of quoting completely useless). The caret "^" has also
326been observed to behave as a quoting character (and doesn't get
327stripped by the shell also).
328
329Here are some examples of usage of the "cmd" shell:
330
331This prints two doublequotes:
332
333 perl -e "print '\"\"' "
334
335This does the same:
336
337 perl -e "print \"\\\"\\\"\" "
338
339This prints "bar" and writes "foo" to the file "blurch":
340
341 perl -e "print 'foo'; print STDERR 'bar'" > blurch
342
343This prints "foo" ("bar" disappears into nowhereland):
344
345 perl -e "print 'foo'; print STDERR 'bar'" 2> nul
346
347This prints "bar" and writes "foo" into the file "blurch":
348
349 perl -e "print 'foo'; print STDERR 'bar'" 1> blurch
350
7bac28a0
PP
351This pipes "foo" to the "less" pager and prints "bar" on the console:
352
353 perl -e "print 'foo'; print STDERR 'bar'" | less
354
355This pipes "foo\nbar\n" to the less pager:
356
7bac28a0
PP
357 perl -le "print 'foo'; print STDERR 'bar'" 2>&1 | less
358
359This pipes "foo" to the pager and writes "bar" in the file "blurch":
360
361 perl -e "print 'foo'; print STDERR 'bar'" 2> blurch | less
362
363
84902520 364Discovering the usefulness of the "command.com" shell on Windows95
7bac28a0
PP
365is left as an exercise to the reader :)
366
367=item Building Extensions
368
369The Comprehensive Perl Archive Network (CPAN) offers a wealth
370of extensions, some of which require a C compiler to build.
371Look in http://www.perl.com/ for more information on CPAN.
372
373Most extensions (whether they require a C compiler or not) can
374be built, tested and installed with the standard mantra:
375
376 perl Makefile.PL
3e3baf6d
TB
377 $MAKE
378 $MAKE test
379 $MAKE install
7bac28a0 380
3e3baf6d
TB
381where $MAKE stands for NMAKE or DMAKE. Some extensions may not
382provide a testsuite (so "$MAKE test" may not do anything, or fail),
383but most serious ones do.
7bac28a0 384
3e3baf6d
TB
385If a module implements XSUBs, you will need one of the supported
386C compilers. You must make sure you have set up the environment for
387the compiler for command-line compilation.
7bac28a0 388
3e3baf6d 389If a module does not build for some reason, look carefully for
7bac28a0
PP
390why it failed, and report problems to the module author. If
391it looks like the extension building support is at fault, report
392that with full details of how the build failed using the perlbug
393utility.
394
9cde0e7f
GS
395=item Command-line Wildcard Expansion
396
397The default command shells on DOS descendant operating systems (such
398as they are) usually do not expand wildcard arguments supplied to
399programs. They consider it the application's job to handle that.
400This is commonly achieved by linking the application (in our case,
401perl) with startup code that the C runtime libraries usually provide.
402However, doing that results in incompatible perl versions (since the
403behavior of the argv expansion code differs depending on the
404compiler, and it is even buggy on some compilers). Besides, it may
405be a source of frustration if you use such a perl binary with an
406alternate shell that *does* expand wildcards.
407
408Instead, the following solution works rather well. The nice things
409about it: 1) you can start using it right away 2) it is more powerful,
410because it will do the right thing with a pattern like */*/*.c
4113) you can decide whether you do/don't want to use it 4) you can
412extend the method to add any customizations (or even entirely
413different kinds of wildcard expansion).
414
415 C:\> copy con c:\perl\lib\Wild.pm
416 # Wild.pm - emulate shell @ARGV expansion on shells that don't
417 use File::DosGlob;
418 @ARGV = map {
419 my @g = File::DosGlob::glob($_) if /[*?]/;
420 @g ? @g : $_;
421 } @ARGV;
422 1;
423 ^Z
424 C:\> set PERL5OPT=-MWild
425 C:\> perl -le "for (@ARGV) { print }" */*/perl*.c
426 p4view/perl/perl.c
427 p4view/perl/perlio.c
428 p4view/perl/perly.c
429 perl5.005/win32/perlglob.c
430 perl5.005/win32/perllib.c
431 perl5.005/win32/perlglob.c
432 perl5.005/win32/perllib.c
433 perl5.005/win32/perlglob.c
434 perl5.005/win32/perllib.c
435
436Note there are two distinct steps there: 1) You'll have to create
437Wild.pm and put it in your perl lib directory. 2) You'll need to
438set the PERL5OPT environment variable. If you want argv expansion
439to be the default, just set PERL5OPT in your default startup
440environment.
441
442If you are using the Visual C compiler, you can get the C runtime's
443command line wildcard expansion built into perl binary. The resulting
444binary will always expand unquoted command lines, which may not be
445what you want if you use a shell that does that for you. The expansion
446done is also somewhat less powerful than the approach suggested above.
447
c90c0ff4
PP
448=item Win32 Specific Extensions
449
450A number of extensions specific to the Win32 platform are available
451from CPAN. You may find that many of these extensions are meant to
452be used under the Activeware port of Perl, which used to be the only
453native port for the Win32 platform. Since the Activeware port does not
454have adequate support for Perl's extension building tools, these
455extensions typically do not support those tools either, and therefore
456cannot be built using the generic steps shown in the previous section.
457
458To ensure smooth transitioning of existing code that uses the
9036c72f
GS
459ActiveState port, there is a bundle of Win32 extensions that contains
460all of the ActiveState extensions and most other Win32 extensions from
c90c0ff4
PP
461CPAN in source form, along with many added bugfixes, and with MakeMaker
462support. This bundle is available at:
463
9036c72f 464 http://www.perl.com/CPAN/authors/id/GSAR/libwin32-0.12.zip
c90c0ff4
PP
465
466See the README in that distribution for building and installation
467instructions. Look for later versions that may be available at the
468same location.
469
156a3eb7
GS
470=item Running Perl Scripts
471
472Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
473indicate to the OS that it should execute the file using perl.
474Win32 has no comparable means to indicate arbitrary files are
475executables.
476
477Instead, all available methods to execute plain text files on
478Win32 rely on the file "extension". There are three methods
479to use this to execute perl scripts:
480
481=over 8
482
483=item 1
484
485There is a facility called "file extension associations" that will
486work in Windows NT 4.0. This can be manipulated via the two
487commands "assoc" and "ftype" that come standard with Windows NT
4884.0. Type "ftype /?" for a complete example of how to set this
489up for perl scripts (Say what? You thought Windows NT wasn't
490perl-ready? :).
491
492=item 2
493
494Since file associations don't work everywhere, and there are
495reportedly bugs with file associations where it does work, the
496old method of wrapping the perl script to make it look like a
497regular batch file to the OS, may be used. The install process
498makes available the "pl2bat.bat" script which can be used to wrap
499perl scripts into batch files. For example:
500
501 pl2bat foo.pl
502
503will create the file "FOO.BAT". Note "pl2bat" strips any
504.pl suffix and adds a .bat suffix to the generated file.
505
506If you use the 4DOS/NT or similar command shell, note that
507"pl2bat" uses the "%*" variable in the generated batch file to
508refer to all the command line arguments, so you may need to make
509sure that construct works in batch files. As of this writing,
5104DOS/NT users will need a "ParameterChar = *" statement in their
5114NT.INI file, or will need to execute "setdos /p*" in the 4DOS/NT
512startup file to enable this to work.
513
514=item 3
515
516Using "pl2bat" has a few problems: the file name gets changed,
517so scripts that rely on C<$0> to find what they must do may not
518run properly; running "pl2bat" replicates the contents of the
519original script, and so this process can be maintenance intensive
520if the originals get updated often. A different approach that
521avoids both problems is possible.
522
523A script called "runperl.bat" is available that can be copied
524to any filename (along with the .bat suffix). For example,
525if you call it "foo.bat", it will run the file "foo" when it is
526executed. Since you can run batch files on Win32 platforms simply
527by typing the name (without the extension), this effectively
528runs the file "foo", when you type either "foo" or "foo.bat".
529With this method, "foo.bat" can even be in a different location
530than the file "foo", as long as "foo" is available somewhere on
531the PATH. If your scripts are on a filesystem that allows symbolic
532links, you can even avoid copying "runperl.bat".
533
534Here's a diversion: copy "runperl.bat" to "runperl", and type
535"runperl". Explain the observed behavior, or lack thereof. :)
536Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
537
538=back
539
7bac28a0
PP
540=item Miscellaneous Things
541
542A full set of HTML documentation is installed, so you should be
543able to use it if you have a web browser installed on your
544system.
545
546C<perldoc> is also a useful tool for browsing information contained
547in the documentation, especially in conjunction with a pager
548like C<less> (recent versions of which have Win32 support). You may
549have to set the PAGER environment variable to use a specific pager.
550"perldoc -f foo" will print information about the perl operator
551"foo".
552
553If you find bugs in perl, you can run C<perlbug> to create a
554bug report (you may have to send it manually if C<perlbug> cannot
555find a mailer on your system).
556
557=back
558
68dc0745
PP
559=head1 BUGS AND CAVEATS
560
f7c603cb
GS
561An effort has been made to ensure that the DLLs produced by the two
562supported compilers are compatible with each other (despite the
563best efforts of the compiler vendors). Extension binaries produced
564by one compiler should also coexist with a perl binary built by
565a different compiler. In order to accomplish this, PERL.DLL provides
566a layer of runtime code that uses the C Runtime that perl was compiled
567with. Extensions which include "perl.h" will transparently access
568the functions in this layer, thereby ensuring that both perl and
569extensions use the same runtime functions.
68dc0745 570
8b88ae92
NIS
571If you have had prior exposure to Perl on Unix platforms, you will notice
572this port exhibits behavior different from what is documented. Most of the
7bac28a0
PP
573differences fall under one of these categories. We do not consider
574any of them to be serious limitations (especially when compared to the
575limited nature of some of the Win32 OSes themselves :)
68dc0745
PP
576
577=over 8
578
579=item *
580
581C<stat()> and C<lstat()> functions may not behave as documented. They
582may return values that bear no resemblance to those reported on Unix
7bac28a0
PP
583platforms, and some fields (like the the one for inode) may be completely
584bogus.
68dc0745
PP
585
586=item *
587
6890e559 588The following functions are currently unavailable: C<fork()>,
5aabfad6 589C<dump()>, C<chown()>, C<link()>, C<symlink()>, C<chroot()>,
26618a56
GS
590C<setpgrp()> and related security functions, C<setpriority()>,
591C<getpriority()>, C<syscall()>, C<fcntl()>, C<getpw*()>,
2d7a9237
GS
592C<msg*()>, C<shm*()>, C<sem*()>, C<alarm()>, C<socketpair()>,
593C<*netent()>, C<*protoent()>, C<*servent()>, C<*hostent()>,
594C<getnetby*()>.
26618a56 595This list is possibly incomplete.
6890e559
GS
596
597=item *
598
68dc0745
PP
599Various C<socket()> related calls are supported, but they may not
600behave as on Unix platforms.
601
602=item *
603
604The four-argument C<select()> call is only supported on sockets.
605
606=item *
607
f998180f
GS
608The C<ioctl()> call is only supported on sockets (where it provides the
609functionality of ioctlsocket() in the Winsock API).
610
611=item *
612
2d7a9237
GS
613Failure to spawn() a subprocess is indicated by setting $? to "255 << 8".
614C<$?> is set in a way compatible with Unix (i.e. the exitstatus of the
615subprocess is obtained by "$? >> 8", as described in the documentation).
68dc0745
PP
616
617=item *
618
26618a56
GS
619You can expect problems building modules available on CPAN if you
620build perl itself with -DUSE_THREADS. These problems should be resolved
621as we get closer to 5.005.
68dc0745
PP
622
623=item *
624
625C<utime()>, C<times()> and process-related functions may not
626behave as described in the documentation, and some of the
627returned values or effects may be bogus.
628
629=item *
630
3e3baf6d 631Signal handling may not behave as on Unix platforms (where it
f7c603cb
GS
632doesn't exactly "behave", either :). For instance, calling C<die()>
633or C<exit()> from signal handlers will cause an exception, since most
634implementations of C<signal()> on Win32 are severely crippled.
635Thus, signals may work only for simple things like setting a flag
636variable in the handler. Using signals under this port should
637currently be considered unsupported.
68dc0745
PP
638
639=item *
640
1a159553
GS
641C<kill()> is implemented, but doesn't have the semantics of
642C<raise()>, i.e. it doesn't send a signal to the identified process
643like it does on Unix platforms. Instead it immediately calls
644C<TerminateProcess(process,signal)>. Thus the signal argument is
645used to set the exit-status of the terminated process. This behavior
646may change in future.
647
648=item *
649
7bac28a0 650File globbing may not behave as on Unix platforms. In particular,
3e3baf6d
TB
651if you don't use perlglob.bat for globbing, it will understand
652wildcards only in the filename component (and not in the pathname).
653In other words, something like "print <*/*.pl>" will not print all the
654perl scripts in all the subdirectories one level under the current one
655(like it does on UNIX platforms). perlglob.exe is also dependent on
656the particular implementation of wildcard expansion in the vendor
657libraries used to build it (which varies wildly at the present time).
658Using perlglob.bat (or File::DosGlob) avoids these limitations, but
659still only provides DOS semantics (read "warts") for globbing.
68dc0745
PP
660
661=back
662
663Please send detailed descriptions of any problems and solutions that
664you may find to <F<perlbug@perl.com>>, along with the output produced
665by C<perl -V>.
666
667=head1 AUTHORS
668
669=over 4
670
3e3baf6d 671Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
68dc0745 672
3e3baf6d 673Gurusamy Sarathy E<lt>gsar@umich.eduE<gt>
68dc0745 674
3e3baf6d 675Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>
68dc0745
PP
676
677=back
678
f7c603cb
GS
679This document is maintained by Gurusamy Sarathy.
680
68dc0745
PP
681=head1 SEE ALSO
682
683L<perl>
684
685=head1 HISTORY
686
687This port was originally contributed by Gary Ng around 5.003_24,
688and borrowed from the Hip Communications port that was available
689at the time.
690
691Nick Ing-Simmons and Gurusamy Sarathy have made numerous and
692sundry hacks since then.
693
3e3baf6d
TB
694Borland support was added in 5.004_01 (Gurusamy Sarathy).
695
9036c72f 696Last updated: 12 July 1998
68dc0745
PP
697
698=cut
3e3baf6d 699