Received: from localhost (unknown [200.46.204.183]) by postgresql.org (Postfix) with ESMTP id E640F2E0178 for ; Fri, 1 Feb 2008 07:05:44 -0400 (AST) Received: from postgresql.org ([200.46.204.71]) by localhost (mx1.hub.org [200.46.204.183]) (amavisd-maia, port 10024) with ESMTP id 41121-07 for ; Fri, 1 Feb 2008 07:05:41 -0400 (AST) Received: from qb-out-0506.google.com (qb-out-0506.google.com [72.14.204.225]) by postgresql.org (Postfix) with ESMTP id B50AB2E017B for ; Fri, 1 Feb 2008 07:05:40 -0400 (AST) Received: by qb-out-0506.google.com with SMTP id o12so783714qba.17 for ; Fri, 01 Feb 2008 03:05:39 -0800 (PST) Received: by 10.100.171.10 with SMTP id t10mr6995771ane.58.1201863938943; Fri, 01 Feb 2008 03:05:38 -0800 (PST) Received: from PASHA ( [82.207.102.193]) by mx.google.com with ESMTPS id o11sm7667343fkf.9.2008.02.01.03.05.36 (version=SSLv3 cipher=OTHER); Fri, 01 Feb 2008 03:05:37 -0800 (PST) Date: Fri, 1 Feb 2008 13:05:38 +0200 X-Mailer: The Bat! (v3.62.14) Professional Reply-To: Pavel Golub Organization: Microolap X-Priority: 3 (Normal) Message-ID: <804818750.20080201130538@gf.microolap.com> To: Bruce Momjian CC: pgsql-docs@postgresql.org Subject: Re: Lack of docs for libpq C Library In-Reply-To: <200801311601.m0VG1Mh28607@momjian.us> References: <20080131152736.GG8602@alvh.no-ip.org> <200801311601.m0VG1Mh28607@momjian.us> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit From: Pavel Golub X-Virus-Scanned: Maia Mailguard 1.0.1 X-Archive-Number: 200802/8 X-Sequence-Number: 4802 Hello, Bruce. You wrote: BM> Alvaro Herrera wrote: >> Bruce Momjian wrote: >> > Pavel Golub wrote: >> > > Hello, pgsql-docs. >> > > >> > > I noticed that some exported functions are not documented in the >> > > Chapter 30. However, there are some info about them in other chapters, >> > > e.g. PQclientEncoding using is described in chapter 22.2.3 "Automatic >> > > Character Set Conversion Between Server and Client". >> > >> > Though they are exported, the are more for internal use, e.g. psql, >> > rather than something we want people using --- they can change from >> > release to release. >> >> I disagree. I think PQinitSSL is meant to be called from the >> application, for example. Same with PQsetClientEncoding. And the BM> I see PQinitSSL and PQsetClientEncoding mentioned in the documentation; BM> is it lacking enough detail? Well they are. But in wrong place. I was using 'SET client_encoding TO xxx' SQL a long time. And then I found PQsetClientEncoding in wrong place. Then PQmblen function. I beleive it means PQMultiByteLength? If so, it would be very usefull for me. >> PQExpBuffer stuff is all very useful, and years ago when I wrote an app >> to use it it annoyed me that there were no docs on it. (Back then, I >> didn't realize I could have complained about it or written the docs >> myself). BM> True but we don't guarantee the API of many of these functions like we BM> do the documented ones. You may state in that these functions are internal and nobody is recommended using them. At least developers haven't to try to guess what they mean and create some kind of Colossus with feet of clay based on these guesses. BM> --------------------------------------------------------------------------- >> >> >> > --------------------------------------------------------------------------- >> > >> > >> > > >> > > This is the list of exported functions without docs: >> > > ================ >> > > PQclientEncoding >> > > PQsetClientEncoding >> > > PQconninfoFree >> > > PQdsplen >> > > PQenv2encoding >> > > PQinitSSL >> > > PQmblen >> > > PQregisterThreadLock >> > > appendPQExpBuffer >> > > appendPQExpBufferChar >> > > appendPQExpBufferStr >> > > createPQExpBuffer >> > > destroyPQExpBuffer >> > > enlargePQExpBuffer >> > > initPQExpBuffer >> > > appendBinaryPQExpBuffer >> > > pg_char_to_encoding >> > > pg_encoding_to_char >> > > pg_utf_mblen >> > > pg_valid_server_encoding >> > > pgresStatus >> > > pqsignal >> > > printfPQExpBuffer >> > > resetPQExpBuffer >> > > termPQExpBuffer >> >> >> -- >> Alvaro Herrera http://www.CommandPrompt.com/ >> The PostgreSQL Company - Command Prompt, Inc. >> >> ---------------------------(end of broadcast)--------------------------- >> TIP 9: In versions below 8.0, the planner will ignore your desire to >> choose an index scan if your joining column's datatypes do not >> match -- With best wishes, Pavel mailto:pavel@gf.microolap.com