perl/5.32.0/perlclib.pod


=encoding euc-jp

=head1 NAME

=begin original

perlclib - Internal replacements for standard C library functions

=end original

perlclib - 標準 C ライブラリ関数の内部的な代用品

=head1 DESCRIPTION

=begin original

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.

=end original

Perl porters が注意するべき事のひとつは、F<perl> は内部で C 標準ライブラリを
あまり使わないようにしていると言うことです; 例えば、F<ctype.h> 関数は
ほとんど使われていないことに気付くでしょう。
これは、どのような操作をしようとしているかを正確に知るために、Perl は
標準ライブラリ関数を再実装したり抽象化したりしようとするからです。

=begin original

This is a reference card for people who are familiar with the C library
and who want to do things the Perl way; to tell them which functions
they ought to use instead of the more normal C functions. 

=end original

これは C ライブラリに慣れていて Perl 方式で何かをしたい人々のための
リファレンスカードです; より普通の C 関数の代わりに使うべき関数を示します。

=head2 Conventions

(規約)

=begin original

In the following tables:

=end original

以下の表で:

=over 3

=item C<t>

=begin original

is a type.

=end original

は型です。

=item C<p>

=begin original

is a pointer.

=end original

はポインタです。

=item C<n>

=begin original

is a number.

=end original

は数値です。

=item C<s>

=begin original

is a string.

=end original

は文字列です。

=back

=begin original

C<sv>, C<av>, C<hv>, etc. represent variables of their respective types.

=end original

C<sv>, C<av>, C<hv> などはそれぞれ対応する型の変数です。

=head2 File Operations

(ファイル操作)

=begin original

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 I/O abstraction 
C<FILE*> types may not even be available. See also the C<perlapio>
documentation for more information about the following functions:

=end original

F<stdio.h> 関数の代わりに、Perl 抽象層を使うべきです。
C<FILE*> 型の代わりに、C<PerlIO*> 型を扱う必要があります。
新しい PerlIO 層の I/O 抽象化では C<FILE*> 型は利用できないかも知れないことを
忘れないでください。
以下の関数に関するさらなる詳細については C<perlapio> 文書を
参照してください:

 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) (Dep-
                               recated)
 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)

=begin original

Note that the PerlIO equivalents of C<fread> and C<fwrite> are slightly
different from their C library counterparts:

=end original

C<fread> と C<fwrite> の PerlIO の代用品は C ライブラリの対応物とは
少し違うことに注意してください:

 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)

=begin original

There is no equivalent to C<fgets>; one should use C<sv_gets> instead:

=end original

C<fgets> の等価物はありません; 代わりに C<sv_gets> を使うべきです:

 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)               Newx(p, n, t)
 t* p = calloc(n, s)            Newxz(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(dst, src, sizeof(t))    StructCopy(src, dst, t)
 memset(dst, 0, n * sizeof(t))  Zero(dst, n, t)
 memzero(dst, 0)                Zero(dst, n, char)
 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)

 memcmp(p1, p2, n)              memNE(p1, p2, n)
 !memcmp(p1, p2, n)             memEQ(p1, p2, n)

=begin original

Notice the different order of arguments to C<Copy> and C<Move> than used
in C<memcpy> and C<memmove>.

=end original

C<Copy> および C<Move> の引数の順番は C<memcpy> および C<memmove> と異なる
ことに注意してください。

=begin original

Most of the time, though, you'll want to be dealing with SVs internally
instead of raw C<char *> strings:

=end original

しかし、大抵の場合、生の C<char *> 文字列ではなく内部的に SV を
扱いたいでしょう:

 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, ...)

=begin original

Note also the existence of C<sv_catpvf> and C<sv_vcatpvfn>, combining
concatenation with formatting.

=end original

連結とフォーマッティングを結合した C<sv_catpvf> および C<sv_vcatpvfn> が
あることにも注意してください。

=begin original

Sometimes instead of zeroing the allocated heap by using Newxz() you
should consider "poisoning" the data.  This means writing a bit
pattern into it that should be illegal as pointers (and floating point
numbers), and also hopefully surprising enough as integers, so that
any code attempting to use the data without forethought will break
sooner rather than later.  Poisoning can be done using the Poison()
macros, which have similar arguments to Zero():

=end original

時々、Newxz() を使って割り当てられたヒープをゼロにする代わりにデータに
「毒入れ」したいかもしれません。
これは、ポインタ(および浮動小数点数)として不正になり、できれば整数としても
十分に驚くべきビットパターンを書き込んで、考えなしにデータを使おうとする
コードが早めに壊れるようにすることです。
毒入れは Zero() と似たような引数を持つ Poison() マクロで行えます:

 PoisonWith(dst, n, t, b)    scribble memory with byte b
 PoisonNew(dst, n, t)        equal to PoisonWith(dst, n, t, 0xAB)
 PoisonFree(dst, n, t)       equal to PoisonWith(dst, n, t, 0xEF)
 Poison(dst, n, t)           equal to PoisonFree(dst, n, t)

=head2 Character Class Tests

(文字クラステスト)

=begin original

There are several types of character class tests that Perl implements.
The only ones described here are those that directly correspond to C
library functions that operate on 8-bit characters, but there are
equivalents that operate on wide characters, and UTF-8 encoded strings.
All are more fully described in L<perlapi/Character classification> and
L<perlapi/Character case changing>.

=end original

Perl が実装しているいくつか種類の文字クラステストがあります。
ここで記述しているのは 8 ビット文字を操作する C ライブライブラリに直接
対応しているもののみですが、ワイド文字、UTF-8 エンコード文字を操作する
等価物もあります。
全ては L<perlapi/Character classification> と
L<perlapi/Character case changing> でより完全に記述されています。

=begin original

The C library routines listed in the table below return values based on
the current locale.  Use the entries in the final column for that
functionality.  The other two columns always assume a POSIX (or C)
locale.  The entries in the ASCII column are only meaningful for ASCII
inputs, returning FALSE for anything else.  Use these only when you
B<know> that is what you want.  The entries in the Latin1 column assume
that the non-ASCII 8-bit characters are as Unicode defines, them, the
same as ISO-8859-1, often called Latin 1.

=end original

後述する表に挙げられている C ライブラリルーチンは現在のロケールを基にした
値を返します。
この機能のためには最後の列のエントリを使ってください。
残りの二つの列は常に POSIX (あるいは C) ロケールを仮定します。
ASCII 列のエントリは ASCII 入力でのみ意味を持ち、それ以外では FALSE を
返します。
これが望んでいるものであると B<分かっている> 場合にのみこれを使ってください。
Latin1 列のエントリは、非 ASCII 8 ビット文字は Unicode が定義しているように、
ISO-8859-1 (しばしば Latin 1 と呼ばれます) であると仮定します。

=begin original

 Instead Of:  Use for ASCII:   Use for Latin1:      Use for locale:

=end original

 元:         ASCII 用:         Latin1 用:           ロケール用:

 isalnum(c)  isALPHANUMERIC(c) isALPHANUMERIC_L1(c) isALPHANUMERIC_LC(c)
 isalpha(c)  isALPHA(c)        isALPHA_L1(c)        isALPHA_LC(u )
 isascii(c)  isASCII(c)                             isASCII_LC(c)
 isblank(c)  isBLANK(c)        isBLANK_L1(c)        isBLANK_LC(c)
 iscntrl(c)  isCNTRL(c)        isCNTRL_L1(c)        isCNTRL_LC(c)
 isdigit(c)  isDIGIT(c)        isDIGIT_L1(c)        isDIGIT_LC(c)
 isgraph(c)  isGRAPH(c)        isGRAPH_L1(c)        isGRAPH_LC(c)
 islower(c)  isLOWER(c)        isLOWER_L1(c)        isLOWER_LC(c)
 isprint(c)  isPRINT(c)        isPRINT_L1(c)        isPRINT_LC(c)
 ispunct(c)  isPUNCT(c)        isPUNCT_L1(c)        isPUNCT_LC(c)
 isspace(c)  isSPACE(c)        isSPACE_L1(c)        isSPACE_LC(c)
 isupper(c)  isUPPER(c)        isUPPER_L1(c)        isUPPER_LC(c)
 isxdigit(c) isXDIGIT(c)       isXDIGIT_L1(c)       isXDIGIT_LC(c)

 tolower(c)  toLOWER(c)        toLOWER_L1(c)        toLOWER_LC(c)
 toupper(c)  toUPPER(c)                             toUPPER_LC(c)

=begin original

To emphasize that you are operating only on ASCII characters, you can
append C<_A> to each of the macros in the ASCII column: C<isALPHA_A>,
C<isDIGIT_A>, and so on.

=end original

念を押しておくと、ASCII 文字のみを操作するなら、ASCII の列のそれぞれの
マクロに C<_A> を追加したものが使えます: C<isALPHA_A>, C<isDIGIT_A> などです。

=begin original

(There is no entry in the Latin1 column for C<isascii> even though there
is an C<isASCII_L1>, which is identical to C<isASCII>;  the
latter name is clearer.  There is no entry in the Latin1 column for
C<toupper> because the result can be non-Latin1.  You have to use
C<toUPPER_uni>, as described in L<perlapi/Character case changing>.)

=end original

(C<isASCII> と等価な C<isASCII_L1> というものはありますが、C<isascii> の
Latin1 の列はありません; 前者の名前の方が明確です。
C<toupper> の Latin1 の列はありません; 結果は非 Latin1 に
なるかもしれないからです。
L<perlapi/Character case changing> に記述されている C<toUPPER_uni> を
使う必要があります。)

=head2 F<stdlib.h> functions

(F<stdlib.h> 関数)

 Instead Of:                 Use:

 atof(s)                     Atof(s)
 atoi(s)                     grok_atoUV(s, &uv, &e)
 atol(s)                     grok_atoUV(s, &uv, &e)
 strtod(s, &p)               Strtod(s, &p)
 strtol(s, &p, n)            Strtol(s, &p, b)
 strtoul(s, &p, n)           Strtoul(s, &p, b)

=begin original

Typical use is to do range checks on C<uv> before casting:

=end original

典型的な使用法は、キャストする前の C<uv> の範囲チェックです:

  int i; UV uv;
  char* end_ptr = input_end;
  if (grok_atoUV(input, &uv, &end_ptr)
      && uv <= INT_MAX)
    i = (int)uv;
    ... /* continue parsing from end_ptr */
  } else {
    ... /* parse error: not a decimal integer in range 0 .. MAX_IV */
  }

=begin original

Notice also the C<grok_bin>, C<grok_hex>, and C<grok_oct> functions in
F<numeric.c> for converting strings representing numbers in the respective
bases into C<NV>s.  Note that grok_atoUV() doesn't handle negative inputs,
or leading whitespace (being purposefully strict).

=end original

それぞれの基数で数値を表現している文字列を C<NV> に変換するための
F<numeric.c> にある C<grok_bin>, C<grok_hex>, C<grok_oct> 関数にも
注目してください。
grok_atoUV() は負の入力や銭湯の空白を扱わないことに注意してください
(意図的に厳密にしています)。

=begin original

Note that strtol() and strtoul() may be disguised as Strtol(), Strtoul(),
Atol(), Atoul().  Avoid those, too.

=end original

strtol() と strtoul() は Strtol(), Strtoul(), Atol(), Atoul() と言う形に
偽装しているかもしれないことに注意してください。
これらも避けてください。

=begin original

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.

=end original

理論的には、perl がビルドされたマシンに実際に strtol や strtoul がない
場合、C<Strtol> と C<Strtoul> は定義されないかもしれません。
しかしこれらの 2 関数は 1989 ANSI C 使用の一部なので、今のところどこでも
これらを見つけられると思われます。

 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_setenv(s, val)

=head2 Miscellaneous functions

(さまざまな関数)

=begin original

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.

=end original

F<setjmp.h> 関数を使おうと B<思う> ことすらするべきではありませんが、もし
そう考えているなら、代わりに F<scope.h> の C<JMPENV> スタックを
使ってください。

=begin original

For C<signal>/C<sigaction>, use C<rsignal(signo, handler)>.

=end original

C<signal>/C<sigaction> については、C<rsignal(signo, handler)> を
使ってください。

=head1 SEE ALSO

L<perlapi>, L<perlapio>, L<perlguts>

=begin meta

Translate: SHIRAKATA Kentaro <argrath@ub32.org>
Status: completed

=end meta
