1N/Aperlclib - Internal replacements for standard C library functions
1N/AOne thing Perl porters should note is that F<perl> doesn't tend to use that
1N/Amuch of the C standard library internally; you'll see very little use of,
1N/Afor example, the F<
ctype.h> functions in there. This is because Perl
1N/Atends to reimplement or abstract standard library functions, so that we
1N/Aknow exactly how they're going to operate.
1N/AThis is a reference card for people who are familiar with the C library
1N/Aand who want to do things the Perl way; to tell them which functions
1N/Athey ought to use instead of the more normal C functions.
1N/AIn the following tables:
1N/AC<sv>, C<av>, C<hv>, etc. represent variables of their respective types.
1N/A=head2 File Operations
1N/AInstead of the F<
stdio.h> functions, you should use the Perl abstraction
1N/Alayer. Instead of C<FILE*> types, you need to be handling C<PerlIO*>
1N/Atypes. Don't forget that with the new PerlIO layered I/O abstraction
1N/AC<FILE*> types may not even be available. See also the C<perlapio>
1N/Adocumentation for more information about the following functions:
1N/A stdin PerlIO_stdin()
1N/A stdout PerlIO_stdout()
1N/A stderr PerlIO_stderr()
1N/A fopen(fn, mode) PerlIO_open(fn, mode)
1N/A freopen(fn, mode, stream) PerlIO_reopen(fn, mode, perlio) (Deprecated)
1N/A fflush(stream) PerlIO_flush(perlio)
1N/A fclose(stream) PerlIO_close(perlio)
1N/A=head2 File Input and Output
1N/A fprintf(stream, fmt, ...) PerlIO_printf(perlio, fmt, ...)
1N/A [f]getc(stream) PerlIO_getc(perlio)
1N/A [f]putc(stream, n) PerlIO_putc(perlio, n)
1N/A ungetc(n, stream) PerlIO_ungetc(perlio, n)
1N/ANote that the PerlIO equivalents of C<fread> and C<fwrite> are slightly
1N/Adifferent from their C library counterparts:
1N/A fread(p, size, n, stream) PerlIO_read(perlio, buf, numbytes)
1N/A fwrite(p, size, n, stream) PerlIO_write(perlio, buf, numbytes)
1N/A fputs(s, stream) PerlIO_puts(perlio, s)
1N/AThere is no equivalent to C<fgets>; one should use C<sv_gets> instead:
1N/A fgets(s, n, stream) sv_gets(sv, perlio, append)
1N/A=head2 File Positioning
1N/A feof(stream) PerlIO_eof(perlio)
1N/A fseek(stream, n, whence) PerlIO_seek(perlio, n, whence)
1N/A rewind(stream) PerlIO_rewind(perlio)
1N/A fgetpos(stream, p) PerlIO_getpos(perlio, sv)
1N/A fsetpos(stream, p) PerlIO_setpos(perlio, sv)
1N/A ferror(stream) PerlIO_error(perlio)
1N/A clearerr(stream) PerlIO_clearerr(perlio)
1N/A=head2 Memory Management and String Handling
1N/A t* p = malloc(n) New(id, p, n, t)
1N/A t* p = calloc(n, s) Newz(id, p, n, t)
1N/A p = realloc(p, n) Renew(p, n, t)
1N/A memcpy(dst, src, n) Copy(src, dst, n, t)
1N/A memmove(dst, src, n) Move(src, dst, n, t)
1N/A memcpy/*(struct foo *) StructCopy(src, dst, t)
1N/A memset(dst, 0, n * sizeof(t)) Zero(dst, n, t)
1N/A memzero(dst, 0) Zero(dst, n, char)
1N/A strndup(p, n) savepvn(p, n) (Hey, strndup doesn't exist!)
1N/A strstr(big, little) instr(big, little)
1N/A strcmp(s1, s2) strLE(s1, s2) / strEQ(s1, s2) / strGT(s1,s2)
1N/A strncmp(s1, s2, n) strnNE(s1, s2, n) / strnEQ(s1, s2, n)
1N/ANotice the different order of arguments to C<Copy> and C<Move> than used
1N/Ain C<memcpy> and C<memmove>.
1N/AMost of the time, though, you'll want to be dealing with SVs internally
1N/Ainstead of raw C<char *> strings:
1N/A strlen(s) sv_len(sv)
1N/A strcpy(dt, src) sv_setpv(sv, s)
1N/A strncpy(dt, src, n) sv_setpvn(sv, s, n)
1N/A strcat(dt, src) sv_catpv(sv, s)
1N/A strncat(dt, src) sv_catpvn(sv, s)
1N/A sprintf(s, fmt, ...) sv_setpvf(sv, fmt, ...)
1N/ANote also the existence of C<sv_catpvf> and C<sv_vcatpvfn>, combining
1N/Aconcatenation with formatting.
1N/ASometimes instead of zeroing the allocated heap by using Newz() you
1N/Ashould consider "poisoning" the data. This means writing a bit
1N/Apattern into it that should be illegal as pointers (and floating point
1N/Anumbers), and also hopefully surprising enough as integers, so that
1N/Aany code attempting to use the data without forethought will break
1N/Asooner rather than later. Poisoning can be done using the Poison()
1N/Amacro, which has similar arguments as Zero():
1N/A=head2 Character Class Tests
1N/AThere are two types of character class tests that Perl implements: one
1N/Atype deals in C<char>s and are thus B<not> Unicode aware (and hence
1N/Adeprecated unless you B<know> you should use them) and the other type
1N/Adeal in C<UV>s and know about Unicode properties. In the following
1N/Atable, C<c> is a C<char>, and C<u> is a Unicode codepoint.
1N/A Instead Of: Use: But better use:
1N/A isalnum(c) isALNUM(c) isALNUM_uni(u)
1N/A isalpha(c) isALPHA(c) isALPHA_uni(u)
1N/A iscntrl(c) isCNTRL(c) isCNTRL_uni(u)
1N/A isdigit(c) isDIGIT(c) isDIGIT_uni(u)
1N/A isgraph(c) isGRAPH(c) isGRAPH_uni(u)
1N/A islower(c) isLOWER(c) isLOWER_uni(u)
1N/A isprint(c) isPRINT(c) isPRINT_uni(u)
1N/A ispunct(c) isPUNCT(c) isPUNCT_uni(u)
1N/A isspace(c) isSPACE(c) isSPACE_uni(u)
1N/A isupper(c) isUPPER(c) isUPPER_uni(u)
1N/A isxdigit(c) isXDIGIT(c) isXDIGIT_uni(u)
1N/A tolower(c) toLOWER(c) toLOWER_uni(u)
1N/A toupper(c) toUPPER(c) toUPPER_uni(u)
1N/A strtod(s, *p) Nothing. Just don't use it.
1N/A strtol(s, *p, n) Strtol(s, *p, n)
1N/A strtoul(s, *p, n) Strtoul(s, *p, n)
1N/ANotice also the C<grok_bin>, C<grok_hex>, and C<grok_oct> functions in
1N/AF<
numeric.c> for converting strings representing numbers in the respective
1N/AIn theory C<Strtol> and C<Strtoul> may not be defined if the machine perl is
1N/Abuilt on doesn't actually have strtol and strtoul. But as those 2
1N/Afunctions are part of the 1989 ANSI C spec we suspect you'll find them
1N/A int rand() double Drand01()
1N/A srand(n) { seedDrand01((Rand_seed_t)n);
1N/A PL_srand_called = TRUE; }
1N/A system(s) Don't. Look at pp_system or use my_popen
1N/A getenv(s) PerlEnv_getenv(s)
1N/A setenv(s, val) my_putenv(s, val)
1N/A=head2 Miscellaneous functions
1N/AYou should not even B<want> to use F<
setjmp.h> functions, but if you
1N/Athink you do, use the C<JMPENV> stack in F<
scope.h> instead.
1N/AFor C<signal>/C<sigaction>, use C<rsignal(signo, handler)>.
1N/AC<perlapi>, C<perlapio>, C<perlguts>