Обсуждение: Lack of docs for libpq C Library
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:pavel@gf.microolap.com
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. --------------------------------------------------------------------------- > > 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:pavel@gf.microolap.com > > > ---------------------------(end of broadcast)--------------------------- > TIP 4: Have you searched our list archives? > > http://archives.postgresql.org -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://postgres.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
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 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). > --------------------------------------------------------------------------- > > > > > > 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.
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 I see PQinitSSL and PQsetClientEncoding mentioned in the documentation; is it lacking enough detail? > 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). True but we don't guarantee the API of many of these functions like we do the documented ones. --------------------------------------------------------------------------- > > > > --------------------------------------------------------------------------- > > > > > > > > > > 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 -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://postgres.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Alvaro Herrera <alvherre@commandprompt.com> writes:
> 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).
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
Tom Lane wrote: > Alvaro Herrera <alvherre@commandprompt.com> writes: > > 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). > > 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. I added that for 8.3. The HP documentation seemed excellent, which is why I added it. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://postgres.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Bruce Momjian <bruce@momjian.us> writes:
> Tom Lane wrote:
>> 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.
> I added that for 8.3. The HP documentation seemed excellent, which is
> why I added it.
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
Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
> > Tom Lane wrote:
> >> 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.
>
> > I added that for 8.3. The HP documentation seemed excellent, which is
> > why I added it.
>
> 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.
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.
> Furthermore HP is hardly the authoritative reference on SSL. Can't
> we find an RFC or something?
See above.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Am Donnerstag, 31. Januar 2008 schrieb Bruce Momjian: > 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. > > > Furthermore HP is hardly the authoritative reference on SSL. Can't > > we find an RFC or something? > > See above. 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/
Peter Eisentraut <peter_e@gmx.net> writes:
>>> Furthermore HP is hardly the authoritative reference on SSL. Can't
>>> we find an RFC or something?
>>
>> See above.
> 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.
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
Bruce Momjian wrote: > 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. 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
Alvaro Herrera wrote: > Bruce Momjian wrote: > > > 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. > > 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 -------- 2006-09-03 Well, archive.org indicates the URL has been stable for at least 15 months so the original might be OK. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://postgres.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Alvaro Herrera wrote: > Bruce Momjian wrote: > > > 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. > > 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 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. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://postgres.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Tom Lane wrote:
> Peter Eisentraut <peter_e@gmx.net> writes:
> >>> Furthermore HP is hardly the authoritative reference on SSL. Can't
> >>> we find an RFC or something?
> >>
> >> See above.
>
> > 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.
>
> 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
> own Google search ...
The HP page is not a primary Google hit --- it took me trolling though
many copies of the SSL manual pages to find it.
--
Bruce Momjian <bruce@momjian.us> http://momjian.us
EnterpriseDB http://postgres.enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Bruce Momjian wrote: > Alvaro Herrera wrote: > > 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 > -------- > 2006-09-03 > > Well, archive.org indicates the URL has been stable for at least 15 > months so the original might be OK. The point is that archive.org will keep that copy online even if hp.com decides to shut it down or change it. -- Alvaro Herrera http://www.CommandPrompt.com/ PostgreSQL Replication, Consulting, Custom Development, 24x7 support
Bruce Momjian wrote: > 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 > > own Google search ... > > The HP page is not a primary Google hit --- it took me trolling though > 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. -- Peter Eisentraut http://developer.postgresql.org/~petere/
Peter Eisentraut wrote: > Bruce Momjian wrote: > > 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 > > > own Google search ... > > > > The HP page is not a primary Google hit --- it took me trolling though > > 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. 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. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://postgres.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Thu, 31 Jan 2008 20:18:27 -0300 Alvaro Herrera <alvherre@commandprompt.com> wrote: > Bruce Momjian wrote: > > Alvaro Herrera wrote: > > > > 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 > > -------- > > 2006-09-03 > > > > Well, archive.org indicates the URL has been stable for at least 15 > > months so the original might be OK. > > 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 -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) iD8DBQFHopXjATb/zqfZUUQRAsrjAJ9mbLhVY1w2vKmiG7y3FLpf/p2zUQCffrwY 3OIVlDrmxPSbGxaColBgQ2Y= =G3XM -----END PGP SIGNATURE-----
Tom Lane wrote: > "Joshua D. Drake" <jd@commandprompt.com> writes: > > Alvaro Herrera <alvherre@commandprompt.com> wrote: > >> 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. > > 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. Right, it seems like it would be archive.org's problem. > 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 Did you see Alvaro's archive.org URL that showed it was the same in September, 2006? > 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. 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. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://postgres.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Bruce Momjian <bruce@momjian.us> writes:
> Tom Lane wrote:
>> 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
> Did you see Alvaro's archive.org URL that showed it was the same in
> September, 2006?
Yeah, which means its half-life is about gone, in my experience.
regards, tom lane
Tom Lane wrote: > Bruce Momjian <bruce@momjian.us> writes: > > Tom Lane wrote: > >> 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 > > > Did you see Alvaro's archive.org URL that showed it was the same in > > September, 2006? > > 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? -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://postgres.enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
Tom Lane wrote: > "Joshua D. Drake" <jd@commandprompt.com> writes: >> Alvaro Herrera <alvherre@commandprompt.com> wrote: >>> 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. > > 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. 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). > > 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. Not arguing with this. I just think if we are going to link it, we should link the authoritative source. > > 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. 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
"Joshua D. Drake" <jd@commandprompt.com> writes:
> Alvaro Herrera <alvherre@commandprompt.com> wrote:
>> 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.
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
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
Tom Lane wrote: > Alvaro Herrera <alvherre@commandprompt.com> writes: > > 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). > > 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. -- Bruce Momjian <bruce@momjian.us> http://momjian.us EnterpriseDB http://postgres.enterprisedb.com + 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>