|
1 |
| -<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.263 2008/09/19 20:06:13 tgl Exp $ --> |
| 1 | +<!-- $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.264 2008/09/22 13:55:13 tgl Exp $ --> |
2 | 2 |
|
3 | 3 | <chapter id="libpq">
|
4 | 4 | <title><application>libpq</application> - C Library</title>
|
@@ -593,7 +593,7 @@ typedef struct
|
593 | 593 | char *compiled; /* Fallback compiled in default value */
|
594 | 594 | char *val; /* Option's current value, or NULL */
|
595 | 595 | char *label; /* Label for field in connect dialog */
|
596 |
| - char *dispchar; /* Character to display for this field |
| 596 | + char *dispchar; /* Indicates how to display this field |
597 | 597 | in a connect dialog. Values are:
|
598 | 598 | "" Display entered value as is
|
599 | 599 | "*" Password field - hide value
|
@@ -624,6 +624,51 @@ typedef struct
|
624 | 624 | </listitem>
|
625 | 625 | </varlistentry>
|
626 | 626 |
|
| 627 | + <varlistentry> |
| 628 | + <term><function>PQconninfoParse</function><indexterm><primary>PQconninfoParse</></></term> |
| 629 | + <listitem> |
| 630 | + <para> |
| 631 | + Returns parsed connection options from the provided connection string. |
| 632 | + |
| 633 | +<synopsis> |
| 634 | +PQconninfoOption *PQconninfoParse(const char *conninfo, char **errmsg); |
| 635 | +</synopsis> |
| 636 | + </para> |
| 637 | + |
| 638 | + <para> |
| 639 | + Parses a connection string and returns the resulting options as an |
| 640 | + array; or returns NULL if there is a problem with the connection |
| 641 | + string. This can be used to determine |
| 642 | + the <function>PQconnectdb</function> options in the provided |
| 643 | + connection string. The return value points to an array of |
| 644 | + <structname>PQconninfoOption</structname> structures, which ends |
| 645 | + with an entry having a null <structfield>keyword</> pointer. |
| 646 | + </para> |
| 647 | + |
| 648 | + <para> |
| 649 | + Note that only options explicitly specified in the string will have |
| 650 | + values set in the result array; no defaults are inserted. |
| 651 | + </para> |
| 652 | + |
| 653 | + <para> |
| 654 | + If <literal>errmsg</> is not NULL, then <literal>*errmsg</> is set |
| 655 | + to NULL on success, else to a malloc'd error string explaining |
| 656 | + the problem. (It is also possible for <literal>*errmsg</> to be |
| 657 | + set to NULL even when NULL is returned; this indicates an out-of-memory |
| 658 | + situation.) |
| 659 | + </para> |
| 660 | + |
| 661 | + <para> |
| 662 | + After processing the options array, free it by passing it to |
| 663 | + <function>PQconninfoFree</function>. If this is not done, some memory |
| 664 | + is leaked for each call to <function>PQconninfoParse</function>. |
| 665 | + Conversely, if an error occurs and <literal>errmsg</> is not NULL, |
| 666 | + be sure to free the error string using <function>PQfreemem</>. |
| 667 | + </para> |
| 668 | + |
| 669 | + </listitem> |
| 670 | + </varlistentry> |
| 671 | + |
627 | 672 | <varlistentry>
|
628 | 673 | <term><function>PQfinish</function><indexterm><primary>PQfinish</></></term>
|
629 | 674 | <listitem>
|
@@ -2985,39 +3030,6 @@ typedef struct {
|
2985 | 3030 | </para>
|
2986 | 3031 | </listitem>
|
2987 | 3032 | </varlistentry>
|
2988 |
| - |
2989 |
| - <varlistentry> |
2990 |
| - <term> |
2991 |
| - <function>PQfreemem</function> |
2992 |
| - <indexterm> |
2993 |
| - <primary>PQfreemem</primary> |
2994 |
| - </indexterm> |
2995 |
| - </term> |
2996 |
| - |
2997 |
| - <listitem> |
2998 |
| - <para> |
2999 |
| - Frees memory allocated by <application>libpq</>. |
3000 |
| - <synopsis> |
3001 |
| - void PQfreemem(void *ptr); |
3002 |
| - </synopsis> |
3003 |
| - </para> |
3004 |
| - |
3005 |
| - <para> |
3006 |
| - Frees memory allocated by <application>libpq</>, particularly |
3007 |
| - <function>PQescapeByteaConn</function>, |
3008 |
| - <function>PQescapeBytea</function>, |
3009 |
| - <function>PQunescapeBytea</function>, |
3010 |
| - and <function>PQnotifies</function>. |
3011 |
| - It is particularly important that this function, rather than |
3012 |
| - <function>free()</>, be used on Microsoft Windows. This is because |
3013 |
| - allocating memory in a DLL and releasing it in the application works |
3014 |
| - only if multithreaded/single-threaded, release/debug, and static/dynamic |
3015 |
| - flags are the same for the DLL and the application. On non-Microsoft |
3016 |
| - Windows platforms, this function is the same as the standard library |
3017 |
| - function <function>free()</>. |
3018 |
| - </para> |
3019 |
| - </listitem> |
3020 |
| - </varlistentry> |
3021 | 3033 | </variablelist>
|
3022 | 3034 |
|
3023 | 3035 | </sect2>
|
@@ -4537,6 +4549,63 @@ char *pg_encoding_to_char(int <replaceable>encoding_id</replaceable>);
|
4537 | 4549 | </para>
|
4538 | 4550 |
|
4539 | 4551 | <variablelist>
|
| 4552 | + <varlistentry> |
| 4553 | + <term> |
| 4554 | + <function>PQfreemem</function> |
| 4555 | + <indexterm> |
| 4556 | + <primary>PQfreemem</primary> |
| 4557 | + </indexterm> |
| 4558 | + </term> |
| 4559 | + |
| 4560 | + <listitem> |
| 4561 | + <para> |
| 4562 | + Frees memory allocated by <application>libpq</>. |
| 4563 | + <synopsis> |
| 4564 | + void PQfreemem(void *ptr); |
| 4565 | + </synopsis> |
| 4566 | + </para> |
| 4567 | + |
| 4568 | + <para> |
| 4569 | + Frees memory allocated by <application>libpq</>, particularly |
| 4570 | + <function>PQescapeByteaConn</function>, |
| 4571 | + <function>PQescapeBytea</function>, |
| 4572 | + <function>PQunescapeBytea</function>, |
| 4573 | + and <function>PQnotifies</function>. |
| 4574 | + It is particularly important that this function, rather than |
| 4575 | + <function>free()</>, be used on Microsoft Windows. This is because |
| 4576 | + allocating memory in a DLL and releasing it in the application works |
| 4577 | + only if multithreaded/single-threaded, release/debug, and static/dynamic |
| 4578 | + flags are the same for the DLL and the application. On non-Microsoft |
| 4579 | + Windows platforms, this function is the same as the standard library |
| 4580 | + function <function>free()</>. |
| 4581 | + </para> |
| 4582 | + </listitem> |
| 4583 | + </varlistentry> |
| 4584 | + |
| 4585 | + <varlistentry> |
| 4586 | + <term> |
| 4587 | + <function>PQconninfoFree</function> |
| 4588 | + <indexterm> |
| 4589 | + <primary>PQconninfoFree</primary> |
| 4590 | + </indexterm> |
| 4591 | + </term> |
| 4592 | + |
| 4593 | + <listitem> |
| 4594 | + <para> |
| 4595 | + Frees the data structures allocated by |
| 4596 | + <function>PQconndefaults</> or <function>PQconninfoParse</>. |
| 4597 | + <synopsis> |
| 4598 | + void PQconninfoFree(PQconninfoOption *connOptions); |
| 4599 | + </synopsis> |
| 4600 | + </para> |
| 4601 | + |
| 4602 | + <para> |
| 4603 | + A simple <function>PQfreemem</function> will not do for this, since |
| 4604 | + the array contains references to subsidiary strings. |
| 4605 | + </para> |
| 4606 | + </listitem> |
| 4607 | + </varlistentry> |
| 4608 | + |
4540 | 4609 | <varlistentry>
|
4541 | 4610 | <term>
|
4542 | 4611 | <function>PQencryptPassword</function>
|
|
0 commit comments