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.5 1996/07/31 18:40:12 scrappy Exp $
  10  *
  11  *-------------------------------------------------------------------------
  12  */
  13
  14 #ifndef LIBPQ_FE_H
  15 #define LIBPQ_FE_H
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 /* ----------------
  22  *      include stuff common to fe and be
  23  * ----------------
  24  */
  25 /* #include "libpq/libpq.h" */
  26 #include "libpq/pqcomm.h"
  27 #include "lib/dllist.h"
  28
  29 typedef enum {CONNECTION_OK,
  30               CONNECTION_BAD}  ConnStatusType;
  31
  32 typedef enum {
  33   PGRES_EMPTY_QUERY = 0,
  34   PGRES_COMMAND_OK,  /* a query command that doesn't return */
  35                     /* anything was executed properly by the backend */
  36   PGRES_TUPLES_OK,  /* a query command that returns tuples */
  37                    /* was executed properly by the backend, PGresult */
  38                    /* contains the resulttuples */
  39   PGRES_COPY_OUT,
  40   PGRES_COPY_IN,
  41   PGRES_BAD_RESPONSE, /* an unexpected response was recv'd from the backend */
  42   PGRES_NONFATAL_ERROR,
  43   PGRES_FATAL_ERROR
  44
  45 } ExecStatusType;
  46
  47 /* string descriptions of the ExecStatusTypes */
  48 extern char* pgresStatus[];
  49
  50 /*
  51  * POSTGRES backend dependent Constants.
  52  */
  53
  54 /* ERROR_MSG_LENGTH should really be the same as ELOG_MAXLEN in utils/elog.h*/
  55 #define ERROR_MSG_LENGTH 4096
  56 #define COMMAND_LENGTH 20
  57 #define REMARK_LENGTH 80
  58 #define PORTAL_NAME_LENGTH 16
  59
  60 /* ----------------
  61  * PQArgBlock --
  62  *      Information (pointer to array of this structure) required
  63  *      for the PQfn() call.
  64  * ----------------
  65  */
  66 typedef struct {
  67     int len;
  68     int isint;
  69     union {
  70         int *ptr;       /* can't use void (dec compiler barfs)  */
  71         int integer;
  72     } u;
  73 } PQArgBlock;
  74
  75 typedef struct pgresAttDesc {
  76   char* name; /* type name */
  77   Oid adtid;  /* type id */
  78   int2 adtsize; /* type size */
  79 } PGresAttDesc;
  80
  81 /* use char* for Attribute values,
  82    ASCII tuples are guaranteed to be null-terminated
  83    For binary tuples, the first four bytes of the value is the size,
  84    and the bytes afterwards are the value.  The binary value is
  85    not guaranteed to be null-terminated.  In fact, it can have embedded nulls*/
  86 typedef struct pgresAttValue {
  87   int len; /* length in bytes of the value */
  88   char *value; /* actual value */
  89 } PGresAttValue;
  90
  91 typedef struct pgNotify {
  92     char relname[NAMEDATALEN];  /* name of relation containing data */
  93     int be_pid;                 /* process id of backend */
  94 } PGnotify;
  95
  96 /* PGconn encapsulates a connection to the backend */
  97 typedef struct pg_conn{
  98   char *pghost; /* the machine on which the server is running */
  99   char *pgtty;  /* tty on which the backend messages is displayed */
 100   char *pgport; /* the communication port with the backend */
 101   char *pgoptions; /* options to start the backend with */
 102   char *dbName; /* database name */
 103   ConnStatusType status;
 104   char errorMessage[ERROR_MSG_LENGTH];
 105   /* pipes for be/fe communication */
 106   FILE *Pfin;
 107   FILE *Pfout;
 108   FILE *Pfdebug;
 109   void *port; /* really a Port* */
 110   int asyncNotifyWaiting;
 111   Dllist* notifyList;
 112 } PGconn;
 113
 114 #define CMDSTATUS_LEN 40
 115
 116 /* PGresult encapsulates the result of a query */
 117 /* unlike the old libpq, we assume that queries only return in one group */
 118 typedef struct pg_result{
 119   int ntups;
 120   int numAttributes;
 121   PGresAttDesc *attDescs;
 122   PGresAttValue* *tuples; /* each PGresTuple is an array of PGresAttValue's */
 123   int tupArrSize;         /* size of tuples array allocated */
 124   ExecStatusType resultStatus;
 125   char cmdStatus[CMDSTATUS_LEN]; /* cmd status from the last insert query*/
 126   int binary; /* binary tuple values if binary == 1, otherwise ASCII */
 127   PGconn* conn;
 128 } PGresult;
 129
 130 struct _PQprintOpt {
 131     bool header;         /* print output field headings and row count */
 132     bool align;          /* fill align the fields */
 133     bool standard;       /* old brain dead format */
 134     bool html3;          /* output html tables */
 135     bool expanded;       /* expand tables */
 136     bool pager;          /* use pager for output if needed */
 137     char *fieldSep;      /* field separator */
 138     char *tableOpt;      /* insert to HTML <table ...> */
 139     char *caption;       /* HTML <caption> */
 140     char **fieldName;    /* null terminated array of repalcement field names */
 141 };
 142
 143 typedef struct _PQprintOpt PQprintOpt;
 144
 145 /* ===  in fe-connect.c === */
 146   /* make a new client connection to the backend */
 147 extern PGconn* PQsetdb(char* pghost, char* pgport, char* pgoptions,
 148                        char* pgtty, char* dbName);
 149   /* close the current connection and free the PGconn data structure */
 150 extern void PQfinish(PGconn* conn);
 151   /* close the current connection and restablish a new one with the same
 152      parameters */
 153 extern void PQreset(PGconn* conn);
 154
 155 extern char* PQdb(PGconn* conn);
 156 extern char* PQhost(PGconn* conn);
 157 extern char* PQoptions(PGconn* conn);
 158 extern char* PQport(PGconn* conn);
 159 extern char* PQtty(PGconn* conn);
 160 extern ConnStatusType PQstatus(PGconn* conn);
 161 extern char* PQerrorMessage(PGconn* conn);
 162 extern void PQtrace(PGconn *conn, FILE* debug_port);
 163 extern void PQuntrace(PGconn *conn);
 164
 165 /* === in fe-exec.c === */
 166 extern PGresult* PQexec(PGconn* conn, char* query);
 167 extern int PQgetline(PGconn *conn, char* string, int length);
 168 extern int PQendcopy(PGconn *conn);
 169 extern void PQputline(PGconn *conn, char* string);
 170 extern ExecStatusType PQresultStatus(PGresult* res);
 171 extern int PQntuples(PGresult *res);
 172 extern int PQnfields(PGresult *res);
 173 extern char* PQfname(PGresult *res, int field_num);
 174 extern int PQfnumber(PGresult *res, char* field_name);
 175 extern Oid PQftype(PGresult *res, int field_num);
 176 extern int2 PQfsize(PGresult *res, int field_num);
 177 extern char* PQcmdStatus(PGresult *res);
 178 extern char* PQoidStatus(PGresult *res);
 179 extern char* PQgetvalue(PGresult *res, int tup_num, int field_num);
 180 extern int PQgetlength(PGresult *res, int tup_num, int field_num);
 181 extern void PQclear(PGresult* res);
 182 /* PQdisplayTuples() is a better version of PQprintTuples() */
 183 extern void PQdisplayTuples(PGresult *res,
 184                             FILE *fp,      /* where to send the output */
 185                             int fillAlign, /* pad the fields with spaces */
 186                             char *fieldSep,  /* field separator */
 187                             int printHeader, /* display headers? */
 188                             int quiet);
 189 extern void PQprintTuples(PGresult* res,
 190                           FILE* fout,      /* output stream */
 191                           int printAttName,/* print attribute names or not*/
 192                           int terseOutput, /* delimiter bars or not?*/
 193                           int width        /* width of column,
 194                                               if 0, use variable width */
 195                           );
 196 extern void PQprint(FILE* fout,      /* output stream */
 197                     PGresult* res,
 198                     PQprintOpt *ps   /* option structure */
 199                     );
 200 extern PGnotify* PQnotifies(PGconn *conn);
 201 extern PGresult* PQfn(PGconn* conn,
 202                       int fnid,
 203                       int *result_buf,
 204                       int *result_len,
 205                       int result_is_int,
 206                       PQArgBlock *args,
 207                       int nargs);
 208 /* === in fe-auth.c === */
 209 extern MsgType fe_getauthsvc(char* PQerrormsg);
 210 extern void fe_setauthsvc(char *name, char* PQerrormsg);
 211 extern char *fe_getauthname(char* PQerrormsg);
 212
 213 /* === in fe-misc.c === */
 214 /* pqGets and pqPuts gets and sends strings to the file stream
 215    returns 0 if successful
 216    if debug is non-null, debugging output is sent to that stream
 217 */
 218 extern int pqGets(char* s, int maxlen, FILE* stream, FILE* debug);
 219 extern int pqGetnchar(char* s, int maxlen, FILE* stream, FILE* debug);
 220 extern int pqPutnchar(char* s, int maxlen, FILE* stream, FILE* debug);
 221 extern int pqPuts(char* s, FILE* stream, FILE* debug );
 222 extern int pqGetc(FILE* stream, FILE *debug);
 223 /* get a n-byte integer from the stream into result */
 224 /* returns 0 if successful */
 225 extern int pqGetInt(int* result, int bytes, FILE* stream, FILE *debug );
 226 /* put a n-byte integer into the stream */
 227 /* returns 0 if successful */
 228 extern int pqPutInt(int n, int bytes, FILE* stream, FILE *debug );
 229 extern void pqFlush(FILE* stream, FILE* debug);
 230
 231 /* === in fe-lobj.c === */
 232 int lo_open(PGconn* conn, Oid lobjId, int mode);
 233 int lo_close(PGconn *conn, int fd);
 234 int lo_read(PGconn *conn, int fd, char *buf, int len);
 235 int lo_write(PGconn *conn, int fd, char *buf, int len);
 236 int lo_lseek(PGconn *conn, int fd, int offset, int whence);
 237 Oid lo_creat(PGconn *conn, int mode);
 238 int lo_tell(PGconn *conn, int fd);
 239 int lo_unlink(PGconn *conn, Oid lobjId);
 240 Oid lo_import(PGconn *conn, char *filename);
 241 int lo_export(PGconn *conn, Oid lobjId, char *filename);
 242 /* max length of message to send  */
 243 #define MAX_MESSAGE_LEN 8193
 244
 245 /* maximum number of fields in a tuple */
 246 #define BYTELEN 8
 247 #define MAX_FIELDS 512
 248
 249 /* fall back options if they are not specified by arguments or defined
 250    by environment variables */
 251 #define DefaultHost     "localhost"
 252 #define DefaultTty      ""
 253 #define DefaultOption   ""
 254
 255 typedef void *TUPLE;
 256 #define palloc malloc
 257 #define pfree free
 258
 259 #if defined(PORTNAME_sparc)
 260 extern char *sys_errlist[];
 261 #define strerror(A) (sys_errlist[(A)])
 262 #endif /* PORTNAME_sparc */
 263
 264 #ifdef __cplusplus
 265 };
 266 #endif
 267
 268 #endif /* LIBPQ_FE_H */
 269