新井です。

In message "[ruby-dev:19842] Re: [ruby-talk:66990] README.EXT.ja seems to have more info..."
  on 19 Mar 2003 01:48:31 +0900,
  Kazuo Saito <ksaito / uranus.dti.ne.jp> wrote:
> 斉藤です。

> で、まだそのログを掘り返している最中なんですが、このREADME.EXT{,.ja}
> にある説明の範囲では、単純に s/STR2CSTR/StringValuePtr/ としていいもの
> でしょうか。

渡された引数などが STR2CSTR で to_str された後に、暗黙の変換
を行う前のオブジェクトが利用されているとダメですが、

	s = 文字列じゃないオブジェクト;
	ptr = STR2CSTR(s);
	rb_p(s);	/* <- StringValuePtr に置き換えると結果が変わる */

おそらく STR2CSTR() を使う段階で、そのオブジェクトが文字列で
あることを期待していると思います。

なので、README.EXT.ja では、単純に置き換えで良いのではないで
しょうか?

(doc/NEWS あたりに説明を添えてってのがより良いかとは思います)

> なにせ事情をよく知らないうえ、頼りは blade の namazu だけなもので、
> 素人が勢いで書くのもまずいと思ってます。一応経緯を追ってみますけど、
> どなたかご存知の方は直接追記/書き換えしてくださるか、簡単なサマリでも
> いただけると嬉しいんですが、うーん。

一応、簡単なサマリというか説明はここに書きましたが、これでわかります?
# 説明不足は十分承知してますが

<http://www.ruby-lang.org/ja/man-1.6/?cmd=view;name=ruby+1.7+feature>

: 拡張ライブラリAPI(STR2CSTR())

    ((-あらい 2002-09-08: 重要な変更だと思うので書くことにしました-))

    拡張ライブラリの API である STR2CSTR() は、与えられたオブジェクト
    が文字列でなくかつ to_str メソッドを持つ場合、内部で to_str を呼び
    出して暗黙の型変換を行います。この場合、変換結果が保持する文字列ポ
    インタを返しますが、このAPIでは暗黙の型変換結果のオブジェクトがど
    こからも参照されないため、型変換結果が GC される可能性があります。
    ((<ruby-dev:12731>))

    version 1.7 以降では代わりに StringValuePtr() を使用します。こちら
    は、引数の参照先が暗黙の型変換の結果に置き換わるため変換結果が GC 
    されません。(version 1.7 では、STR2CSTR() は、obsolete です)

    もう一つ新しく StringValue() という API が用意されています。こちら
    は、引数が to_str による暗黙の型変換を期待する場合に使用します。
    引数が文字列なら何もしません。
    文字列を受け取るメソッドの最初の方で読んでおくと便利です。

    なお、今のところ str2cstr() (Cポインタと文字列長を返す)の代わりに
    なる安全な API は用意されていません。(((<ruby-dev:15644>))で提案は
    ありました)

--
新井康司 (Koji Arai)