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.3 1996/07/23 03:35:14 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 headers or not */
 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     char *fieldSep;      /* field separator */
 137     char *tableOpt;      /* insert to HTML <table ...> */
 138     char *caption;       /* HTML <caption> */
 139     char **fieldName;    /* null terminated array of repalcement field names */
 140 };
 141
 142 typedef struct _PQprintOpt PQprintOpt;
 143
 144 /* ===  in fe-connect.c === */
 145   /* make a new client connection to the backend */
 146 extern PGconn* PQsetdb(char* pghost, char* pgport, char* pgoptions,
 147                        char* pgtty, char* dbName);
 148   /* close the current connection and free the PGconn data structure */
 149 extern void PQfinish(PGconn* conn);
 150   /* close the current connection and restablish a new one with the same
 151      parameters */
 152 extern void PQreset(PGconn* conn);
 153
 154 extern char* PQdb(PGconn* conn);
 155 extern char* PQhost(PGconn* conn);
 156 extern char* PQoptions(PGconn* conn);
 157 extern char* PQport(PGconn* conn);
 158 extern char* PQtty(PGconn* conn);
 159 extern ConnStatusType PQstatus(PGconn* conn);
 160 extern char* PQerrorMessage(PGconn* conn);
 161 extern void PQtrace(PGconn *conn, FILE* debug_port);
 162 extern void PQuntrace(PGconn *conn);
 163
 164 /* === in fe-exec.c === */
 165 extern PGresult* PQexec(PGconn* conn, char* query);
 166 extern int PQgetline(PGconn *conn, char* string, int length);
 167 extern int PQendcopy(PGconn *conn);
 168 extern void PQputline(PGconn *conn, char* string);
 169 extern ExecStatusType PQresultStatus(PGresult* res);
 170 extern int PQntuples(PGresult *res);
 171 extern int PQnfields(PGresult *res);
 172 extern char* PQfname(PGresult *res, int field_num);
 173 extern int PQfnumber(PGresult *res, char* field_name);
 174 extern Oid PQftype(PGresult *res, int field_num);
 175 extern int2 PQfsize(PGresult *res, int field_num);
 176 extern char* PQcmdStatus(PGresult *res);
 177 extern char* PQoidStatus(PGresult *res);
 178 extern char* PQgetvalue(PGresult *res, int tup_num, int field_num);
 179 extern int PQgetlength(PGresult *res, int tup_num, int field_num);
 180 extern void PQclear(PGresult* res);
 181 /* PQdisplayTuples() is a better version of PQprintTuples() */
 182 extern void PQdisplayTuples(PGresult *res,
 183                             FILE *fp,      /* where to send the output */
 184                             int fillAlign, /* pad the fields with spaces */
 185                             char *fieldSep,  /* field separator */
 186                             int printHeader, /* display headers? */
 187                             int quiet);
 188 extern void PQprintTuples(PGresult* res,
 189                           FILE* fout,      /* output stream */
 190                           int printAttName,/* print attribute names or not*/
 191                           int terseOutput, /* delimiter bars or not?*/
 192                           int width        /* width of column,
 193                                               if 0, use variable width */
 194                           );
 195 extern void PQprint(FILE* fout,      /* output stream */
 196                     PGresult* res,
 197                     PQprintOpt *ps   /* option structure */
 198                     );
 199 extern PGnotify* PQnotifies(PGconn *conn);
 200 extern PGresult* PQfn(PGconn* conn,
 201                       int fnid,
 202                       int *result_buf,
 203                       int *result_len,
 204                       int result_is_int,
 205                       PQArgBlock *args,
 206                       int nargs);
 207 /* === in fe-auth.c === */
 208 extern MsgType fe_getauthsvc(char* PQerrormsg);
 209 extern void fe_setauthsvc(char *name, char* PQerrormsg);
 210 extern char *fe_getauthname(char* PQerrormsg);
 211
 212 /* === in fe-misc.c === */
 213 /* pqGets and pqPuts gets and sends strings to the file stream
 214    returns 0 if successful
 215    if debug is non-null, debugging output is sent to that stream
 216 */
 217 extern int pqGets(char* s, int maxlen, FILE* stream, FILE* debug);
 218 extern int pqGetnchar(char* s, int maxlen, FILE* stream, FILE* debug);
 219 extern int pqPutnchar(char* s, int maxlen, FILE* stream, FILE* debug);
 220 extern int pqPuts(char* s, FILE* stream, FILE* debug );
 221 extern int pqGetc(FILE* stream, FILE *debug);
 222 /* get a n-byte integer from the stream into result */
 223 /* returns 0 if successful */
 224 extern int pqGetInt(int* result, int bytes, FILE* stream, FILE *debug );
 225 /* put a n-byte integer into the stream */
 226 /* returns 0 if successful */
 227 extern int pqPutInt(int n, int bytes, FILE* stream, FILE *debug );
 228 extern void pqFlush(FILE* stream, FILE* debug);
 229
 230 /* === in fe-lobj.c === */
 231 int lo_open(PGconn* conn, Oid lobjId, int mode);
 232 int lo_close(PGconn *conn, int fd);
 233 int lo_read(PGconn *conn, int fd, char *buf, int len);
 234 int lo_write(PGconn *conn, int fd, char *buf, int len);
 235 int lo_lseek(PGconn *conn, int fd, int offset, int whence);
 236 Oid lo_creat(PGconn *conn, int mode);
 237 int lo_tell(PGconn *conn, int fd);
 238 int lo_unlink(PGconn *conn, Oid lobjId);
 239 Oid lo_import(PGconn *conn, char *filename);
 240 int lo_export(PGconn *conn, Oid lobjId, char *filename);
 241 /* max length of message to send  */
 242 #define MAX_MESSAGE_LEN 8193
 243
 244 /* maximum number of fields in a tuple */
 245 #define BYTELEN 8
 246 #define MAX_FIELDS 512
 247
 248 /* fall back options if they are not specified by arguments or defined
 249    by environment variables */
 250 #define DefaultHost     "localhost"
 251 #define DefaultTty      ""
 252 #define DefaultOption   ""
 253
 254 typedef void *TUPLE;
 255 #define palloc malloc
 256 #define pfree free
 257
 258 #if defined(PORTNAME_sparc)
 259 extern char *sys_errlist[];
 260 #define strerror(A) (sys_errlist[(A)])
 261 #endif /* PORTNAME_sparc */
 262
 263 #ifdef __cplusplus
 264 };
 265 #endif
 266
 267 #endif /* LIBPQ_FE_H */
 268