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.7 1996/08/13 01:34:29 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 const 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
  87 #define NULL_LEN        (-1)    /* pg_result len for NULL value */
  88
  89 typedef struct pgresAttValue {
  90   int len; /* length in bytes of the value */
  91   char *value; /* actual value */
  92 } PGresAttValue;
  93
  94 typedef struct pgNotify {
  95     char relname[NAMEDATALEN];  /* name of relation containing data */
  96     int be_pid;                 /* process id of backend */
  97 } PGnotify;
  98
  99 /* PGconn encapsulates a connection to the backend */
 100 typedef struct pg_conn{
 101   char *pghost; /* the machine on which the server is running */
 102   char *pgtty;  /* tty on which the backend messages is displayed */
 103   char *pgport; /* the communication port with the backend */
 104   char *pgoptions; /* options to start the backend with */
 105   char *dbName; /* database name */
 106   ConnStatusType status;
 107   char errorMessage[ERROR_MSG_LENGTH];
 108   /* pipes for be/fe communication */
 109   FILE *Pfin;
 110   FILE *Pfout;
 111   FILE *Pfdebug;
 112   void *port; /* really a Port* */
 113   int asyncNotifyWaiting;
 114   Dllist* notifyList;
 115 } PGconn;
 116
 117 #define CMDSTATUS_LEN 40
 118
 119 /* PGresult encapsulates the result of a query */
 120 /* unlike the old libpq, we assume that queries only return in one group */
 121 typedef struct pg_result{
 122   int ntups;
 123   int numAttributes;
 124   PGresAttDesc *attDescs;
 125   PGresAttValue* *tuples; /* each PGresTuple is an array of PGresAttValue's */
 126   int tupArrSize;         /* size of tuples array allocated */
 127   ExecStatusType resultStatus;
 128   char cmdStatus[CMDSTATUS_LEN]; /* cmd status from the last insert query*/
 129   int binary; /* binary tuple values if binary == 1, otherwise ASCII */
 130   PGconn* conn;
 131 } PGresult;
 132
 133 struct _PQprintOpt {
 134     bool header;         /* print output field headings and row count */
 135     bool align;          /* fill align the fields */
 136     bool standard;       /* old brain dead format */
 137     bool html3;          /* output html tables */
 138     bool expanded;       /* expand tables */
 139     bool pager;          /* use pager for output if needed */
 140     char *fieldSep;      /* field separator */
 141     char *tableOpt;      /* insert to HTML <table ...> */
 142     char *caption;       /* HTML <caption> */
 143     char **fieldName;    /* null terminated array of repalcement field names */
 144 };
 145
 146 typedef struct _PQprintOpt PQprintOpt;
 147
 148 /* ===  in fe-connect.c === */
 149   /* make a new client connection to the backend */
 150 extern PGconn* PQsetdb(const char* pghost, const char* pgport, const char* pgoptions,
 151                        const char* pgtty, const char* dbName);
 152   /* close the current connection and free the PGconn data structure */
 153 extern void PQfinish(PGconn* conn);
 154   /* close the current connection and restablish a new one with the same
 155      parameters */
 156 extern void PQreset(PGconn* conn);
 157
 158 extern char* PQdb(PGconn* conn);
 159 extern char* PQhost(PGconn* conn);
 160 extern char* PQoptions(PGconn* conn);
 161 extern char* PQport(PGconn* conn);
 162 extern char* PQtty(PGconn* conn);
 163 extern ConnStatusType PQstatus(PGconn* conn);
 164 extern char* PQerrorMessage(PGconn* conn);
 165 extern void PQtrace(PGconn *conn, FILE* debug_port);
 166 extern void PQuntrace(PGconn *conn);
 167
 168 /* === in fe-exec.c === */
 169 extern PGresult* PQexec(PGconn* conn, const char* query);
 170 extern int PQgetline(PGconn *conn, char* string, int length);
 171 extern int PQendcopy(PGconn *conn);
 172 extern void PQputline(PGconn *conn, const char* string);
 173 extern ExecStatusType PQresultStatus(PGresult* res);
 174 extern int PQntuples(PGresult *res);
 175 extern int PQnfields(PGresult *res);
 176 extern char* PQfname(PGresult *res, int field_num);
 177 extern int PQfnumber(PGresult *res, const char* field_name);
 178 extern Oid PQftype(PGresult *res, int field_num);
 179 extern int2 PQfsize(PGresult *res, int field_num);
 180 extern char* PQcmdStatus(PGresult *res);
 181 extern const char* PQoidStatus(PGresult *res);
 182 extern char* PQgetvalue(PGresult *res, int tup_num, int field_num);
 183 extern int PQgetlength(PGresult *res, int tup_num, int field_num);
 184 extern int PQgetisnull(PGresult *res, int tup_num, int field_num);
 185 extern void PQclear(PGresult* res);
 186 /* PQdisplayTuples() is a better version of PQprintTuples() */
 187 extern void PQdisplayTuples(PGresult *res,
 188                             FILE *fp,      /* where to send the output */
 189                             int fillAlign, /* pad the fields with spaces */
 190                             const char *fieldSep,  /* field separator */
 191                             int printHeader, /* display headers? */
 192                             int quiet);
 193 extern void PQprintTuples(PGresult* res,
 194                           FILE* fout,      /* output stream */
 195                           int printAttName,/* print attribute names or not*/
 196                           int terseOutput, /* delimiter bars or not?*/
 197                           int width        /* width of column,
 198                                               if 0, use variable width */
 199                           );
 200 extern void PQprint(FILE* fout,      /* output stream */
 201                     PGresult* res,
 202                     PQprintOpt *ps   /* option structure */
 203                     );
 204 extern PGnotify* PQnotifies(PGconn *conn);
 205 extern PGresult* PQfn(PGconn* conn,
 206                       int fnid,
 207                       int *result_buf,
 208                       int *result_len,
 209                       int result_is_int,
 210                       PQArgBlock *args,
 211                       int nargs);
 212 /* === in fe-auth.c === */
 213 extern MsgType fe_getauthsvc(char* PQerrormsg);
 214 extern void fe_setauthsvc(const char *name, char* PQerrormsg);
 215 extern char *fe_getauthname(char* PQerrormsg);
 216
 217 /* === in fe-misc.c === */
 218 /* pqGets and pqPuts gets and sends strings to the file stream
 219    returns 0 if successful
 220    if debug is non-null, debugging output is sent to that stream
 221 */
 222 extern int pqGets(char* s, int maxlen, FILE* stream, FILE* debug);
 223 extern int pqGetnchar(char* s, int maxlen, FILE* stream, FILE* debug);
 224 extern int pqPutnchar(const char* s, int maxlen, FILE* stream, FILE* debug);
 225 extern int pqPuts(const char* s, FILE* stream, FILE* debug );
 226 extern int pqGetc(FILE* stream, FILE *debug);
 227 /* get a n-byte integer from the stream into result */
 228 /* returns 0 if successful */
 229 extern int pqGetInt(int* result, int bytes, FILE* stream, FILE *debug );
 230 /* put a n-byte integer into the stream */
 231 /* returns 0 if successful */
 232 extern int pqPutInt(int n, int bytes, FILE* stream, FILE *debug );
 233 extern void pqFlush(FILE* stream, FILE* debug);
 234
 235 /* === in fe-lobj.c === */
 236 int lo_open(PGconn* conn, Oid lobjId, int mode);
 237 int lo_close(PGconn *conn, int fd);
 238 int lo_read(PGconn *conn, int fd, char *buf, int len);
 239 int lo_write(PGconn *conn, int fd, char *buf, int len);
 240 int lo_lseek(PGconn *conn, int fd, int offset, int whence);
 241 Oid lo_creat(PGconn *conn, int mode);
 242 int lo_tell(PGconn *conn, int fd);
 243 int lo_unlink(PGconn *conn, Oid lobjId);
 244 Oid lo_import(PGconn *conn, char *filename);
 245 int lo_export(PGconn *conn, Oid lobjId, char *filename);
 246 /* max length of message to send  */
 247 #define MAX_MESSAGE_LEN 8193
 248
 249 /* maximum number of fields in a tuple */
 250 #define BYTELEN 8
 251 #define MAX_FIELDS 512
 252
 253 /* fall back options if they are not specified by arguments or defined
 254    by environment variables */
 255 #define DefaultHost     "localhost"
 256 #define DefaultTty      ""
 257 #define DefaultOption   ""
 258
 259 typedef void *TUPLE;
 260 #define palloc malloc
 261 #define pfree free
 262
 263 #if defined(PORTNAME_sparc)
 264 extern char *sys_errlist[];
 265 #define strerror(A) (sys_errlist[(A)])
 266 #endif /* PORTNAME_sparc */
 267
 268 #ifdef __cplusplus
 269 };
 270 #endif
 271
 272 #endif /* LIBPQ_FE_H */
 273