.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /usr/local/cvsroot/pgsql/src/man/libpq.3,v 1.15 1998/04/07 18:12:56 momjian Exp $
.\" Translated by Mitsuhiro Maeda (mitsu@cni.co.jp)
.TH LIBPQ INTRO 03/12/94 日本語PostgreSQL 日本語PostgreSQL
.SH 説明
.\" Libpq is the programmer's interface to Postgres.
Libpq は Postgres へのプログラマインタフェイスです。
.\"   Libpq is a set of
.\" library routines that allows queries to pass to the Postgres backend and
.\" instances to return through an IPC channel.
Libpq はライブラリルーチンの集合で、
Postgres のバックエンドに問い合わせを渡し、
IPC チャネルからインスタンスを戻すことが可能です。
.PP
.\" This version of the documentation describes the C interface library.
この文書のバージョンでは Cインタフェイスライブラリを説明します。
.\" Three short programs are included at the end of this section to show how
.\" to write programs that use Libpq.
この節の最後に Libpq を使ってどのようにプログラムを書くのかを示す
3つの短いプログラムが含まれています。
.PP
.\" There are several examples of Libpq applications in the following
.\" directories:
Libpq アプリケーションのいくつかの例が次のディレクトリにあります。
.nf
\&../src/test/regress
\&../src/test/examples
\&../src/bin/psql
.fi
.PP
.\" Frontend programs which use Libpq must include the header file
.\" .B "libpq-fe.h"
.\" and must link with the
.\" .B libpq 
.\" library.
libpq を使うフロントエンドプログラムはヘッダファイル
.B "libpq-fe.h"
をインクルードして、
.B libpq
ライブラリをリンクしなくてはなりません。
.\" .SH "Control and Initialization"
.SH "制御と初期化"
.\" .PP
.\" The following environment variables can be used to set up default
.\" environment values to avoid hard-coding database names into
.\" an application program:
データベースの名前をアプリケーションプログラムに
ハードコーディングしなくてもよいように、
次の環境変数でデフォルト値をセットアップできます:
.sp
\(bu
.B PGHOST
.\" sets the default server name.
デフォルトのサーバ名をセットします。
.\" If it is set to a non-zero-length string, it causes TCP/IP
.\" communication to be used, rather than the default local Unix domain sockets.
もし 0でない長さの文字列をセットしたら、
デフォルトの Unix ドメインソケットではなく TCP/IP での通信が使われます。
.sp
\(bu
.B PGOPTIONS
.\" sets additional runtime options for the Postgres backend.
Postgres のバックエンドにの実行時オプションを追加します。
.sp
\(bu
.B PGPORT
.\" sets the default port or local Unix domain socket file extension
.\" for communicating with the Postgres backend.
Postgres のバックエンドと通信するデフォルトのポート番号または
ローカル Unix ドメインソケットファイルの拡張子をセットします。
.sp
\(bu
.B PGTTY
.\" sets the file or tty on which debugging messages from the backend server
.\" are displayed.
バックエンドサーバからのデバッグメッセージを表示する
ファイルあるいは tty をセットします。
.sp
\(bu
.B PGDATABASE
.\" sets the default Postgres database name.
デフォルトの Postgres データベース名をセットします。
.sp
\(bu
.B PGREALM
.\" sets the
.\" .I Kerberos
.\" realm to use with Postgres, if it is different from the local realm.
もしローカルな realm と違うなら、
Postgres と使う
.IR Kerberos
の realm をセットします。
.\"   If 
.\" .B PGREALM
.\" is set, Postgres applications will attempt authentication with servers
.\" for this realm and use separate ticket files to avoid conflicts with
.\" local ticket files.
もし
.B PGREALM
がセットされると、
Postgres アプリケーションはこの realm を使ってサーバとの認証を試して、
ローカルチケットファイルとの衝突を避けるために別のチケットファイルを使います。
.\"   This environment variable is only used if 
.\" .I Kerberos
.\" authentication is enabled.
この環境変数は
.I Kerberos
認証が可能になっているときにのみ使われます。

.PP
.\" The following environment variables can be used to specify user-level default behavior
.\" for every Postgres session:
次の環境変数は Postgres のセッションでの
ユーザレベルでのデフォルトの振舞いを指定するのに使うことができます:

.sp
\(bu
.B PGDATESTYLE
.\" sets the default style of date/time representation.
デフォルトの日付/時間の表示スタイルをセットします。

.sp
\(bu
.B PGTZ
.\" sets the default time zone.
デフォルトのタイムゾーンをセットします。

.PP
.\" The following environment variables can be used to specify default internal
.\" behavior for every Postgres session:
次の環境変数は
Postgres のセッションでの
内部的なデフォルトの振舞いを指定するのに使うことができます:
.sp
\(bu
.B PGGEQO
.\" sets the default mode for the genetic optimizer.
遺伝最適化機構 (genetic optimizer) のデフォルトモードをセットします。
.sp
\(bu
.B PGRPLANS
.\" sets the default mode to allow or disable right-sided plans in the optimizer.
最適化機構の right-sided プランを許可/却下のデフォルトモードをセットします。
.sp
\(bu
.B PGCOSTHEAP
.\" sets the default cost for heap searches for the optimizer.
最適化機構のヒープ検索のデフォルトコストをセットします。
.sp
\(bu
.B PGCOSTINDEX
.\" sets the default cost for indexed searches for the optimizer.
最適化機構のインデックス検索のデフォルトコストをセットします。

.PP
.\" See the
.\" set(l)
.\" man page for information on the arguments for these environment variables.
これらの環境変数についての情報は
set(l) マニュアルページを参照してください。

.\" .SH "Database Connection Functions"
.SH "データベース接続関数"
.PP
.\" The following routines deal with making a connection to a backend
.\" from a C program.
次のルーチンは Cプログラムからバックエンドへの接続を確立することを扱うものです。
.PP
.B PQsetdb
.IP
.\" Makes a new connection to a backend.
バックエンドへの新らしい接続を確立します。
.nf
PGconn *PQsetdb(char *pghost,
                char *pgport,
                char *pgoptions,
                char *pgtty,
                char *dbName); 
.fi
.\" If any argument is NULL, then the corresponding environment variable
.\" is checked.
もし引数が NULL なら、関連する環境変数がチェックされます。
.\"   If the environment variable is also not set, then hardwired
.\" defaults are used. 
もし環境変数もセットされていなければ、
ハード的に実装されているデフォルトが使われます。
.IP
.\" .I PQsetdb
.\" always returns a valid PGconn pointer.
.I PQsetdb
は常に有効な PGconn ポインタを返します。
.\"   The 
.\" .I PQstatus
.\" (see below) command should be called to ensure that a connection was
.\" properly made before queries are sent via the connection.
その接続で問い合わせが送られる前に、
.I PQstatus
(下記を参照してください)コマンドで接続が適切に行われたかどうかを確認してください。
.\"   Libpq
.\" programmers should be careful to maintain the PGconn abstraction.
Libpq プログラマは PGconn の取り扱いには注意するべきです。
.\"   Use
.\" the accessor functions below to get at the contents of PGconn.
PGconn の内容を取り出すには下のアクセサリ関数を使ってください。
.\"   Avoid
.\" directly referencing the fields of the PGconn structure as they are
.\" subject to change in the future.
直接 PGconn 構造体のフィールドを参照することはさけましょう。
それらは将来的に変更されることを仮定しています。
.IP
.B PQdb
.\" returns the database name of the connection.
接続のデータベース名を返します。
.nf
char *PQdb(PGconn *conn)
.fi
.B PQhost
.\" returns the host name of the connection.
接続のホスト名を返します。
.nf
char *PQhost(PGconn *conn)
.fi
.B PQoptions
.\" returns the pgoptions used in the connection.
接続に使われている実行時オプションを返します。
.nf
char *PQoptions(PGconn *conn)
.fi
.B PQport
.\" returns the pgport of the connection.
接続のポートを返します。
.nf
char *PQport(PGconn *conn)
.fi
.B PQtty
.\" returns the pgtty of the connection.
接続のデバッグ出力先を返します。
.nf
char *PQtty(PGconn *conn)
.fi
.B PQstatus
.\" Returns the status of the connection. The status can be CONNECTION_OK or
.\" CONNECTION_BAD.  
接続ステータスを返します。
ステータスは CONNECTION_OK もしくは CONNECTION_BAD になります。
.nf
ConnStatusType *PQstatus(PGconn *conn)
.fi
.B PQerrorMessage
.\" returns the error message associated with the connection
接続に関連するエラーメッセージを返します。
.nf
char *PQerrorMessage(PGconn* conn);
.fi
.PP
.B PQfinish
.IP
.\" Close the connection to the backend.  Also frees memory used by the
.\" PGconn structure.
バックエンドへの接続を閉じます。
また、PGconn 構造体に使われていたメモリを解放します。
.\"   The PGconn pointer should not be used after PQfinish
.\" has been called. 
PQfinish が呼ばれた後に PGconn ポインタは使わないでください。
.nf
void PQfinish(PGconn *conn)
.fi
.PP
.B PQreset
.IP
.\" Reset the communication port with the backend.
バックエンドとの通信ポートをリセットします。
.\"  This function will close
.\" the IPC socket connection to the backend and attempt to reestablish a
.\" new connection to the same backend.
この関数はバックエンドへの IPC ソケット接続を閉じて、
同じバックエンドへの新しい接続を再度確立しようとします。
.nf
void PQreset(PGconn *conn)
.fi
.PP
.\" .SH "Query Execution Functions"
.SH "問い合わせ実行関数"
.PP
.B PQexec
.IP
.\" Submit a query to Postgres.
問い合わせを Postgres に提出します。
.\"  Returns a PGresult pointer if the query was
.\" successful or a NULL otherwise.
問い合わせが成功すると PGresult へのポインタを、
そうでなければ NULL を返します。
.\"   If a NULL is returned, 
.\" .I PQerrorMessage
.\" can be used to get more information about the error.
もし NULL が戻れば、
.I PQerrorMessage
でエラーの情報を得ることができます。
.nf
PGresult *PQexec(PGconn *conn,
                 char *query);
.fi
.\" The PGresult structure encapsulates the query result returned by the
.\" backend.
バックエンドからの問い合わせ結果を PGresult 構造体にカプセル化します。
.\"   Libpq programmers should be careful to maintain the PGresult
.\" abstraction.
Libpq プログラマは PGresult の取り扱いには注意するべきです。
.\"  Use the accessor functions described below to retrieve the
.\" results of the query.
問い合わせの結果を得るには、下記のアクセサリ関数を使ってください。
.\"   Avoid directly referencing the fields of the PGresult
.\" structure as they are subject to change in the future. 
PGresult 構造体のフィールドを直接参照することは避けましょう。
それらは将来的に変更されることを仮定しています。
.PP
.B PQresultStatus
.IP
.\" Returns the result status of the query.
問い合わせの結果ステータスを返します。
.\" .I PQresultStatus
.\" can return one of the following values:
.I PQresultStatus
は次の値のどれかを返します:
.nf
PGRES_EMPTY_QUERY,
.\" PGRES_COMMAND_OK,  /* the query was a command */
PGRES_COMMAND_OK,  /* 問い合わせはコマンドでした */
.\" PGRES_TUPLES_OK,  /* the query successfully returned tuples */
PGRES_TUPLES_OK,  /* 問い合わせは成功してタプルが返されました */
PGRES_COPY_OUT, 
PGRES_COPY_IN,
.\" PGRES_BAD_RESPONSE, /* an unexpected response was received */
PGRES_BAD_RESPONSE, /* 予期せぬ応答を受け取りました */
PGRES_NONFATAL_ERROR,
PGRES_FATAL_ERROR
.fi
.IP
.\" If the result status is PGRES_TUPLES_OK, then the following routines can
.\" be used to retrieve the tuples returned by the query.
もし結果のステータスが PGRES_TUPLES_OK なら、
問い合わせから戻ったタプルを次のルーチンで取り出すことができます。
.IP

.B PQntuples
.\" returns the number of tuples (instances) in the query result.
問い合わせ結果のタプル(インスタンス)数を返します。

.nf
int PQntuples(PGresult *res);
.fi

.B PQcmdTuples
.\" returns the number of tuples (instances) affected by INSERT, UPDATE, and
.\" DELETE queries.
INSERT、UPDATE、DELETE の問い合わせで影響されたタプル(インスタンス)の数を返します。

.nf
char *PQcmdTuples(PGresult *res);
.fi

.B PQnfields
.\" returns the number of fields (attributes) in the query result.
問い合わせ結果のフィールド(属性)数を返します。
.nf
int PQnfields(PGresult *res);
.fi

.B PQfname
.\" returns the field (attribute) name associated with the given field index.
与えられたフィールド番号に関連するフィールド(属性)名を返します。
.\" Field indices start at 0.
フィールド番号は 0から始まります。
.nf
char *PQfname(PGresult *res,
             int field_index);
.fi

.B PQfnumber
.\" returns the field (attribute) index associated with the given field name.
与えられたフィールド名に関連するフィールド(属性)番号を返します。
.nf
int PQfnumber(PGresult *res,
             char* field_name);
.fi

.B PQftype
.\" returns the field type associated with the given field index.
与えられたフィールド番号に関連したフィールドの型を返します。
.\" The
.\" integer returned is an internal coding of the type.
戻り値の整数はその型の内部コーディングになります。
.\"   Field indices start
.\" at 0.
フィールド番号は 0から始まります。
.nf
Oid PQftype(PGresult *res,
            int field_num);
.fi

.B PQfsize
.\" returns the size in bytes of the field associated with the given field
.\" index.
与えられたフィールド番号に関連するフィールドのサイズをバイト単位で返します。
.\" If the size returned is -1, the field is a variable length field.
もし返ったサイズが -1 なら、そのフィールドは可変長フィールドです。
.\" Field indices start at 0. 
フィールド番号は 0から始まります。
.nf
int2 PQfsize(PGresult *res,
             int field_index);
.fi

.B PQgetvalue
.\" returns the field (attribute) value.
フィールド(属性)の値を返します。
.\"  For most queries, the value
.\" returned by 
.\" .I PQgetvalue
.\" is a null-terminated ASCII string representation
.\" of the attribute value.
ほとんどの問い合わせで
.I PQgetvalue
から戻る値は、その属性値のヌル終端の ASCII 文字列表現です。
.\"  If the query was a result of a 
.\" .B BINARY
.\" cursor, then the value returned by
.\" .I PQgetvalue
.\" is the binary representation of the type in the internal format of the
.\" backend server.
もし問い合わせが
.B バイナリ
カーソルの結果なら、
.I PQgetvalue
から戻る値は、
バックエンドサーバの内部フォーマットの型のバイナリ表現となります。
.\"  It is the programmer's responsibility to cast and
.\" convert the data to the correct C type.
そのデータを正しい C の型にキャストや変換をするのはプログラマの責任となります。
.\"   The value returned by 
.\" .I PQgetvalue
.\" points to storage that is part of the PGresult structure.
.I PQgetvalue
の返す値は
PGresult 構造体の一部の記憶領域を指すポインタです。
.\"   One must
.\" explicitly copy the value into other storage if it is to be used past
.\" the lifetime of the PGresult structure itself.
PGresult 構造体の寿命よりも長く値を使おうとするなら、
その値を明示的に他の記憶領域にコピーしてください。
.nf
char* PQgetvalue(PGresult *res,
                 int tup_num,
                 int field_num);
.fi

.B PQgetlength
.\" returns the length of a field (attribute) in bytes.
フィールド(属性)の長さをバイト単位で返します。
.\"   If the field
.\" is a
.\" .I "struct varlena" ,
.\" the length returned here does 
.\" .B not
.\" include the size field of the varlena, i.e., it is 4 bytes less.
もしフィールドが
.I "struct varlena"
なら、ここで戻る長さは
varlena のサイズフィールドは含まれて
.B いません。
つまり、4バイト足りません。
.nf
int PQgetlength(PGresult *res,
                int tup_num,
                int field_num);
.fi

.B PQgetisnull
.\" returns the NULL status of a field.
フィールドの NULL ステータスを返します。
.nf
int PQgetisnull(PGresult *res,
                int tup_num,
                int field_num);
.fi

.PP
.B PQcmdStatus
.IP 
.\" Returns the command status associated with the last query command.
最後の問い合わせコマンドに関連するコマンドステータスを返します。
.nf
char *PQcmdStatus(PGresult *res);
.fi
.PP
.B PQoidStatus
.IP
.\" Returns a string with the object id of the tuple inserted if the last
.\" query is an INSERT command.  Otherwise, returns an empty string.
もし最後の問い合わせが INSERT コマンドなら、
挿入されたタプルのオブジェクトID の文字列が返ります。
.nf
char* PQoidStatus(PGresult *res);
.fi
.PP
.B PQprint
.IP
.\" + Prints out all the tuples in an intelligent manner. The
.\" .B psql
.\" + program uses this function for its output.
+ インテリジェントな方法ですべてのタプルを表示します。
.B psql
プログラムがこの関数を出力に使っています。
.nf
void PQprint(
      FILE* fout,      /* output stream */
      PGresult* res,   /* query results */
      PQprintOpt *ps   /* option structure */
        );

.fi
.\" .I PQprintOpt
.\" is a typedef'ed structure as defined below.
.I PQprintOpt
は下に定義される typedef された構造体です。
.(C
typedef struct _PQprintOpt {
    bool header;           /* print table headings and row count */
    bool align;            /* fill align the fields */
    bool standard;         /* old brain dead format (needs align) */
    bool html3;            /* output html3+ tables */
    bool expanded;         /* expand tables */
    bool pager;            /* use pager if needed */
    char *fieldSep;        /* field separator */
    char *caption;         /* html table caption (or NULL) */
    char **fieldName;      /* null terminated array of field names (or NULL) */
} PQprintOpt;
.fi
.LP
.B PQclear
.IP
.\" Frees the storage associated with the PGresult.
PGresult に関連した記憶領域を解放します。
.\"   Every query result
.\" should be properly freed when it is no longer used.
問い合わせの結果は使わなくなった時に適切に解放されるべきです。
.\"   Failure to do this
.\" will result in memory leaks in the frontend application.
これを行わないと、フロントエンドアプリケーションでメモリリークを起こすことがあります。
.\"   The PQresult*
.\" passed in should be a value which is returned from PQexec().
渡される PQresult* は PQexec() から返った値にしてください。
.\"   Calling
.\" PQclear() on an uninitialized PQresult pointer will very likely result
.\" in a core dump. 
PQresult ポインタに対して PQclear() を呼ぶと、
簡単にコアダンプしてしまいます。
.nf
void PQclear(PQresult *res);
.fi
.PP
.SH "Fast Path"
.PP
.\" Postgres provides a 
.\" .B "fast path"
.\" interface to send function calls to the backend.
Postgres はバックエンドへの関数の呼び出しに
.B "fast path"
インタフェイスを提供します。
.\"   This is a trapdoor
.\" into system internals and can be a potential security hole.
これはシステム内部への蓋で、
潜在的なセキュリティホールとなり得ます。
.\"   Most users
.\" will not need this feature. 
通常ユーザはこの特色は使わない方がよいでしょう。
.nf
PGresult* PQfn(PGconn* conn,
	       int fnid, 
	       int *result_buf, 
	       int *result_len,
	       int result_is_int,
	       PQArgBlock *args, 
	       int nargs);
.fi
.PP
.\" The
.\" .I fnid
.\" argument is the object identifier of the function to be executed.
.I fnid
引数は、実行される関数のオブジェクトID です。
.\" .I result_buf
.\" is the buffer in which to load the return value.
.I result_buf
は戻り値を格納するバッファです。
.\"  The caller must have
.\" allocated sufficient space to store the return value.  
この関数を呼び出す人は、
戻り値を格納する充分な空間をアロケートしておかなくてはなりません。
.\" The result length will be returned in the storage pointed to by 
.\" .I result_len.
戻り値の長さが
.I result_len
に示される領域に戻ります。
.\" If the result is to be an integer value, than 
.\" .I result_is_int
.\" should be set to 1; otherwise it should be set to 0.
もし戻り値が整数なら、
.I result_is_int
を 1に、そうでないなら、 0にセットしてください。
.\" .I args
.\" and 
.\" .I nargs
.\" specify the arguments to the function.
.I args
と
.I nargs
で関数への引数を指定します。
.nf
typedef struct {
    int len;
    int isint;
    union {
        int *ptr;	
	int integer;
    } u;
} PQArgBlock;
.fi
.PP
.\" .I PQfn
.\" always returns a valid PGresult*.
.I PQfn
は常に有効な PGresult* を返します。
.\"  The resultStatus should be checked
.\" before the result is used.
その結果を使う前に resultStatus をチェックしてください。
.\"   The caller is responsible for freeing the
.\" PGresult with 
.\" .I PQclear
.\" when it is not longer needed.
必要がなくなった時に、PGresult を
.I PQclear
で解放するのは呼び出した人の責任です。
.PP
.\" .SH "Asynchronous Notification"
.SH "非同期通知"
.PP
.\" Postgres supports asynchronous notification via the 
.\" .I LISTEN
.\" and
.\" .I NOTIFY
.\" commands.
Postgres は
.I LISTEN
と
.I NOTIFY
コマンドで非同期通知をサポートします。
.\"   A backend registers its interest in a particular relation
.\" with the LISTEN command.
LISTEN コマンドでバックエンドは特定のリレーションへの興味を登録します。
.\"   All backends listening on a particular
.\" relation will be notified asynchronously when a NOTIFY of that relation
.\" name is executed by another backend.
別のバックエンドでそのリレーション名で NOTIFY が実行されると、
特定のリレーションにLISTENしているすべてのバックエンドは非同期に通知されます。
.\"   No additional information is
.\" passed from the notifier to the listener.
他に通知者からリスナーへ送られる付加的な情報はありません。
.\"   Thus, typically, any actual
.\" data that needs to be communicated is transferred through the relation.
ですから、典型的には通信する必要のある実際のデータは
リレーションを通して送られることになります。
.PP
.\" Libpq applications are notified whenever a connected backend has
.\" received an asynchronous notification.
Libpq アプリケーションは接続しているバックエンドが非同期通知を受け取ると、
通知されます。
.\"   However, the communication from
.\" the backend to the frontend is not asynchronous.
しかし、バックエンドからフロントエンドへの通信は非同期ではありません。
.\"   Notification comes
.\" piggy-backed on other query results.
通知は他の問い合わせ結果の上に乗って来るのです。
.\"   Thus, an application must submit
.\" queries, even empty ones, in order to receive notice of backend
.\" notification.
ですから、バックエンドの通知を受け取るためには
アプリケーションは空でもいいですから何か問い合わせを送らなくてはなりません。
.\"   In effect, the Libpq application must poll the backend to
.\" see if there is any pending notification information.
つまり、Libpq アプリケーションはバックエンドをポーリングして
残っている通知情報がないかどうかを見なくてはなりません。
.\"   After the
.\" execution of a query, a frontend may call 
.\" .I PQNotifies
.\" to see if any notification data is available from the backend. 
問い合わせの後に、
フロントエンドは
.I PQNotifies
を呼び出してバックエンドから通知データが来たかどうかを見ることができます。
.PP
.B PQNotifies
.IP
.\" returns the notification from a list of unhandled notifications from the
.\" backend.
バックエンドからのまだ処理していない通知のリストを返します。
.\"  Returns NULL if there are no pending notifications from the
.\" backend.   
もしバックエンドからの通知がなければ、
NULL を返します。
.\" .I PQNotifies
.\" behaves like the popping of a stack.
.I PQNotifies
の動作はスタックのポップのようになります。
.\"   Once a notification is returned
.\" from
.\" .I PQnotifies,
.\" it is considered handled and will be removed from the list of
.\" notifications.
.I PQNotifies
から通知が戻ると、
その通知は処理されたと考えられて、通知リストから除かれます。
.nf
PGnotify* PQNotifies(PGconn *conn);
.fi
.PP
.\" The second sample program gives an example of the use of asynchronous
.\" notification.
2番目のサンプルプログラムに非同期通知の例があります。
.PP
.\" .SH "Functions Associated with the COPY Command"
.SH "COPY コマンドに関連した関数"
.PP
.\" The
.\" .I copy
.\" command in Postgres has options to read from or write to the network
.\" connection used by Libpq.
Postgres の
.I copy
コマンドには
 Libpq に使われているネットワーク接続に対しての読み書きのオプションがあります。
.\"   Therefore, functions are necessary to
.\" access this network connection directly so applications may take full
.\" advantage of this capability.
ですから、関数がこのネットワーク接続に直接アクセスすることが必要で、
そうすることで、この特徴の長所をフルに生かすことができるのです。
.PP
.B PQgetline
.IP
.\" Reads a newline-terminated line of characters (transmitted by the
.\" backend server) into a buffer 
.\" .I string 
.\" of size
.\" .I length .
(バックエンドサーバから送られた) 改行で終端する文字列一行を
.I length
サイズのバッファ
.I string
に読み込みます。
.\" Like
.\" .I fgets (3),
.\" this routine copies up to 
.\" .I length "-1"
.\" characters into 
.\" .I string .
.I fgets(3)
のように、このルーチンは
.I length "-1"
文字まで
.I string
にコピーします。
.\" It is like 
.\" .I gets (3),
.\" however, in that it converts the terminating newline into a null
.\" character.
しかし、
.I gets (3)
のように、終端の改行をヌル文字に変換します。
.IP
.\" .I PQgetline
.\" returns EOF at EOF, 0 if the entire line has been read, and 1 if the
.\" buffer is full but the terminating newline has not yet been read.
.I PQgetline
は最後に EOFを、一行全部読んだ時に 0を、
バッファがいっぱいになってしまってもまだ終端の改行を読んでいないときに 1を返します。
.IP
.\" Notice that the application must check to see if a new line consists
.\" of the characters \*(lq\\.\*(rq, which indicates that the backend
.\" server has finished sending the results of the 
.\" .I copy
.\" command.
アプリケーションは新しい行が
バックエンドサーバが
.I copy
コマンドの結果を送り終えたことを示す
 \*(lq\\.\*(rq という文字になっているかどうかをチェックしなくてはなりません。
.\"   Therefore, if the application ever expects to receive lines
.\" that are more than
.\" .I length "-1"
.\" characters long, the application must be sure to check the return
.\" value of 
.\" .I PQgetline
.\" very carefully.
そして、もしアプリケーションが
.I length "-1"
文字以上の行を読み込むことがあるようなら、
アプリケーションは
.I PQgetline
の戻り値を注意深くチェックしなくてはなりません。
.IP
.\" The code in
.\" .nf
.\" \&../src/bin/psql/psql.c
.\" .fi
.\" contains routines that correctly handle the copy protocol.
.nf
\&../src/bin/psql/psql.c
.fi
のコードには COPY プロトコルの正しい処理を行うルーチンが含まれています。
.nf
int PQgetline(PGconn *conn,
              char *string,
              int length)
.fi
.PP
.B PQputline
.IP
.\" Sends a null-terminated 
.\" .I string
.\" to the backend server.
ヌル終端文字列
.I string
をバックエンドサーバに送ります。
.IP
.\" The application must explicitly send the characters \*(lq\\.\*(rq
.\" to indicate to the backend that it has finished sending its data.
アプリケーションはデータを送り終えたときには、
 \*(lq\\.\*(rq という文字列を明示的にバックエンドに送らなくてはなりません。
.nf
void PQputline(PGconn *conn,
               char *string);
.fi
.PP
.B PQendcopy
.IP
.\" Syncs with the backend.  This function waits until the backend has
.\" finished the copy.
バックエンドと同期をとります。
この関数はバックエンドが COPY を終えるまで待ちます。
.\"   It should either be issued when the
.\" last string has been sent to the backend using
.\" .I PQputline
.\" or when the last string has been received from the backend using
.\" .I PGgetline .
これは
.I PQputline
で最後の文字列をバックエンドに送った時と、
.I PQgetline
で最後の文字列をバックエンドから受け取った時の両方とも発行すべきです。
.\" It must be issued or the backend may get \*(lqout of sync\*(rq with
.\" the frontend.
発行しなければ、
\*(lqout of sync\*(rq をバックエンドから受け取ることがあります。
.\"   Upon return from this function, the backend is ready to
.\" receive the next query.
この関数から戻ると、
バックエンドは次の問い合わせを受け取る準備ができています。
.IP
.\" The return value is 0 on successful completion, nonzero otherwise.
正常終了すると 0を、それ以外には 0以外が返ります。
.nf
int PQendcopy(PGconn *conn);
.fi
.\" As an example:
例としては:
.nf
PQexec(conn, "create table foo (a int4, b char16, d float8)");
PQexec(conn, "copy foo from stdin");
PQputline(conn, "3<TAB>hello world<TAB>4.5\en");
PQputline(conn,"4<TAB>goodbye world<TAB>7.11\en");
\&...
PQputline(conn,"\\.\en");
PQendcopy(conn);
.fi
.PP
.\" .SH "LIBPQ Tracing Functions"
.SH "LIBPQ トレース関数"
.PP
.B PQtrace
.IP
.\" Enable tracing of the frontend/backend communication to a debugging file
.\" stream. 
デバッグファイルストリームへの
フロントエンド/バックエンドの通信のトレースを有効にします。
.nf
void PQtrace(PGconn *conn
             FILE *debug_port)
.fi
.PP
.B PQuntrace 
.IP
.\" Disable tracing started by 
.\" .I PQtrace
.I PQtrace
で始めたトレースを無効にします。
.nf
void PQuntrace(PGconn *conn)
.fi
.PP
.\" .SH "User Authentication Functions"
.SH "ユーザ認証関数"
.PP
.\" If the user has generated the appropriate authentication credentials
.\" (e.g., obtaining
.\" .I Kerberos
.\" tickets), the frontend/backend authentication process is handled by
.\" .I PQexec
.\" without any further intervention.
もしユーザが適切な認証書を生成した(例えば、
.I Kerberos
チケットを入手した)なら、
フロントエンド/バックエンドの認証プロセスは
余計な仲介なしに
.I PQexec
で処理されます。
.\"   The authentication method is now
.\" determined entirely by the DBA (see pga_hba.conf(5)).
現在認証方法は DBA (pg_hba.conf(5)を参照してください) で決定されます。
.\"  The following
.\" routines no longer have any effect and should not be used.
次のルーチンは何の意味もありませんので使わないでください。
.PP
.B fe_getauthname
.IP
.\" Returns a pointer to static space containing whatever name the user
.\" has authenticated.
ユーザが認証された名前を含むスタティックな空間へのポインタを返します。
.\"   Use of this routine in place of calls to
.\" .I getenv (3)
.\" or 
.\" .I getpwuid (3)
.\" by applications is highly recommended, as it is entirely possible that
.\" the authenticated user name is 
.\" .B not
.\" the same as value of the
.\" .B USER
.\" environment variable or the user's entry in
.\" .I /etc/passwd .
アプリケーションがこのルーチンを
.I getenv (3)
や
.I getpwuid (3)
の代わりに使うことが強く推奨されます。
認証されたユーザ名が環境変数
.B USER
の値や
.I /etc/passwd
のユーザエントリと違うことは大いにあるからです。
.nf
char *fe_getauthname(char* errorMessage)
.fi
.PP
.B fe_setauthsvc
.IP
.\" Specifies that Libpq should use authentication service
.\" .I name
.\" rather than its compiled-in default.
Libpq に認証サービスとして、コンパイルされたデフォルトではなく
.I name
を使うように指定します。
.\"  This value is typically taken
.\" from a command-line switch.
この値は典型的にはコマンドラインスイッチとして与えられます。
.nf
void fe_setauthsvc(char *name,
                   char* errorMessage)
.fi
.\" Any error messages from the authentication attempts are returned in the
.\" errorMessage argument.
認証要求からのエラーメッセージは errorMessage 引数に戻ります。
.PP
.SH バグ
.PP
.\" The query buffer is 8192 bytes long, and queries over that length will
.\" be silently truncated.
問い合わせバッファは 8192 バイトの長さですので、
それ以上の長さの問い合わせは何も言わずに切られます。
.PP
.\" .SH "Sample Programs"
.SH "サンプルプログラム"
.bp
.\" .SH "Sample Program 1"
.SH "サンプルプログラム 1"
.PP
.nf M
/*
 * testlibpq.c
.\" * 	Test the C version of Libpq, the Postgres frontend library.
 *	Postgres の C バージョンのフロントエンドライブラリ Libpq のテスト
 *
 *
 */
#include <stdio.h>
#include "libpq-fe.h"

void 
exit_nicely(PGconn* conn)
{
  PQfinish(conn);
  exit(1);
}

main()
{
  char *pghost, *pgport, *pgoptions, *pgtty;
  char* dbName;
  int nFields;
  int i,j;

/*  FILE *debug; */

  PGconn* conn;
  PGresult* res;

.\"  /* begin, by setting the parameters for a backend connection
.\"     if the parameters are null, then the system will try to use
.\"     reasonable defaults by looking up environment variables 
.\"     or, failing that, using hardwired constants */
    /*  まず、バックエンドとの接続のパラメータをセットします。
	もしパラメータが NULL なら、システムは環境変数を参照して
	適当なデフォルト値にしようとします。もしそれもできなければ、
	ハードコーディングされた定数を使います */
	
.\"  pghost = NULL;  /* host name of the backend server */
  pghost = NULL;  /* バックエンドサーバのホスト名 */
.\"  pgport = NULL;  /* port of the backend server */
  pgport = NULL;  /* バックエンドサーバのポート番号 */
.\"  pgoptions = NULL; /* special options to start up the backend server */
  pgoptions = NULL; /* バックエンドサーバのスタートアップオプション */
.\"  pgtty = NULL;     /* debugging tty for the backend server */
  pgtty = NULL;     /* バックエンドサーバのデバッグ出力先 */
  dbName = "template1";

.\"  /* make a connection to the database */
  /* データベースに接続します */
  conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);

.\"  /* check to see that the backend connection was successfully made */
  /* バックエンドへの接続が成功したかどうかチェックします */
  if (PQstatus(conn) == CONNECTION_BAD) {
.\"    fprintf(stderr,"Connection to database '%s' failed.\\n", dbName);
    fprintf(stderr,"データベース'%s'への接続に失敗しました。\\n", dbName);
    fprintf(stderr,"%s",PQerrorMessage(conn));
    exit_nicely(conn);
  }

/*  debug = fopen("/tmp/trace.out","w");  */
/*   PQtrace(conn, debug);  */

.\"  /* start a transaction block */
  /* トランザクションブロックを開始します */
  res = PQexec(conn,"BEGIN"); 
  if (PQresultStatus(res) != PGRES_COMMAND_OK) {
.\"    fprintf(stderr,"BEGIN command failed\\n");
    fprintf(stderr,"BEGINコマンドに失敗しました\\n");
    PQclear(res);
    exit_nicely(conn);
  }
.\"   /* should PQclear PGresult whenever it is no longer needed to avoid
.\"      memory leaks */
  /* メモリリークを防ぐために、使わなくなった PGresult を PQclear 
     しておきます */
  PQclear(res); 

.\"  /* fetch instances from the pg_database, the system catalog of databases*/
  /* データベースのシステムカタログ pg_database からインスタンスを取り出します */
  res = PQexec(conn,"DECLARE mycursor CURSOR FOR select * from pg_database");
  if (PQresultStatus(res) != PGRES_COMMAND_OK) {
.\"    fprintf(stderr,"DECLARE CURSOR command failed\\n");
    fprintf(stderr,"DECLARE CURSOR コマンドに失敗しました。\\n");
    PQclear(res);
    exit_nicely(conn);
  }
  PQclear(res);

  res = PQexec(conn,"FETCH ALL in mycursor");
  if (PQresultStatus(res) != PGRES_TUPLES_OK) {
.\"     fprintf(stderr,"FETCH ALL command didn't return tuples properly\\n");
    fprintf(stderr,"FETCH ALL コマンドがタプルを適切に返しませんでした。\\n");
    PQclear(res);
    exit_nicely(conn);
  }
 
.\"  /* first, print out the attribute names */
  /* まず属性名を出力しま。 */
  nFields = PQnfields(res);
  for (i=0; i < nFields; i++) {
    printf("%-15s",PQfname(res,i));
  }
  printf("\\n\\n");

.\"  /* next, print out the instances */
  /* 次いで、インスタンスを出力します */
  for (i=0; i < PQntuples(res); i++) {
    for (j=0  ; j < nFields; j++) {
      printf("%-15s", PQgetvalue(res,i,j));
    }
    printf("\\n");
  }

  PQclear(res);
  
.\"  /* close the cursor */
  /* カーソルを閉じます */
  res = PQexec(conn, "CLOSE mycursor");
  PQclear(res);

.\"  /* commit the transaction */
  /* トランザクションをコミットします */
  res = PQexec(conn, "COMMIT");
  PQclear(res);

.\"  /* close the connection to the database and cleanup */
  /* データベースへの接続を閉じてクリーンアップします */
  PQfinish(conn);

/*   fclose(debug); */
}
.fi
.bp
.\" .SH "Sample Program 2"
.SH "サンプルプログラム 2"
.PP
.nf M
/*
 * testlibpq2.c
.\" * 	Test of the asynchronous notification interface
 * 	非同期通知インタフェイスのテスト
 *
.\"   populate a database with the following:
次のようにデータベースを作ってください:

CREATE TABLE TBL1 (i int4);

CREATE TABLE TBL2 (i int4);

CREATE RULE r1 AS ON INSERT TO TBL1 DO [INSERT INTO TBL2 values (new.i); NOTIFY TBL2];

.\" * Then start up this program
.\" * After the program has begun, do
 * そしてこのプログラムをスタートさせます
 * プログラムがスタートしたら次のようにします

INSERT INTO TBL1 values (10);

 *
 *
 */
#include <stdio.h>
#include "libpq-fe.h"

void exit_nicely(PGconn* conn)
{
  PQfinish(conn);
  exit(1);
}

main()
{
  char *pghost, *pgport, *pgoptions, *pgtty;
  char* dbName;
  int nFields;
  int i,j;

  PGconn* conn;
  PGresult* res;
  PGnotify* notify;

.\"   /* begin, by setting the parameters for a backend connection
.\"      if the parameters are null, then the system will try to use
.\"      reasonable defaults by looking up environment variables 
.\"      or, failing that, using hardwired constants */
    /*  まず、バックエンドとの接続のパラメータをセットします。
	もしパラメータが NULL なら、システムは環境変数を参照して
	適当なデフォルト値にしようとします。もしそれもできなければ、
	ハードコーディングされた定数を使います */
.\"  pghost = NULL;  /* host name of the backend server */
  pghost = NULL;  /* バックエンドサーバのホスト名 */
.\"  pgport = NULL;  /* port of the backend server */
  pgport = NULL;  /* バックエンドサーバのポート番号 */
.\"  pgoptions = NULL; /* special options to start up the backend server */
  pgoptions = NULL; /* バックエンドサーバのスタートアップオプション */
.\"  pgtty = NULL;     /* debugging tty for the backend server */
  pgtty = NULL;     /* バックエンドサーバのデバッグ出力先 */
.\"  dbName = getenv("USER"); /* change this to the name of your test database*/
  dbName = getenv("USER"); /* これをテストのデータベース名に変えてください */

.\"  /* make a connection to the database */
  /* データベースに接続します */
  conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);

.\"  /* check to see that the backend connection was successfully made */
  /* バックエンドへの接続が成功したかどうかチェックします */
  if (PQstatus(conn) == CONNECTION_BAD) {
.\"    fprintf(stderr,"Connection to database '%s' failed.\\n", dbName);
    fprintf(stderr,"データベース'%s'への接続に失敗しました。\\n", dbName);
    fprintf(stderr,"%s",PQerrorMessage(conn));
    exit_nicely(conn);
  }

  res = PQexec(conn, "LISTEN TBL2");
  if (PQresultStatus(res) != PGRES_COMMAND_OK) {
.\"    fprintf(stderr,"LISTEN command failed\\n");
    fprintf(stderr,"LISTEN コマンドに失敗しました。\\n");
    PQclear(res);
    exit_nicely(conn);
  }
.\"   /* should PQclear PGresult whenever it is no longer needed to avoid
.\"      memory leaks */
  /* メモリリークを防ぐために、使わなくなった PGresult を PQclear 
     しておきます */
  PQclear(res); 

  while (1) {
.\"      /* async notification only come back as a result of a query*/
      /* 非同期通知は問い合わせの結果として戻るだけです */
.\"      /* we can send empty queries */
      /* 空の問い合わせを送ることもできます。*/
      res = PQexec(conn, "");
/*      printf("res->status = %s\\n", pgresStatus[PQresultStatus(res)]); */
.\"      /* check for asynchronous returns */
      /* 非同期通知をチェックします */
      notify = PQnotifies(conn);
      if (notify) {
	  fprintf(stderr,
.\"		  "ASYNC NOTIFY of '%s' from backend pid '%d' received\\n",
		  "'%s' への非同期通知をバックエンド(pid '%d')から受け取りました。\\n",
		  notify->relname, notify->be_pid);
	  free(notify);
	  break;
      }
      PQclear(res);
  }
      
.\"  /* close the connection to the database and cleanup */
  /* データベースへの接続を閉じてクリーンアップします */
  PQfinish(conn);

}
.fi
.bp
.\" .SH "Sample Program 3"
.SH "サンプルプログラム 3"
.PP
.nf M
/*
 * testlibpq3.c
.\" * 	Test the C version of Libpq, the Postgres frontend library.
 *	Postgres の C バージョンのフロントエンドライブラリ Libpq のテスト
.\" *   tests the binary cursor interface
 *   バイナリカーソルのテスト
 *
 *
 *
.\" populate a database by doing the following:
 次のようにデータベースを作ってください:
 
CREATE TABLE test1 (i int4, d float4, p polygon);

INSERT INTO test1 values (1, 3.567, '(3.0, 4.0, 1.0, 2.0)'::polygon);

INSERT INTO test1 values (2, 89.05, '(4.0, 3.0, 2.0, 1.0)'::polygon);

.\" the expected output is:
 このような出力になるはずです:

tuple 0: got
 i = (4 bytes) 1,
 d = (4 bytes) 3.567000,
 p = (4 bytes) 2 points         boundbox = (hi=3.000000/4.000000, lo = 1.000000,2.000000)
tuple 1: got
 i = (4 bytes) 2,
 d = (4 bytes) 89.050003,
 p = (4 bytes) 2 points         boundbox = (hi=4.000000/3.000000, lo = 2.000000,1.000000)

 *
 */
#include <stdio.h>
#include "libpq-fe.h"
#include "utils/geo-decls.h" /* for the POLYGON type */

void exit_nicely(PGconn* conn)
{
  PQfinish(conn);
  exit(1);
}

main()
{
  char *pghost, *pgport, *pgoptions, *pgtty;
  char* dbName;
  int nFields;
  int i,j;
  int i_fnum, d_fnum, p_fnum;

  PGconn* conn;
  PGresult* res;

.\"  /* begin, by setting the parameters for a backend connection
.\"     if the parameters are null, then the system will try to use
.\"     reasonable defaults by looking up environment variables 
.\"     or, failing that, using hardwired constants */
  /*  まず、バックエンドとの接続のパラメータをセットします。
      もしパラメータが NULL なら、システムは環境変数を参照して
      適当なデフォルト値にしようとします。もしそれもできなければ、
      ハードコーディングされた定数を使います */
.\"  pghost = NULL;  /* host name of the backend server */
  pghost = NULL;  /* バックエンドサーバのホスト名 */
.\"  pgport = NULL;  /* port of the backend server */
  pgport = NULL;  /* バックエンドサーバのポート番号 */
.\"  pgoptions = NULL; /* special options to start up the backend server */
  pgoptions = NULL; /* バックエンドサーバのスタートアップオプション */
.\"  pgtty = NULL;     /* debugging tty for the backend server */
  pgtty = NULL;     /* バックエンドサーバのデバッグ出力先 */
.\"  dbName = getenv("USER"); /* change this to the name of your test database*/
  dbName = getenv("USER"); /* これをテストのデータベース名に変えてください */

.\"  /* make a connection to the database */
  /* データベースに接続します */
  conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);

.\"  /* check to see that the backend connection was successfully made */
  /* バックエンドへの接続が成功したかどうかチェックします */
  if (PQstatus(conn) == CONNECTION_BAD) {
.\"    fprintf(stderr,"Connection to database '%s' failed.\\n", dbName);
    fprintf(stderr,"データベース'%s'への接続に失敗しました。\\n", dbName);
    fprintf(stderr,"%s",PQerrorMessage(conn));
    exit_nicely(conn);
  }

.\"  /* start a transaction block */
  /* トランザクションブロックを開始します */
  res = PQexec(conn,"BEGIN"); 
  if (PQresultStatus(res) != PGRES_COMMAND_OK) {
.\"    fprintf(stderr,"BEGIN command failed\\n");
    fprintf(stderr,"BEGINコマンドに失敗しました\\n");
    PQclear(res);
    exit_nicely(conn);
  }
.\"  /* should PQclear PGresult whenever it is no longer needed to avoid
.\"     memory leaks */
  /* メモリリークを防ぐために、使わなくなった PGresult を PQclear 
     しておきます */
  PQclear(res); 

.\"  /* fetch instances from the pg_database, the system catalog of databases*/
  /* データベースのシステムカタログ pg_database からインスタンスを取り出します */
  res = PQexec(conn,"DECLARE mycursor BINARY CURSOR FOR select * from test1");
  if (PQresultStatus(res) != PGRES_COMMAND_OK) {
.\"    fprintf(stderr,"DECLARE CURSOR command failed\\n");
    fprintf(stderr,"DECLARE CURSOR コマンドに失敗しました。\\n");
    PQclear(res);
    exit_nicely(conn);
  }
  PQclear(res);

  res = PQexec(conn,"FETCH ALL in mycursor");
  if (PQresultStatus(res) != PGRES_TUPLES_OK) {
.\"    fprintf(stderr,"FETCH ALL command didn't return tuples properly\\n");
    fprintf(stderr,"FETCH ALL コマンドがタプルを適切に返しませんでした。\\n");
    PQclear(res);
    exit_nicely(conn);
  }
 
  i_fnum = PQfnumber(res,"i");
  d_fnum = PQfnumber(res,"d");
  p_fnum = PQfnumber(res,"p");
  
  for (i=0;i<3;i++) {
      printf("type[%d] = %d, size[%d] = %d\\n",
	     i, PQftype(res,i), 
	     i, PQfsize(res,i));
  }
  for (i=0; i < PQntuples(res); i++) {
    int *ival; 
    float *dval;
    int plen;
    POLYGON* pval;
.\"    /* we hard-wire this to the 3 fields we know about */
    /* これを知っている 3つのフィールドにします */
    ival =  (int*)PQgetvalue(res,i,i_fnum);
    dval =  (float*)PQgetvalue(res,i,d_fnum);
    plen = PQgetlength(res,i,p_fnum);

.\"    /* plen doesn't include the length field so need to increment by VARHDSZ*/
    /* plen にはlength フィールドの長さが含まれていないので、
       VARHDSZ を足す必要があります */
    pval = (POLYGON*) malloc(plen + VARHDRSZ); 
    pval->size = plen;
    memmove((char*)&pval->npts, PQgetvalue(res,i,p_fnum), plen);
    printf("tuple %d: got\\n", i);
    printf(" i = (%d bytes) %d,\\n",
	   PQgetlength(res,i,i_fnum), *ival);
    printf(" d = (%d bytes) %f,\\n",
	   PQgetlength(res,i,d_fnum), *dval);
    printf(" p = (%d bytes) %d points \\tboundbox = (hi=%f/%f, lo = %f,%f)\\n",
	   PQgetlength(res,i,d_fnum),
	   pval->npts,
	   pval->boundbox.xh,
	   pval->boundbox.yh,
	   pval->boundbox.xl,
	   pval->boundbox.yl);
  }

  PQclear(res);
  
.\"  /* close the cursor */
  /* カーソルを閉じます */
  res = PQexec(conn, "CLOSE mycursor");
  PQclear(res);

.\"  /* commit the transaction */
  /* トランザクションをコミットします */
  res = PQexec(conn, "COMMIT");
  PQclear(res);

.\"  /* close the connection to the database and cleanup */
  /* データベースへの接続を閉じてクリーンアップします */
  PQfinish(conn);

}
.fi