I686LINUX/util/I686LINUX/include/libpq-fe.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * libpq-fe.h
   4  *        This file contains definitions for structures and
   5  *        externs for functions used by frontend postgres applications.
   6  *
   7  * Portions Copyright (c) 1996-2003, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * $Id: libpq-fe.h,v 1.100 2003/08/27 00:33:34 petere Exp $
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14
  15 #ifndef LIBPQ_FE_H
  16 #define LIBPQ_FE_H
  17
  18 #ifdef __cplusplus
  19 extern          "C"
  20 {
  21 #endif
  22
  23 #include <stdio.h>
  24
  25 /*
  26  * postgres_ext.h defines the backend's externally visible types,
  27  * such as Oid.
  28  */
  29 #include "postgres_ext.h"
  30
  31 /* SSL type is needed here only to declare PQgetssl() */
  32 #ifdef USE_SSL
  33 #include <openssl/ssl.h>
  34 #endif
  35
  36 /* Application-visible enum types */
  37
  38 typedef enum
  39 {
  40         /*
  41          * Although it is okay to add to this list, values which become unused
  42          * should never be removed, nor should constants be redefined - that
  43          * would break compatibility with existing code.
  44          */
  45         CONNECTION_OK,
  46         CONNECTION_BAD,
  47         /* Non-blocking mode only below here */
  48
  49         /*
  50          * The existence of these should never be relied upon - they should
  51          * only be used for user feedback or similar purposes.
  52          */
  53         CONNECTION_STARTED,                     /* Waiting for connection to be made.  */
  54         CONNECTION_MADE,                        /* Connection OK; waiting to send.         */
  55         CONNECTION_AWAITING_RESPONSE,           /* Waiting for a response from the
  56                                                                                  * postmaster.            */
  57         CONNECTION_AUTH_OK,                     /* Received authentication; waiting for
  58                                                                  * backend startup. */
  59         CONNECTION_SETENV,                      /* Negotiating environment. */
  60         CONNECTION_SSL_STARTUP,         /* Negotiating SSL. */
  61         CONNECTION_NEEDED                       /* Internal state: connect() needed */
  62 } ConnStatusType;
  63
  64 typedef enum
  65 {
  66         PGRES_POLLING_FAILED = 0,
  67         PGRES_POLLING_READING,          /* These two indicate that one may        */
  68         PGRES_POLLING_WRITING,          /* use select before polling again.   */
  69         PGRES_POLLING_OK,
  70         PGRES_POLLING_ACTIVE            /* unused; keep for awhile for backwards
  71                                                                  * compatibility */
  72 } PostgresPollingStatusType;
  73
  74 typedef enum
  75 {
  76         PGRES_EMPTY_QUERY = 0,          /* empty query string was executed */
  77         PGRES_COMMAND_OK,                       /* a query command that doesn't return
  78                                                                  * anything was executed properly by the
  79                                                                  * backend */
  80         PGRES_TUPLES_OK,                        /* a query command that returns tuples was
  81                                                                  * executed properly by the backend,
  82                                                                  * PGresult contains the result tuples */
  83         PGRES_COPY_OUT,                         /* Copy Out data transfer in progress */
  84         PGRES_COPY_IN,                          /* Copy In data transfer in progress */
  85         PGRES_BAD_RESPONSE,                     /* an unexpected response was recv'd from
  86                                                                  * the backend */
  87         PGRES_NONFATAL_ERROR,           /* notice or warning message */
  88         PGRES_FATAL_ERROR                       /* query failed */
  89 } ExecStatusType;
  90
  91 typedef enum
  92 {
  93         PQTRANS_IDLE,                           /* connection idle */
  94         PQTRANS_ACTIVE,                         /* command in progress */
  95         PQTRANS_INTRANS,                        /* idle, within transaction block */
  96         PQTRANS_INERROR,                        /* idle, within failed transaction */
  97         PQTRANS_UNKNOWN                         /* cannot determine status */
  98 } PGTransactionStatusType;
  99
 100 typedef enum
 101 {
 102         PQERRORS_TERSE,                         /* single-line error messages */
 103         PQERRORS_DEFAULT,                       /* recommended style */
 104         PQERRORS_VERBOSE                        /* all the facts, ma'am */
 105 } PGVerbosity;
 106
 107 /* PGconn encapsulates a connection to the backend.
 108  * The contents of this struct are not supposed to be known to applications.
 109  */
 110 typedef struct pg_conn PGconn;
 111
 112 /* PGresult encapsulates the result of a query (or more precisely, of a single
 113  * SQL command --- a query string given to PQsendQuery can contain multiple
 114  * commands and thus return multiple PGresult objects).
 115  * The contents of this struct are not supposed to be known to applications.
 116  */
 117 typedef struct pg_result PGresult;
 118
 119 /* PGnotify represents the occurrence of a NOTIFY message.
 120  * Ideally this would be an opaque typedef, but it's so simple that it's
 121  * unlikely to change.
 122  * NOTE: in Postgres 6.4 and later, the be_pid is the notifying backend's,
 123  * whereas in earlier versions it was always your own backend's PID.
 124  */
 125 typedef struct pgNotify
 126 {
 127         char       *relname;            /* notification condition name */
 128         int                     be_pid;                 /* process ID of server process */
 129         char       *extra;                      /* notification parameter */
 130 } PGnotify;
 131
 132 /* Function types for notice-handling callbacks */
 133 typedef void (*PQnoticeReceiver) (void *arg, const PGresult *res);
 134 typedef void (*PQnoticeProcessor) (void *arg, const char *message);
 135
 136 /* Print options for PQprint() */
 137 typedef char pqbool;
 138
 139 typedef struct _PQprintOpt
 140 {
 141         pqbool          header;                 /* print output field headings and row
 142                                                                  * count */
 143         pqbool          align;                  /* fill align the fields */
 144         pqbool          standard;               /* old brain dead format */
 145         pqbool          html3;                  /* output html tables */
 146         pqbool          expanded;               /* expand tables */
 147         pqbool          pager;                  /* use pager for output if needed */
 148         char       *fieldSep;           /* field separator */
 149         char       *tableOpt;           /* insert to HTML <table ...> */
 150         char       *caption;            /* HTML <caption> */
 151         char      **fieldName;          /* null terminated array of repalcement
 152                                                                  * field names */
 153 } PQprintOpt;
 154
 155 /* ----------------
 156  * Structure for the conninfo parameter definitions returned by PQconndefaults
 157  *
 158  * All fields except "val" point at static strings which must not be altered.
 159  * "val" is either NULL or a malloc'd current-value string.  PQconninfoFree()
 160  * will release both the val strings and the PQconninfoOption array itself.
 161  * ----------------
 162  */
 163 typedef struct _PQconninfoOption
 164 {
 165         char       *keyword;            /* The keyword of the option                    */
 166         char       *envvar;                     /* Fallback environment variable name   */
 167         char       *compiled;           /* Fallback compiled in default value   */
 168         char       *val;                        /* Option's current value, or NULL               */
 169         char       *label;                      /* Label for field in connect dialog    */
 170         char       *dispchar;           /* Character to display for this field in
 171                                                                  * a connect dialog. Values are: ""
 172                                                                  * Display entered value as is "*"
 173                                                                  * Password field - hide value "D"      Debug
 174                                                                  * option - don't show by default */
 175         int                     dispsize;               /* Field size in characters for dialog  */
 176 } PQconninfoOption;
 177
 178 /* ----------------
 179  * PQArgBlock -- structure for PQfn() arguments
 180  * ----------------
 181  */
 182 typedef struct
 183 {
 184         int                     len;
 185         int                     isint;
 186         union
 187         {
 188                 int                *ptr;                /* can't use void (dec compiler barfs)   */
 189                 int                     integer;
 190         }                       u;
 191 } PQArgBlock;
 192
 193 /* ----------------
 194  * Exported functions of libpq
 195  * ----------------
 196  */
 197
 198 /* ===  in fe-connect.c === */
 199
 200 /* make a new client connection to the backend */
 201 /* Asynchronous (non-blocking) */
 202 extern PGconn *PQconnectStart(const char *conninfo);
 203 extern PostgresPollingStatusType PQconnectPoll(PGconn *conn);
 204
 205 /* Synchronous (blocking) */
 206 extern PGconn *PQconnectdb(const char *conninfo);
 207 extern PGconn *PQsetdbLogin(const char *pghost, const char *pgport,
 208                          const char *pgoptions, const char *pgtty,
 209                          const char *dbName,
 210                          const char *login, const char *pwd);
 211
 212 #define PQsetdb(M_PGHOST,M_PGPORT,M_PGOPT,M_PGTTY,M_DBNAME)  \
 213         PQsetdbLogin(M_PGHOST, M_PGPORT, M_PGOPT, M_PGTTY, M_DBNAME, NULL, NULL)
 214
 215 /* close the current connection and free the PGconn data structure */
 216 extern void PQfinish(PGconn *conn);
 217
 218 /* get info about connection options known to PQconnectdb */
 219 extern PQconninfoOption *PQconndefaults(void);
 220
 221 /* free the data structure returned by PQconndefaults() */
 222 extern void PQconninfoFree(PQconninfoOption *connOptions);
 223
 224 /*
 225  * close the current connection and restablish a new one with the same
 226  * parameters
 227  */
 228 /* Asynchronous (non-blocking) */
 229 extern int      PQresetStart(PGconn *conn);
 230 extern PostgresPollingStatusType PQresetPoll(PGconn *conn);
 231
 232 /* Synchronous (blocking) */
 233 extern void PQreset(PGconn *conn);
 234
 235 /* issue a cancel request */
 236 extern int      PQrequestCancel(PGconn *conn);
 237
 238 /* Accessor functions for PGconn objects */
 239 extern char *PQdb(const PGconn *conn);
 240 extern char *PQuser(const PGconn *conn);
 241 extern char *PQpass(const PGconn *conn);
 242 extern char *PQhost(const PGconn *conn);
 243 extern char *PQport(const PGconn *conn);
 244 extern char *PQtty(const PGconn *conn);
 245 extern char *PQoptions(const PGconn *conn);
 246 extern ConnStatusType PQstatus(const PGconn *conn);
 247 extern PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
 248 extern const char *PQparameterStatus(const PGconn *conn,
 249                                   const char *paramName);
 250 extern int      PQprotocolVersion(const PGconn *conn);
 251 extern char *PQerrorMessage(const PGconn *conn);
 252 extern int      PQsocket(const PGconn *conn);
 253 extern int      PQbackendPID(const PGconn *conn);
 254 extern int      PQclientEncoding(const PGconn *conn);
 255 extern int      PQsetClientEncoding(PGconn *conn, const char *encoding);
 256
 257 #ifdef USE_SSL
 258 /* Get the SSL structure associated with a connection */
 259 extern SSL *PQgetssl(PGconn *conn);
 260 #endif
 261
 262 /* Set verbosity for PQerrorMessage and PQresultErrorMessage */
 263 extern PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
 264
 265 /* Enable/disable tracing */
 266 extern void PQtrace(PGconn *conn, FILE *debug_port);
 267 extern void PQuntrace(PGconn *conn);
 268
 269 /* Override default notice handling routines */
 270 extern PQnoticeReceiver PQsetNoticeReceiver(PGconn *conn,
 271                                         PQnoticeReceiver proc,
 272                                         void *arg);
 273 extern PQnoticeProcessor PQsetNoticeProcessor(PGconn *conn,
 274                                          PQnoticeProcessor proc,
 275                                          void *arg);
 276
 277 /* === in fe-exec.c === */
 278
 279 /* Simple synchronous query */
 280 extern PGresult *PQexec(PGconn *conn, const char *query);
 281 extern PGresult *PQexecParams(PGconn *conn,
 282                          const char *command,
 283                          int nParams,
 284                          const Oid *paramTypes,
 285                          const char *const * paramValues,
 286                          const int *paramLengths,
 287                          const int *paramFormats,
 288                          int resultFormat);
 289 extern PGresult *PQexecPrepared(PGconn *conn,
 290                          const char *stmtName,
 291                          int nParams,
 292                          const char *const * paramValues,
 293                          const int *paramLengths,
 294                          const int *paramFormats,
 295                          int resultFormat);
 296
 297 /* Interface for multiple-result or asynchronous queries */
 298 extern int      PQsendQuery(PGconn *conn, const char *query);
 299 extern int PQsendQueryParams(PGconn *conn,
 300                                   const char *command,
 301                                   int nParams,
 302                                   const Oid *paramTypes,
 303                                   const char *const * paramValues,
 304                                   const int *paramLengths,
 305                                   const int *paramFormats,
 306                                   int resultFormat);
 307 extern int PQsendQueryPrepared(PGconn *conn,
 308                                   const char *stmtName,
 309                                   int nParams,
 310                                   const char *const * paramValues,
 311                                   const int *paramLengths,
 312                                   const int *paramFormats,
 313                                   int resultFormat);
 314 extern PGresult *PQgetResult(PGconn *conn);
 315
 316 /* Routines for managing an asynchronous query */
 317 extern int      PQisBusy(PGconn *conn);
 318 extern int      PQconsumeInput(PGconn *conn);
 319
 320 /* LISTEN/NOTIFY support */
 321 extern PGnotify *PQnotifies(PGconn *conn);
 322
 323 /* Routines for copy in/out */
 324 extern int      PQputCopyData(PGconn *conn, const char *buffer, int nbytes);
 325 extern int      PQputCopyEnd(PGconn *conn, const char *errormsg);
 326 extern int      PQgetCopyData(PGconn *conn, char **buffer, int async);
 327
 328 /* Deprecated routines for copy in/out */
 329 extern int      PQgetline(PGconn *conn, char *string, int length);
 330 extern int      PQputline(PGconn *conn, const char *string);
 331 extern int      PQgetlineAsync(PGconn *conn, char *buffer, int bufsize);
 332 extern int      PQputnbytes(PGconn *conn, const char *buffer, int nbytes);
 333 extern int      PQendcopy(PGconn *conn);
 334
 335 /* Set blocking/nonblocking connection to the backend */
 336 extern int      PQsetnonblocking(PGconn *conn, int arg);
 337 extern int      PQisnonblocking(const PGconn *conn);
 338
 339 /* Force the write buffer to be written (or at least try) */
 340 extern int      PQflush(PGconn *conn);
 341
 342 /*
 343  * "Fast path" interface --- not really recommended for application
 344  * use
 345  */
 346 extern PGresult *PQfn(PGconn *conn,
 347          int fnid,
 348          int *result_buf,
 349          int *result_len,
 350          int result_is_int,
 351          const PQArgBlock *args,
 352          int nargs);
 353
 354 /* Accessor functions for PGresult objects */
 355 extern ExecStatusType PQresultStatus(const PGresult *res);
 356 extern char *PQresStatus(ExecStatusType status);
 357 extern char *PQresultErrorMessage(const PGresult *res);
 358 extern char *PQresultErrorField(const PGresult *res, int fieldcode);
 359 extern int      PQntuples(const PGresult *res);
 360 extern int      PQnfields(const PGresult *res);
 361 extern int      PQbinaryTuples(const PGresult *res);
 362 extern char *PQfname(const PGresult *res, int field_num);
 363 extern int      PQfnumber(const PGresult *res, const char *field_name);
 364 extern Oid      PQftable(const PGresult *res, int field_num);
 365 extern int      PQftablecol(const PGresult *res, int field_num);
 366 extern int      PQfformat(const PGresult *res, int field_num);
 367 extern Oid      PQftype(const PGresult *res, int field_num);
 368 extern int      PQfsize(const PGresult *res, int field_num);
 369 extern int      PQfmod(const PGresult *res, int field_num);
 370 extern char *PQcmdStatus(PGresult *res);
 371 extern char *PQoidStatus(const PGresult *res);  /* old and ugly */
 372 extern Oid      PQoidValue(const PGresult *res);        /* new and improved */
 373 extern char *PQcmdTuples(PGresult *res);
 374 extern char *PQgetvalue(const PGresult *res, int tup_num, int field_num);
 375 extern int      PQgetlength(const PGresult *res, int tup_num, int field_num);
 376 extern int      PQgetisnull(const PGresult *res, int tup_num, int field_num);
 377
 378 /* Delete a PGresult */
 379 extern void PQclear(PGresult *res);
 380
 381 /* For freeing other alloc'd results, such as PGnotify structs */
 382 extern void PQfreemem(void *ptr);
 383
 384 /* Exists for backward compatibility.  bjm 2003-03-24 */
 385 #define PQfreeNotify(ptr) PQfreemem(ptr)
 386
 387 /*
 388  * Make an empty PGresult with given status (some apps find this
 389  * useful). If conn is not NULL and status indicates an error, the
 390  * conn's errorMessage is copied.
 391  */
 392 extern PGresult *PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
 393
 394
 395 /* Quoting strings before inclusion in queries. */
 396 extern size_t PQescapeString(char *to, const char *from, size_t length);
 397 extern unsigned char *PQescapeBytea(const unsigned char *bintext, size_t binlen,
 398                           size_t *bytealen);
 399 extern unsigned char *PQunescapeBytea(const unsigned char *strtext,
 400                                 size_t *retbuflen);
 401
 402
 403
 404 /* === in fe-print.c === */
 405
 406 extern void
 407 PQprint(FILE *fout,                             /* output stream */
 408                 const PGresult *res,
 409                 const PQprintOpt *ps);  /* option structure */
 410
 411 /*
 412  * really old printing routines
 413  */
 414 extern void
 415 PQdisplayTuples(const PGresult *res,
 416                                 FILE *fp,               /* where to send the output */
 417                                 int fillAlign,  /* pad the fields with spaces */
 418                                 const char *fieldSep,   /* field separator */
 419                                 int printHeader,        /* display headers? */
 420                                 int quiet);
 421
 422 extern void
 423 PQprintTuples(const PGresult *res,
 424                           FILE *fout,           /* output stream */
 425                           int printAttName, /* print attribute names */
 426                           int terseOutput,      /* delimiter bars */
 427                           int width);           /* width of column, if 0, use variable
 428                                                                  * width */
 429
 430
 431 /* === in fe-lobj.c === */
 432
 433 /* Large-object access routines */
 434 extern int      lo_open(PGconn *conn, Oid lobjId, int mode);
 435 extern int      lo_close(PGconn *conn, int fd);
 436 extern int      lo_read(PGconn *conn, int fd, char *buf, size_t len);
 437 extern int      lo_write(PGconn *conn, int fd, char *buf, size_t len);
 438 extern int      lo_lseek(PGconn *conn, int fd, int offset, int whence);
 439 extern Oid      lo_creat(PGconn *conn, int mode);
 440 extern int      lo_tell(PGconn *conn, int fd);
 441 extern int      lo_unlink(PGconn *conn, Oid lobjId);
 442 extern Oid      lo_import(PGconn *conn, const char *filename);
 443 extern int      lo_export(PGconn *conn, Oid lobjId, const char *filename);
 444
 445 /* === in fe-misc.c === */
 446
 447 /* Determine length of multibyte encoded char at *s */
 448 extern int      PQmblen(const unsigned char *s, int encoding);
 449
 450 /* Get encoding id from environment variable PGCLIENTENCODING */
 451 extern int      PQenv2encoding(void);
 452
 453 #ifdef __cplusplus
 454 }
 455 #endif
 456
 457 #endif   /* LIBPQ_FE_H */