Re: [PATCH] pod/perlclib.pod - Replacements for C library functions

Message-ID: <20010131163143.A1427@pembro26.pmb.ox.ac.uk>

p4raw-id: //depot/perl@8772

6 files changed, 235 insertions, 112 deletions

diff --git a/MANIFEST b/MANIFEST
index 5c555f095c..61af6b5c25 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -1229,6 +1229,7 @@ pod/perlbook.pod	Perl book information
 pod/perlboot.pod	Beginner's Object-oriented Tutorial
 pod/perlbot.pod		Object-oriented Bag o' Tricks
 pod/perlcall.pod	Callback info
+pod/perlclib.pod	Internal replacements for standard C library functions
 pod/perlcompile.pod	Info on using the Compiler suite
 pod/perldata.pod	Data structure info
 pod/perldbmfilter.pod	Info about DBM Filters
diff --git a/pod/buildtoc.PL b/pod/buildtoc.PL
index 1e55649ca8..140341bb40 100644
--- a/pod/buildtoc.PL
+++ b/pod/buildtoc.PL
@@ -133,6 +133,7 @@ if (-d "pod") {
     perldebguts         
     perlxstut           
     perlxs              
+    perlclib            
     perlguts            
     perlcall            
     perlutil            
diff --git a/pod/perl.pod b/pod/perl.pod
index 1621b2f83b..fd55b8d85f 100644
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -87,6 +87,7 @@ For ease of access, the Perl manual has been split up into several sections:
     perldebguts		Perl debugging guts and tips
     perlxstut		Perl XS tutorial
     perlxs		Perl XS application programming interface
+    perlclib		Internal replacements for standard C library functions
     perlguts		Perl internal functions for those doing extensions
     perlcall		Perl calling conventions from C
     perlutil		utilities packaged with the Perl distribution
diff --git a/pod/perlclib.pod b/pod/perlclib.pod
new file mode 100644
index 0000000000..e2ae529237
--- /dev/null
+++ b/pod/perlclib.pod
@@ -0,0 +1,197 @@
+=head1 NAME
+
+perlclib - Internal replacements for standard C library functions
+
+=head1 DESCRIPTION
+
+One thing Perl porters should note is that F<perl> doesn't tend to use that
+much of the C standard library internally; you'll see very little use of, 
+for example, the F<ctype.h> functions in there. This is because Perl
+tends to reimplement or abstract standard library functions, so that we
+know exactly how they're going to operate.
+
+This is a reference card for people who are familiar with the C library
+and who want to do things the Perl way; to tells them which functions
+they ought to use instead of the more normal C functions. 
+
+=head2 Conventions
+
+In the following tables:
+
+=over 3
+
+=item C<t>
+
+is a type.
+
+=item C<p>
+
+is a pointer.
+
+=item C<n>
+
+is a number.
+
+=item C<s>
+
+is a string.
+
+=back
+
+C<sv>, C<av>, C<hv>, etc. represent variables of their respective types.
+
+=head2 File Operations
+
+Instead of the F<stdio.h> functions, you should use the Perl abstraction
+layer. Instead of C<FILE*> types, you need to be handling C<PerlIO*>
+types; don't forget that with the new PerlIO layered IO abstraction, 
+C<FILE*> types may not even be available. See also the C<perlapio>
+documentation for more information about the following functions:
+
+    Instead Of:                 Use:
+    
+    stdin                       PerlIO_stdin()
+    stdout                      PerlIO_stdout()
+    stderr                      PerlIO_stderr()
+
+    fopen(fn, mode)             PerlIO_open(fn, mode)
+    freopen(fn, mode, stream)   PerlIO_reopen(fn, mode, perlio) (Deprecated)
+    fflush(stream)              PerlIO_flush(perlio)
+    fclose(stream)              PerlIO_close(perlio)
+
+=head2 File Input and Output
+
+    Instead Of:                 Use:
+
+    fprintf(stream, fmt, ...)   PerlIO_printf(perlio, fmt, ...)
+
+    [f]getc(stream)             PerlIO_getc(perlio)
+    [f]putc(stream, n)          PerlIO_putc(perlio, n)
+    ungetc(n, stream)           PerlIO_ungetc(perlio, n)
+
+Note that the PerlIO equivalents of C<fread> and C<fwrite> are slightly
+different from their C library counterparts:
+
+    fread(p, size, n, stream)   PerlIO_read(perlio, buf, numbytes)
+    fwrite(p, size, n, stream)  PerlIO_write(perlio, buf, numbytes)
+
+    fputs(s, stream)            PerlIO_puts(perlio, s)
+
+There is no equivalent to C<fgets>; one should use C<sv_gets> instead:
+
+    fgets(s, n, stream)         sv_gets(sv, perlio, append)
+
+=head2 File Positioning
+
+    Instead Of:                 Use:
+
+    feof(stream)                PerlIO_eof(perlio)
+    fseek(stream, n, whence)    PerlIO_seek(perlio, n, whence)
+    rewind(stream)              PerlIO_rewind(perlio)
+
+    fgetpos(stream, p)          PerlIO_getpos(perlio, sv)
+    fsetpos(stream, p)          PerlIO_setpos(perlio, sv)
+
+    ferror(stream)              PerlIO_error(perlio)
+    clearerr(stream)            PerlIO_clearerr(perlio)
+
+=head2 Memory Management and String Handling
+
+    Instead Of:                 Use:
+
+    t* p = malloc(n)            New(id, p, n, t)
+    t* p = calloc(n, s)         Newz(id, p, n, t)
+    p = realloc(p, n)           Renew(p, n, t)
+    memcpy(dst, src, n)         Copy(src, dst, n, t)
+    memmove(dst, src, n)        Move(src, dst, n, t)
+    memcpy/*(struct foo *)      StructCopy(src, dst, t)
+    free(p)                     Safefree(p)
+
+    strdup(p)                   savepv(p)
+    strndup(p, n)               savepvn(p, n) (Hey, strndup doesn't exist!)
+
+    strstr(big, little)         instr(big, little)
+    strcmp(s1, s2)              strLE(s1, s2) / strEQ(s1, s2) / strGT(s1,s2)
+    strncmp(s1, s2, n)          strnNE(s1, s2, n) / strnEQ(s1, s2, n)
+
+Notice the different order of arguments to C<Copy> and C<Move> than used
+in C<memcpy> and C<memmove>.
+
+Most of the time, though, you'll want to be dealing with SVs internally
+instead of raw C<char *> strings:
+
+    strlen(s)                   sv_len(sv)
+    strcpy(dt, src)             sv_setpv(sv, s)
+    strncpy(dt, src, n)         sv_setpvn(sv, s, n)
+    strcat(dt, src)             sv_catpv(sv, s)
+    strncat(dt, src)            sv_catpvn(sv, s)
+    sprintf(s, fmt, ...)        sv_setpvf(sv, fmt, ...)
+
+Note also the existence of C<sv_catpvf> and C<sv_catpvfn>, combining
+concatenation with formatting.
+
+=head2 Character Class Tests
+
+There are two types of character class tests that Perl implements: one
+type deals in C<char>s and are thus B<not> Unicode aware (and hence
+deprecated unless you B<know> you should use them) and the other type
+deal in C<UV>s and know about Unicode properties. In the following
+table, C<c> is a C<char>, and C<u> is a Unicode codepoint.
+
+    Instead Of:                 Use:            But better use:
+
+    isalnum(c)                  isALNUM(c)      isALNUM_uni(u)
+    isalpha(c)                  isALPHA(c)      isALPHA_uni(u)
+    iscntrl(c)                  isCNTRL(c)      isCNTRL_uni(u)
+    isdigit(c)                  isDIGIT(c)      isDIGIT_uni(u)
+    isgraph(c)                  isGRAPH(c)      isGRAPH_uni(u)
+    islower(c)                  isLOWER(c)      isLOWER_uni(u)
+    isprint(c)                  isPRINT(c)      isPRINT_uni(u)
+    ispunct(c)                  isPUNCT(c)      isPUNCT_uni(u)
+    isspace(c)                  isSPACE(c)      isSPACE_uni(u)
+    isupper(c)                  isUPPER(c)      isUPPER_uni(u)
+    isxdigit(c)                 isXDIGIT(c)     isXDIGIT_uni(u)
+
+    tolower(c)                  toLOWER(c)      toLOWER_uni(u)
+    toupper(c)                  toUPPER(c)      toUPPER_uni(u)
+
+=head2 F<stdlib.h> functions
+
+    Instead Of:                 Use: 
+
+    atof(s)                     Atof(s)
+    atol(s)                     Atol(s)
+    strtod(s, *p)               Nothing. Just don't use it.
+    strtol(s, *p, n)            Strtol(s, *p, n)
+    strtoul(s, *p, n)           Strtoul(s, *p, n)
+
+Notice also the C<scan_bin>, C<scan_hex>, and C<scan_oct> functions in
+F<util.c> for converting strings representing numbers in the respective
+bases into C<NV>s.
+
+In theory C<Strtol> and C<Strtoul> may not be defined if the machine perl is
+built on doesn't actually have strtol and strtoul. But as those 2
+functions are part of the 1989 ANSI C spec we suspect you'll find them
+everywhere by now.
+
+    int rand()                  double Drand01()
+    srand(n)                    { seedDrand01((Rand_seed_t)n); 
+                                  PL_srand_called = TRUE; }
+ 
+    exit(n)                     my_exit(n)
+    system(s)                   Don't. Look at pp_system or use my_popen
+
+    getenv(s)                   PerlEnv_getenv(s)
+    setenv(s, val)              my_putenv(s, val)
+
+=head2 Miscellaneous functions
+
+You should not even B<want> to use F<setjmp.h> functions, but if you
+think you do, use the C<JMPENV> stack in F<scope.h> instead.
+
+For C<signal>/C<sigaction>, use C<rsignal(signo, handler)>.
+
+=head1 SEE ALSO
+
+C<perlapi>, C<perlapio>, C<perlguts>
+
diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index 8ff4a84a6e..54d071596a 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -1354,31 +1354,6 @@ destination starting points.  Perl will move, copy, or zero out C<number>
 instances of the size of the C<type> data structure (using the C<sizeof>
 function).
 
-Here is a handy table of equivalents between ordinary C and Perl's
-memory abstraction layer:
-
-    Instead Of:                 Use:
-
-    t* p = malloc(n)            New(id, p, n, t)
-    t* p = calloc(n, s)         Newz(id, p, n, t)
-    p = realloc(p, n)           Renew(p, n, t)
-    memcpy(dst, src, n)         Copy(src, dst, n, t)
-    memmove(dst, src, n)        Move(src, dst, n, t)
-    free(p)                     Safefree(p)
-    strdup(p)                   savepv(p)
-    strndup(p, n)               savepvn(p, n) (Hey, strndup doesn't exist!)
-    memcpy/*(struct foo *)      StructCopy(src, dst, t)
-
-    t   type
-    p   pointer
-    ck  cookie for the memory region (now unused)
-    n   number of elements
-    src source pointer
-    dst destination pointer
-
-Notice the different order of arguments to C<Copy> and C<Move> than used
-in C<memcpy> and C<memmove>.
-
 =head2 PerlIO
 
 The most recent development releases of Perl has been experimenting with
diff --git a/pod/perltoc.pod b/pod/perltoc.pod
index 316cc936a0..c9a5813203 100644
--- a/pod/perltoc.pod
+++ b/pod/perltoc.pod
@@ -3481,6 +3481,38 @@ C<!!!>, C<!!>, C<!>
 
 =back
 
+=head2 perlclib - Internal replacements for standard C library functions
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Conventions
+
+C<t>, C<p>, C<n>, C<s>
+
+=item File Operations
+
+=item File Input and Output
+
+=item File Positioning
+
+=item Memory Management and String Handling
+
+=item Character Class Tests
+
+=item F<stdlib.h> functions
+
+=item Miscellaneous functions
+
+=back
+
+=item SEE ALSO
+
+=back
+
 =head2 perlguts - Introduction to the Perl API
 
 =over 4
@@ -5487,50 +5519,6 @@ Source, Compiled Module Source, Perl Modules/Scripts
 
 =back
 
-=head2 perldos - Perl under DOS, W31, W95.
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Prerequisites
-
-DJGPP, Pthreads
-
-=item Shortcomings of Perl under DOS
-
-=item Building
-
-=item Testing
-
-=item Installation
-
-=back
-
-=item BUILDING AND INSTALLING MODULES
-
-=over 4
-
-=item Prerequisites
-
-=item Unpacking CPAN Modules
-
-=item Building Non-XS Modules
-
-=item Building XS Modules
-
-=back
-
-=item AUTHOR
-
-=item SEE ALSO
-
-=back
-
 =head2 perlepoc, README.epoc - Perl for EPOC
 
 =over 4
@@ -6180,48 +6168,6 @@ LIST, waitpid PID,FLAGS
 
 =back
 
-=head2 perlwin32 - Perl under Win32
-
-=over 4
-
-=item SYNOPSIS
-
-=item DESCRIPTION
-
-=over 4
-
-=item Setting Up
-
-Make, Command Shell, Borland C++, Microsoft Visual C++, Mingw32 with GCC
-
-=item Building
-
-=item Testing
-
-=item Installation
-
-=item Usage Hints
-
-Environment Variables, File Globbing, Using perl from the command line,
-Building Extensions, Command-line Wildcard Expansion, Win32 Specific
-Extensions, Running Perl Scripts, Miscellaneous Things
-
-=back
-
-=item BUGS AND CAVEATS
-
-=item AUTHORS
-
-Gary Ng E<lt>71564.1743@CompuServe.COME<gt>, Gurusamy Sarathy
-E<lt>gsar@activestate.comE<gt>, Nick Ing-Simmons
-E<lt>nick@ing-simmons.netE<gt>
-
-=item SEE ALSO
-
-=item HISTORY
-
-=back
-
 =head1 PRAGMA DOCUMENTATION
 
 =head2 attrs - set/get attributes of a subroutine (deprecated)
@@ -7803,7 +7749,7 @@ B<name()>, B<value()>, B<domain()>, B<path()>, B<expires()>
 
 Searching for authors, bundles, distribution files and modules, make, test,
 install, clean	modules or distributions, get, readme, look module or
-distribution, Signals
+distribution, ls author, Signals
 
 =item CPAN::Shell
 
@@ -7901,6 +7847,8 @@ http firewall, ftp firewall, One way visibility, SOCKS, IP Masquerade
 
 =item AUTHOR
 
+=item TRANSLATIONS
+
 =item SEE ALSO
 
 =back