Subject: Lack of docs for libpq C Library

From: Pavel Golub <[email-masked]>
Date: Thu, 31 Jan 2008 11:20:41 +0200

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".

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

For me as a developer this is extremely important info.

Thanks for understanding.

-- 
With best wishes,
 Pavel                          mailto:[email-masked]

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 31 Jan 2008 10:09:33 -0500 (EST)

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

---------------------------------------------------------------------------

> ---------------------------(end of broadcast)---------------------------
> TIP 4: Have you searched our list archives?
> 
>                http://archives.postgresql.org

-- 
  Bruce Momjian  <[email-masked]>        http://momjian.us
  EnterpriseDB                             http://postgres.enterprisedb.com

  + If your life is a hard drive, Christ can be your backup. +

---

From: Alvaro Herrera <[email-masked]>
Date: Thu, 31 Jan 2008 12:27:36 -0300

> rather than something we want people using --- they can change from

I disagree.  I think PQinitSSL is meant to be called from the
application, for example.  Same with PQsetClientEncoding.  And the
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).

-- 
Alvaro Herrera                                http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 31 Jan 2008 11:01:22 -0500 (EST)

> application, for example.  Same with PQsetClientEncoding.  And the

I see PQinitSSL and PQsetClientEncoding mentioned in the documentation; 
is it lacking enough detail?

> didn't realize I could have complained about it or written the docs

True but we don't guarantee the API of many of these functions like we
do the documented ones.

> 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

---

From: Tom Lane <[email-masked]>
Date: Thu, 31 Jan 2008 11:22:17 -0500

> didn't realize I could have complained about it or written the docs

PQinitSSL *is* documented, though looking at the para immediately raises
the question what the heck we are doing pointing to a random hp.com page
for SSL documentation.

PQsetClientEncoding seems to be documented in the wrong place.

As for the expbuffer stuff, that is intentionally not considered part of
libpq's exported API.  If someone uses it, they get to keep both parts
when it breaks.

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 31 Jan 2008 11:44:53 -0500 (EST)

> the question what the heck we are doing pointing to a random hp.com page

I added that for 8.3.  The HP documentation seemed excellent, which is
why I added it.

---

From: Tom Lane <[email-masked]>
Date: Thu, 31 Jan 2008 12:01:41 -0500

> I added that for 8.3.  The HP documentation seemed excellent, which is

The question is not about whether that doc is good, bad, or indifferent;
it is about the likely lifespan of the URL.  A URL containing mostly
random numbers instead of words does not fill me with confidence.
Furthermore HP is hardly the authoritative reference on SSL.  Can't
we find an RFC or something?

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 31 Jan 2008 12:14:54 -0500 (EST)

> random numbers instead of words does not fill me with confidence.

True, and Magnus was concerned about that as well.  What I liked about
it was the diagrams which I haven't seen anywhere else.  Our doc
reference is:

	(See http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html  for
	diagrams showing SSL certificate usage.)

I put it in parentheses to highlight the URL is only for reference to
the diagrams and explaination.  We can either remove the URL or remove
it if the URL changes.

SSL is pretty complicated so when I saw something that made it clearer,
I added it.

> we find an RFC or something?

See above.

---

From: Peter Eisentraut <[email-masked]>
Date: Thu, 31 Jan 2008 18:50:04 +0100

> > we find an RFC or something?

If anything, we should link to OpenSSL, because they implement the API we are 
referring to.  I don't know what HP has to do with it.

-- 
Peter Eisentraut
http://developer.postgresql.org/~petere/

---

From: Tom Lane <[email-masked]>
Date: Thu, 31 Jan 2008 12:58:42 -0500

> referring to.  I don't know what HP has to do with it.

Yeah, I was thinking a simple pointer to www.openssl.org would be more
appropriate.  We're not here to substitute for somebody doing their
own Google search ...

			regards, tom lane

---

From: Alvaro Herrera <[email-masked]>
Date: Thu, 31 Jan 2008 15:04:59 -0300

> the diagrams and explaination.  We can either remove the URL or remove

If you really like that page, you could link to archive.org's version of
it:

http://web.archive.org/web/20060903180210/http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html

-- 
Alvaro Herrera                                http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 31 Jan 2008 18:10:53 -0500 (EST)

> http://web.archive.org/web/20060903180210/http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html
                             --------
                             2006-09-03

Well, archive.org indicates the URL has been stable for at least 15
months so the original might be OK.

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 31 Jan 2008 18:13:56 -0500 (EST)

> Yeah, I was thinking a simple pointer to www.openssl.org would be more

I looked at the SSL docs and they are _minimal_:

	http://www.openssl.org/docs/

In fact "[STILL INCOMPLETE]" is on almost every item.

> appropriate.  We're not here to substitute for somebody doing their

The HP page is not a primary Google hit --- it took me trolling though
many copies of the SSL manual pages to find it.

---

From: Alvaro Herrera <[email-masked]>
Date: Thu, 31 Jan 2008 20:18:27 -0300

> > http://web.archive.org/web/20060903180210/http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html

The point is that archive.org will keep that copy online even if hp.com
decides to shut it down or change it.

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 31 Jan 2008 18:19:15 -0500 (EST)

> http://web.archive.org/web/20060903180210/http://h71000.www7.hp.com/DOC/83final/BA554_90007/ch04s02.html

Basically, given the URL has been unchanged since at least September
2006 and because it is hard to find via Google, I think we should keep
the HP URL (to give them credit) and fall back to archive.org in case
the URL ever becomes inactive.

SSL is not an easy thing to underestand so having links to good
documentation is a big plus for us.  Using that documentation I was able
to understand SSL enough to make some improvements to the SSL code that
I will apply for 8.4.

---

From: Peter Eisentraut <[email-masked]>
Date: Fri, 1 Feb 2008 02:52:13 +0100

> many copies of the SSL manual pages to find it.

Nevertheless, I think making such semantically significant changes *hours* 
before a major release should be avoided.

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 31 Jan 2008 21:44:51 -0500 (EST)

> before a major release should be avoided.

Well, it is just SGML --- I don't see a problem with adjustments at this
time.  FYI, the HP URL was placed there at least a month ago by me.  I
did add a comment in the SGML based on Alvaro's suggestion.

---

From: "Joshua D. Drake" <[email-masked]>
Date: Thu, 31 Jan 2008 19:45:36 -0800

On Thu, 31 Jan 2008 20:18:27 -0300
Alvaro Herrera <[email-masked]> wrote:

> Bruce Momjian wrote:
> > Alvaro Herrera wrote:
> 
> > > If you really like that page, you could link to archive.org's
> > > version of it:
> > > 
> The point is that archive.org will keep that copy online even if
> hp.com decides to shut it down or change it.
> 

There is a question to the legality of the archive.org copy. The legal
notice of the document states that there must be a valid license for
the product to copy. 

*IF* we link that document, we need to link to the HP site.

Sincerely,

Joshua D. Drake

- -- 
The PostgreSQL Company since 1997: http://www.commandprompt.com/ 
PostgreSQL Community Conference: http://www.postgresqlconference.org/
Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate
PostgreSQL SPI Liaison | SPI Director |  PostgreSQL political pundit

---

From: Tom Lane <[email-masked]>
Date: Fri, 01 Feb 2008 00:10:07 -0500

> *IF* we link that document, we need to link to the HP site.

Uh, this is nonsense.  Even if archive.org is violating HP's copyright
(a point un-tested at law), we cannot be violating anything by which
URL we choose to point to.

The main problem with using the link as it stands is that it is *highly*
unlikely that it will remain valid for the lifespan of the PG 8.3
documentation (let alone subsequent versions).  I've been dealing with
HP's website for many years and I have good reason to know that page
URLs of the kind that Bruce has chosen to quote do not have long shelf
lives.

Personally I would vote for not having the link there at all.  It is not
adding anything very critical to our docs, it is likely to be broken
soon (for some value of soon), and if there is any question about the
legality then that's just frosting on the cake.

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 1 Feb 2008 00:27:14 -0500 (EST)

> URL we choose to point to.

Right, it seems like it would be archive.org's problem.

> documentation (let alone subsequent versions).  I've been dealing with

Did you see Alvaro's archive.org URL that showed it was the same in
September, 2006?

> legality then that's just frosting on the cake.

I found it useful and I think others will as well.  Agreed it is not
critical, but does a URL have to be critical to be on our docs.

---

From: Tom Lane <[email-masked]>
Date: Fri, 01 Feb 2008 00:29:50 -0500

> Did you see Alvaro's archive.org URL that showed it was the same in

Yeah, which means its half-life is about gone, in my experience.

			regards, tom lane

---

From: Bruce Momjian <[email-masked]>
Date: Fri, 1 Feb 2008 00:30:57 -0500 (EST)

> Yeah, which means its half-life is about gone, in my experience.

OK, you used to work for HP so you certainly know more than I do. 
Should I use archive.org instead?

---

From: "Joshua D. Drake" <[email-masked]>
Date: Thu, 31 Jan 2008 21:32:44 -0800

> URL we choose to point to.

I think you missed my point :). My point was if HP got snarky about it, 
the link would die. Whereas it is likely that HP would keep their link 
up (in theory of course).

> URLs of the kind that Bruce has chosen to quote do not have long shelf

Not arguing with this. I just think if we are going to link it, we 
should link the authoritative source.

> legality then that's just frosting on the cake.

It seems to me that if we are going to have the information we need to 
have it from a source that is reasonably guaranteed to be maintained. If 
we don't trust that HP will do that then I would agree that we should 
leave the link out.

Sincerely,

Joshua D. Drake

---

From: Pavel Golub <[email-masked]>
Date: Fri, 1 Feb 2008 13:05:38 +0200

Hello, Bruce.

You wrote:

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

>> didn't realize I could have complained about it or written the docs

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> ---------------------------------------------------------------------------

---

From: Bruce Momjian <[email-masked]>
Date: Thu, 6 Mar 2008 10:39:05 -0500 (EST)

> PQsetClientEncoding seems to be documented in the wrong place.

I have moved the libpq client encoding documentation into the libpq doc
section, and just referenced it from the localization docs.  Backpatched
to 8.3.X.

  + If your life is a hard drive, Christ can be your backup. +
Index: doc/src/sgml/charset.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/charset.sgml,v
retrieving revision 2.84
diff -c -c -r2.84 charset.sgml
*** doc/src/sgml/charset.sgml	28 Sep 2007 22:25:49 -0000	2.84
--- doc/src/sgml/charset.sgml	6 Mar 2008 15:32:28 -0000
***************
*** 1110,1140 ****
  
        <listitem>
         <para>
!         Using <application>libpq</> functions.
!         <command>\encoding</command> actually calls
!         <function>PQsetClientEncoding()</function> for its purpose.
! 
! <synopsis>
! int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>);
! </synopsis>
! 
!         where <replaceable>conn</replaceable> is a connection to the server,
!         and <replaceable>encoding</replaceable> is the encoding you
!         want to use. If the function successfully sets the encoding, it returns 0,
!         otherwise -1. The current encoding for this connection can be determined by
!         using:
! 
! <synopsis>
! int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>);
! </synopsis>
! 
!         Note that it returns the encoding ID, not a symbolic string
!         such as <literal>EUC_JP</literal>. To convert an encoding ID to an encoding name, you
!         can use:
! 
! <synopsis>
! char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
! </synopsis>
         </para>
        </listitem>
  
--- 1110,1116 ----
  
        <listitem>
         <para>
!         <application>libpq</> (<xref linkend="libpq-control">) has functions to control the client encoding.
         </para>
        </listitem>
  
Index: doc/src/sgml/libpq.sgml
===================================================================
RCS file: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v
retrieving revision 1.255
diff -c -c -r1.255 libpq.sgml
*** doc/src/sgml/libpq.sgml	31 Jan 2008 23:31:33 -0000	1.255
--- doc/src/sgml/libpq.sgml	6 Mar 2008 15:32:32 -0000
***************
*** 4417,4422 ****
--- 4417,4472 ----
    <variablelist>
     <varlistentry>
      <term>
+      <function>PQclientEncoding</function>
+      <indexterm>
+       <primary>PQclientEncoding</primary>
+      </indexterm>
+     </term>
+ 
+     <listitem>
+      <para>
+       Returns the client encoding.
+       <synopsis>
+       int PQclientEncoding(const PGconn *<replaceable>conn</replaceable>);
+       </synopsis>
+ 
+       Note that it returns the encoding ID, not a symbolic string
+       such as <literal>EUC_JP</literal>. To convert an encoding ID to an encoding name, you
+       can use:
+ 
+ <synopsis>
+ char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
+ </synopsis>
+      </para>
+     </listitem>
+    </varlistentry>
+ 
+    <varlistentry>
+     <term>
+      <function>PQsetClientEncoding</function>
+      <indexterm>
+       <primary>PQsetClientEncoding</primary>
+      </indexterm>
+     </term>
+ 
+     <listitem>
+      <para>
+       Sets the client encoding.
+       <synopsis>
+       int PQsetClientEncoding(PGconn *<replaceable>conn</replaceable>, const char *<replaceable>encoding</replaceable>);
+       </synopsis>
+ 
+       <replaceable>conn</replaceable> is a connection to the server,
+       and <replaceable>encoding</replaceable> is the encoding you want to
+       use. If the function successfully sets the encoding, it returns 0,
+       otherwise -1. The current encoding for this connection can be
+       determined by using <function>PQclientEncoding</>.
+      </para>
+     </listitem>
+    </varlistentry>
+ 
+    <varlistentry>
+     <term>
       <function>PQsetErrorVerbosity</function>
       <indexterm>
        <primary>PQsetErrorVerbosity</primary>