granicus.if.org Git - postgresql/blob - src/interfaces/libpq/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  * Copyright (c) 1994, Regents of the University of California
   8  *
   9  * $Id: libpq-fe.h,v 1.25 1998/01/26 01:42:37 scrappy Exp $
  10  *
  11  *-------------------------------------------------------------------------
  12  */
  13
  14 #ifndef LIBPQ_FE_H
  15 #define LIBPQ_FE_H
  16
  17 #ifdef __cplusplus
  18 extern          "C"
  19 {
  20 #endif
  21
  22 #include <stdio.h>
  23 /* ----------------
  24  *              include stuff common to fe and be
  25  * ----------------
  26  */
  27 #include "postgres_ext.h"
  28 #include "libpq/pqcomm.h"
  29 #include "lib/dllist.h"
  30
  31         typedef enum
  32         {
  33                 CONNECTION_OK,
  34                 CONNECTION_BAD
  35         } ConnStatusType;
  36
  37         typedef enum
  38         {
  39                 PGRES_EMPTY_QUERY = 0,
  40                 PGRES_COMMAND_OK,               /* a query command that doesn't return */
  41                 /* anything was executed properly by the backend */
  42                 PGRES_TUPLES_OK,                /* a query command that returns tuples */
  43                 /* was executed properly by the backend, PGresult */
  44                 /* contains the resulttuples */
  45                 PGRES_COPY_OUT,
  46                 PGRES_COPY_IN,
  47                 PGRES_BAD_RESPONSE,             /* an unexpected response was recv'd from
  48                                                                  * the backend */
  49                 PGRES_NONFATAL_ERROR,
  50                 PGRES_FATAL_ERROR
  51
  52         } ExecStatusType;
  53
  54 /* string descriptions of the ExecStatusTypes */
  55         extern const char *pgresStatus[];
  56
  57 /*
  58  * POSTGRES backend dependent Constants.
  59  */
  60
  61 /* ERROR_MSG_LENGTH should really be the same as ELOG_MAXLEN in utils/elog.h*/
  62 #define ERROR_MSG_LENGTH 4096
  63 #define COMMAND_LENGTH 20
  64 #define REMARK_LENGTH 80
  65 #define PORTAL_NAME_LENGTH 16
  66
  67 /* ----------------
  68  * PQArgBlock --
  69  *              Information (pointer to array of this structure) required
  70  *              for the PQfn() call.
  71  * ----------------
  72  */
  73         typedef struct
  74         {
  75                 int                     len;
  76                 int                     isint;
  77                 union
  78                 {
  79                         int                *ptr;        /* can't use void (dec compiler barfs)   */
  80                         int                     integer;
  81                 }                       u;
  82         } PQArgBlock;
  83
  84         typedef struct pgresAttDesc
  85         {
  86                 char       *name;               /* type name */
  87                 Oid                     adtid;          /* type id */
  88                 short           adtsize;        /* type size */
  89         } PGresAttDesc;
  90
  91 /* use char* for Attribute values,
  92    ASCII tuples are guaranteed to be null-terminated
  93    For binary tuples, the first four bytes of the value is the size,
  94    and the bytes afterwards are the value.      The binary value is
  95    not guaranteed to be null-terminated.  In fact, it can have embedded nulls*/
  96
  97 #define NULL_LEN                (-1)    /* pg_result len for NULL value */
  98
  99         typedef struct pgresAttValue
 100         {
 101                 int                     len;            /* length in bytes of the value */
 102                 char       *value;              /* actual value */
 103         } PGresAttValue;
 104
 105         typedef struct pgNotify
 106         {
 107                 char            relname[NAMEDATALEN];           /* name of relation
 108                                                                                                  * containing data */
 109                 int                     be_pid;         /* process id of backend */
 110         } PGnotify;
 111
 112         typedef struct pgLobjfuncs
 113         {
 114                 Oid                     fn_lo_open; /* OID of backend function lo_open          */
 115                 Oid                     fn_lo_close;/* OID of backend function lo_close         */
 116                 Oid                     fn_lo_creat;/* OID of backend function lo_creat         */
 117                 Oid                     fn_lo_unlink;           /* OID of backend function
 118                                                                                  * lo_unlink    */
 119                 Oid                     fn_lo_lseek;/* OID of backend function lo_lseek         */
 120                 Oid                     fn_lo_tell; /* OID of backend function lo_tell          */
 121                 Oid                     fn_lo_read; /* OID of backend function LOread           */
 122                 Oid                     fn_lo_write;/* OID of backend function LOwrite          */
 123         } PGlobjfuncs;
 124
 125 /* PGconn encapsulates a connection to the backend */
 126         typedef struct pg_conn
 127         {
 128                 char       *pghost;             /* the machine on which the server is
 129                                                                  * running */
 130                 char       *pgtty;              /* tty on which the backend messages is
 131                                                                  * displayed */
 132                 char       *pgport;             /* the communication port with the backend */
 133                 char       *pgoptions;  /* options to start the backend with */
 134                 char       *dbName;             /* database name */
 135                 ConnStatusType status;
 136                 char            errorMessage[ERROR_MSG_LENGTH];
 137                 /* pipes for be/fe communication */
 138                 FILE       *Pfin;
 139                 FILE       *Pfout;
 140                 FILE       *Pfdebug;
 141                 int                     sock;   /* The socket */
 142                 SockAddr                laddr;  /* Local address */
 143                 SockAddr                raddr;  /* Remote address */
 144                 char                    salt[2];
 145                 int                     asyncNotifyWaiting;
 146                 Dllist     *notifyList;
 147                 char       *pguser;             /* Postgres username of user who is
 148                                                                  * connected */
 149                 char       *pgpass;
 150                 PGlobjfuncs *lobjfuncs; /* Backend function OID's for large object
 151                                                                  * access */
 152         } PGconn;
 153
 154 #define CMDSTATUS_LEN 40
 155
 156 /* PGresult encapsulates the result of a query */
 157 /* unlike the old libpq, we assume that queries only return in one group */
 158         typedef struct pg_result
 159         {
 160                 int                     ntups;
 161                 int                     numAttributes;
 162                 PGresAttDesc *attDescs;
 163                 PGresAttValue **tuples; /* each PGresTuple is an array of
 164                                                                  * PGresAttValue's */
 165                 int                     tupArrSize; /* size of tuples array allocated */
 166                 ExecStatusType resultStatus;
 167                 char            cmdStatus[CMDSTATUS_LEN];       /* cmd status from the
 168                                                                                                  * last insert query */
 169                 int                     binary;         /* binary tuple values if binary == 1,
 170                                                                  * otherwise ASCII */
 171                 PGconn     *conn;
 172         } PGresult;
 173
 174         typedef char pqbool;
 175
 176         /*
 177          * We can't use the conventional "bool", because we are designed to be
 178          * included in a user's program, and user may already have that type
 179          * defined.  Pqbool, on the other hand, is unlikely to be used.
 180          */
 181
 182         struct _PQprintOpt
 183         {
 184                 pqbool          header;         /* print output field headings and row
 185                                                                  * count */
 186                 pqbool          align;          /* fill align the fields */
 187                 pqbool          standard;       /* old brain dead format */
 188                 pqbool          html3;          /* output html tables */
 189                 pqbool          expanded;       /* expand tables */
 190                 pqbool          pager;          /* use pager for output if needed */
 191                 char       *fieldSep;   /* field separator */
 192                 char       *tableOpt;   /* insert to HTML <table ...> */
 193                 char       *caption;    /* HTML <caption> */
 194                 char      **fieldName;  /* null terminated array of repalcement
 195                                                                  * field names */
 196         };
 197
 198         typedef struct _PQprintOpt PQprintOpt;
 199
 200 /* ----------------
 201  * Structure for the conninfo parameter definitions of PQconnectdb()
 202  * ----------------
 203  */
 204         struct _PQconninfoOption
 205         {
 206                 char       *keyword;    /* The keyword of the option                    */
 207                 char       *environ;    /* Fallback environment variable name   */
 208                 char       *compiled;   /* Fallback compiled in default value   */
 209                 char       *val;                /* Options value                                                */
 210                 char       *label;              /* Label for field in connect dialog    */
 211                 char       *dispchar;   /* Character to display for this field  */
 212                 /* in a connect dialog. Values are:             */
 213                 /* ""   Display entered value as is  */
 214                 /* "*"  Password field - hide value  */
 215                 /* "D"  Debug options - don't    */
 216                 /* create a field by default    */
 217                 int                     dispsize;       /* Field size in characters for dialog  */
 218         };
 219
 220         typedef struct _PQconninfoOption PQconninfoOption;
 221
 222 /* ===  in fe-connect.c === */
 223         /* make a new client connection to the backend */
 224         extern PGconn *PQconnectdb(const char *conninfo);
 225         extern PQconninfoOption *PQconndefaults(void);
 226         extern PGconn *PQsetdbLogin(const char *pghost, const char *pgport, const char *pgoptions,
 227                                           const char *pgtty, const char *dbName, const char *login, const char *pwd);
 228 #define PQsetdb(M_PGHOST,M_PGPORT,M_PGOPT,M_PGTTY,M_DBNAME)   PQsetdbLogin(M_PGHOST, M_PGPORT, M_PGOPT, M_PGTTY, M_DBNAME, NULL, NULL)
 229         /* close the current connection and free the PGconn data structure */
 230         extern void PQfinish(PGconn *conn);
 231
 232         /*
 233          * close the current connection and restablish a new one with the same
 234          * parameters
 235          */
 236         extern void PQreset(PGconn *conn);
 237
 238         extern char *PQdb(PGconn *conn);
 239         extern char *PQuser(PGconn *conn);
 240         extern char *PQhost(PGconn *conn);
 241         extern char *PQoptions(PGconn *conn);
 242         extern char *PQport(PGconn *conn);
 243         extern char *PQtty(PGconn *conn);
 244         extern ConnStatusType PQstatus(PGconn *conn);
 245         extern char *PQerrorMessage(PGconn *conn);
 246         extern void PQtrace(PGconn *conn, FILE *debug_port);
 247         extern void PQuntrace(PGconn *conn);
 248
 249 /* === in fe-exec.c === */
 250         extern PGresult *PQexec(PGconn *conn, const char *query);
 251         extern int      PQgetline(PGconn *conn, char *string, int length);
 252         extern int      PQendcopy(PGconn *conn);
 253         extern void PQputline(PGconn *conn, const char *string);
 254         extern ExecStatusType PQresultStatus(PGresult *res);
 255         extern int      PQntuples(PGresult *res);
 256         extern int      PQnfields(PGresult *res);
 257         extern char *PQfname(PGresult *res, int field_num);
 258         extern int      PQfnumber(PGresult *res, const char *field_name);
 259         extern Oid      PQftype(PGresult *res, int field_num);
 260         extern short PQfsize(PGresult *res, int field_num);
 261         extern char *PQcmdStatus(PGresult *res);
 262         extern const char *PQoidStatus(PGresult *res);
 263         extern const char *PQcmdTuples(PGresult *res);
 264         extern char *PQgetvalue(PGresult *res, int tup_num, int field_num);
 265         extern int      PQgetlength(PGresult *res, int tup_num, int field_num);
 266         extern int      PQgetisnull(PGresult *res, int tup_num, int field_num);
 267         extern void PQclear(PGresult *res);
 268 /* PQdisplayTuples() is a better version of PQprintTuples() */
 269         extern void PQdisplayTuples(PGresult *res,
 270                                                                                         FILE *fp,       /* where to send the
 271                                                                                                                  * output */
 272                                                                                         int fillAlign,          /* pad the fields with
 273                                                                                                                                  * spaces */
 274                                                                                         const char *fieldSep,           /* field separator */
 275                                                                                         int printHeader,        /* display headers? */
 276                                                                                         int quiet);
 277         extern void PQprintTuples(PGresult *res,
 278                                                                                   FILE *fout,   /* output stream */
 279                                                                                   int printAttName,             /* print attribute names
 280                                                                                                                                  * or not */
 281                                                                                   int terseOutput,              /* delimiter bars or
 282                                                                                                                                  * not? */
 283                                                                                   int width             /* width of column, if
 284                                                                                                                  * 0, use variable width */
 285         );
 286         extern void PQprint(FILE *fout,         /* output stream */
 287                                                                         PGresult *res,
 288                                                                         PQprintOpt *ps          /* option structure */
 289         );
 290         extern PGnotify *PQnotifies(PGconn *conn);
 291         extern PGresult *PQfn(PGconn *conn,
 292                                                                           int fnid,
 293                                                                           int *result_buf,
 294                                                                           int *result_len,
 295                                                                           int result_is_int,
 296                                                                           PQArgBlock *args,
 297                                                                           int nargs);
 298 /* === in fe-auth.c === */
 299         extern MsgType fe_getauthsvc(char *PQerrormsg);
 300         extern void fe_setauthsvc(const char *name, char *PQerrormsg);
 301         extern char *fe_getauthname(char *PQerrormsg);
 302
 303 /* === in fe-misc.c === */
 304 /* pqGets and pqPuts gets and sends strings to the file stream
 305    returns 0 if successful
 306    if debug is non-null, debugging output is sent to that stream
 307 */
 308         extern int      pqGets(char *s, int maxlen, FILE *stream, FILE *debug);
 309         extern int      pqGetnchar(char *s, int maxlen, FILE *stream, FILE *debug);
 310         extern int      pqPutnchar(const char *s, int maxlen, FILE *stream, FILE *debug);
 311         extern int      pqPuts(const char *s, FILE *stream, FILE *debug);
 312         extern int      pqGetc(FILE *stream, FILE *debug);
 313 /* get a n-byte integer from the stream into result */
 314 /* returns 0 if successful */
 315         extern int      pqGetInt(int *result, int bytes, FILE *stream, FILE *debug);
 316 /* put a n-byte integer into the stream */
 317 /* returns 0 if successful */
 318         extern int      pqPutInt(const int n, int bytes, FILE *stream, FILE *debug);
 319         extern void pqFlush(FILE *stream, FILE *debug);
 320
 321 /* === in fe-lobj.c === */
 322         int                     lo_open(PGconn *conn, Oid lobjId, int mode);
 323         int                     lo_close(PGconn *conn, int fd);
 324         int                     lo_read(PGconn *conn, int fd, char *buf, int len);
 325         int                     lo_write(PGconn *conn, int fd, char *buf, int len);
 326         int                     lo_lseek(PGconn *conn, int fd, int offset, int whence);
 327         Oid                     lo_creat(PGconn *conn, int mode);
 328         int                     lo_tell(PGconn *conn, int fd);
 329         int                     lo_unlink(PGconn *conn, Oid lobjId);
 330         Oid                     lo_import(PGconn *conn, char *filename);
 331         int                     lo_export(PGconn *conn, Oid lobjId, char *filename);
 332 /* max length of message to send  */
 333 #define MAX_MESSAGE_LEN 8193
 334
 335 /* maximum number of fields in a tuple */
 336 #define BYTELEN 8
 337 #define MAX_FIELDS 512
 338
 339 /* fall back options if they are not specified by arguments or defined
 340    by environment variables */
 341 #define DefaultHost             "localhost"
 342 #define DefaultTty              ""
 343 #define DefaultOption   ""
 344 #define DefaultAuthtype           ""
 345 #define DefaultPassword           ""
 346
 347
 348         typedef void *TUPLE;
 349 #define palloc malloc
 350 #define pfree free
 351
 352 #if defined(sunos4)
 353         extern char *sys_errlist[];
 354 #define strerror(A) (sys_errlist[(A)])
 355 #endif                                                  /* sunos4 */
 356
 357 #ifdef __cplusplus
 358 };
 359
 360 #endif
 361
 362 #endif                                                  /* LIBPQ_FE_H */