Skip site navigation (1) Skip section navigation (2)

Re: Lack of docs for libpq C Library

From: Pavel Golub <pavel(at)microolap(dot)com>
To: Bruce Momjian <bruce(at)momjian(dot)us>
Cc: pgsql-docs(at)postgresql(dot)org
Subject: Re: Lack of docs for libpq C Library
Date: 2008-02-01 11:05:38
Message-ID: 804818750.20080201130538@gf.microolap.com (view raw or flat)
Thread:
Lists: pgsql-docs
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(at)gf(dot)microolap(dot)com


In response to

pgsql-docs by date

Next:From: Gurjeet SinghDate: 2008-02-03 05:05:46
Subject: Wrong query examples in docs
Previous:From: Joshua D. DrakeDate: 2008-02-01 05:32:44
Subject: Re: Lack of docs for libpq C Library

Privacy Policy | About PostgreSQL
Copyright © 1996-2014 The PostgreSQL Global Development Group