From: Simon Cozens Date: Wed, 31 Jan 2001 16:31:43 +0000 (+0000) Subject: Re: [PATCH] pod/perlclib.pod - Replacements for C library functions X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=f40a6c711beb7bdc0833c20793b9fa5333077213;p=p5sagit%2Fp5-mst-13.2.git Re: [PATCH] pod/perlclib.pod - Replacements for C library functions Message-ID: <20010131163143.A1427@pembro26.pmb.ox.ac.uk> p4raw-id: //depot/perl@8772 --- diff --git a/MANIFEST b/MANIFEST index 5c555f0..61af6b5 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 1e55649..140341b 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 1621b2f..fd55b8d 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 0000000..e2ae529 --- /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 doesn't tend to use that +much of the C standard library internally; you'll see very little use of, +for example, the F 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 + +is a type. + +=item C

+ +is a pointer. + +=item C + +is a number. + +=item C + +is a string. + +=back + +C, C, C, etc. represent variables of their respective types. + +=head2 File Operations + +Instead of the F functions, you should use the Perl abstraction +layer. Instead of C types, you need to be handling C +types; don't forget that with the new PerlIO layered IO abstraction, +C types may not even be available. See also the C +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 and C 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; one should use C 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 and C than used +in C and C. + +Most of the time, though, you'll want to be dealing with SVs internally +instead of raw C 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 and C, combining +concatenation with formatting. + +=head2 Character Class Tests + +There are two types of character class tests that Perl implements: one +type deals in Cs and are thus B Unicode aware (and hence +deprecated unless you B you should use them) and the other type +deal in Cs and know about Unicode properties. In the following +table, C is a C, and C 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 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, C, and C functions in +F for converting strings representing numbers in the respective +bases into Cs. + +In theory C and C 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 to use F functions, but if you +think you do, use the C stack in F instead. + +For C/C, use C. + +=head1 SEE ALSO + +C, C, C + diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 8ff4a84..54d0715 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -1354,31 +1354,6 @@ destination starting points. Perl will move, copy, or zero out C instances of the size of the C data structure (using the C 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 and C than used -in C and C. - =head2 PerlIO The most recent development releases of Perl has been experimenting with diff --git a/pod/perltoc.pod b/pod/perltoc.pod index 316cc93..c9a5813 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, C

, C, C + +=item File Operations + +=item File Input and Output + +=item File Positioning + +=item Memory Management and String Handling + +=item Character Class Tests + +=item F 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 E71564.1743@CompuServe.COME, Gurusamy Sarathy -Egsar@activestate.comE, Nick Ing-Simmons -Enick@ing-simmons.netE - -=item SEE ALSO - -=item HISTORY - -=back - =head1 PRAGMA DOCUMENTATION =head2 attrs - set/get attributes of a subroutine (deprecated) @@ -7803,7 +7749,7 @@ B, B, B, B, B 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