--- /dev/null
+=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>
+
=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
=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
=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)
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
=item AUTHOR
+=item TRANSLATIONS
+
=item SEE ALSO
=back
projects / p5sagit/p5-mst-13.2.git / commitdiff