Type Specifier Name
A [schema].type name that will be used to reference your handler. `man pqt-specs´ for complete documentation on syntax.

Put Routine
A PGtypeProc put routine takes a C data type and converts it into a valid backend external format. The converted format is used with libpq's parameterized API. For instance: a C int data type is used to put a postgresql int4. To convert this to a valid external format, libpqtypes swaps the bytes (when needed) so they are in network order. A put routine returns the number of bytes being put. On error, a put routine must return -1.

Get Routine
A PGtypeProc get routine does the opposite of a put routine. It converts a type's text or binary external format to its native C type. For instance: a postgresql int4 is converted to a C int. For binary results, the 4 bytes are converted to host order and stored as a C int. A get routine returns zero to indicate success. On error, a get routine must return -1.

typedef struct
{
	const char *typname;
	PGtypeProc typput;
	PGtypeProc typget;
} PGregisterType;

typedef struct
{
	int sversion;          /* server version, e.g. 70401 for 7.4.1 */
	int pversion;          /* FE/BE protocol version in use */
	char datestyle[32];    /* server´s datestyle: like "SQL, MDY" */
	/* When non-zero, server uses int64 timestamps */
	int integer_datetimes;
} PGtypeFormatInfo;

typedef struct
{
	Oid attoid;    /* Oid of the attribute */
	int attlen;    /* storage size of attribute.  -1 if not known */
	int atttypmod; /* The typmod of attribute. */
	char *attname; /* The name of the attribute. */
} PGrecordAttDesc;

typedef struct pg_typhandler
{
	/* An internal libpqtypes assigned id for this type handler. */
	int id;
	/* The schema name of this type, which may be empty if not
	 * provided during registration.
	 */
	char typschema[65];
	/* The name of this type: like int2 or bytea, cannot be empty */
	char typname[65];
	/* The storage size of this type.  -1 if not known. */
	int typlen;
	/* The backend OID of the type. */
	Oid typoid;
	/* The backend array OID of the type. */
	Oid typoid_array;
	/* The put handler for this type. */
	PGtypeProc typput;
	/* The get handler for this type. */
	PGtypeProc typget;
	/* If this handler is a sub-class, this will be the ´id´ of
	 * the super class type handler.  It is set to -1 if not
	 * a sub-class.
	 */
	int base_id;
	/* Indicates the number of composite attributes within the
	 * ´attDescs´ array.  This is set to 0 for non-composites.
	 */
	int nattrs;
	/* If non-zero, the 'attDescs' pointer must be freed. */
	int freeAttDescs;
	/* The memory behind the 'attDescs' pointer when the number of 
	 * attrs is less than 16.  When greater than 16, heap memory
	 * is used and 'freeAttDescs' is set to a non-zero value.
	 */
	PGrecordAttDesc attDescsBuf[16];
	/* An array of PGrecordAttDesc, one element per record
	 * attribute.  Must be freed if 'freeAttDescs' is non-zero.
	 */
	PGrecordAttDesc *attDescs;
} PGtypeHandler;

struct pg_typeargs
{
	/* Indicates if this is a put or get operation. */
	int is_put;
	/* Formatting information. */
	const PGtypeFormatInfo *fmtinfo;
	/* Indicates if a request for a direct pointer was
	 * made, %text*.
	 */
	int is_ptr;
	/*
	 * When is_put is non-zero, set this to 1 for binary and 0 for
	 * text format.  It defaults to binary.  When is_put is 0, this
	 * indicates the field type PQftype of get.field_num.
	 */
	int format;
	/* An argument list.  Arguments should be retrieved with va_arg. */
	va_list ap;
	/* The position of this typname within a specifier
	 * string, 1-based.
	 */
	int typpos;
	/* Type handler for the specifier at typpos. */
	PGtypeHandler *typhandler;
	/*
	 * Report an error from within a handler.  This error message
	 * will show up in PQgeterror.
	 *
	 * This always returns -1 so one can report an error and return
	 * -1 from a handler in a single statement:
	 *
	 *   return args->errorf(args, "ERROR: %s", strerror(errno));
	 *
	 * errorf always prepends a small header
	 * "schema.typname[pos:num] - msg". For example, if the above
	 * failed within the int4 handler and typpos was 5, the
	 * resulting error message would be:
	 *
	 *   pg_catalog.int4[pos:5] - ERROR: Invalid argument
	 *
	 * errorf does not put any newlines in error message.
	 */
	int (*errorf)(PGtypeArgs *args, const char *format, ...);
	/* Used by type sub-class handlers.  When is_put is
	 * non-zero, a sub-class prepares type data and then calls
	 * super.  When is_put is zero, a sub-class first
	 * calls super to get the base class's deserialized value
	 * and can then convert it.
	 */
	int (*super)(PGtypeArgs *args, ...);
	/* This structure is used when is_put is non-zero. */
	struct
	{
		/* The PGparam structure passed to PQputf(). */
		PGparam *param;
		/* A buffer used to store the type's output format.  If
		 * more than 'outl' bytes are needed, see 'expandBuffer'.
		 * Normally data is copied to the out buffer, but it can
		 * also be pointed elsewhere: like a const string or static
		 * memory.  When repointing the out buffer, DO NOT use
		 * 'expandBuffer'.  Never use realloc on this buffer.
		 */
		char *out;
		/* The size in bytes of the 'out' buffer. If expandBuffer
		 * is used, this will reflect the new buffer length.
		 */
		int outl;
		/* Expands the 'out' buffer to 'new_len'.  If new_len is
		 * less than or equal to the current length 'outl', the
		 * expand request is ignored.  This behaves just like a
		 * realloc, existing data is copied to the new memory.
		 * You should never use realloc on the out buffer.
		 * Returns -1 on error and 0 for success.
		 */
		int (*expandBuffer)(PGtypeArgs *args, int new_len);
		/* internal use only. */
		char *__allocated_out;
	} put;
	/* This structure is used when is_put is zero. */
	struct
	{
		/* The PGresult passed to PQgetf().
		PGresult *result;
		/* The tuple number */
		int tup_num;
		/* the tuple field number. */
		int field_num;
	} get;
};

PGregisterType type = {"myint4=pg_catalog.int4", NULL, NULL};
PQregisterTypes(conn, PQT_SUBCLASS, &type, 1, 0);

/* we are going to register this under the ´pqt´ schema */
PGregisterType type = {"pqt.epoch=pg_catalog.timestamptz", epoch_put, epoch_get};
PQregisterTypes(conn, PQT_SUBCLASS, &type, 1, 0))
/* putting an epoch */
struct stat st;
if(stat("/home/foobar/archive.tgz", &st) == 0)
{
	PGparam *param = PQparamCreate(conn);
	PQputf(param, "%epoch", st.st_mtime);
	//....
}
/* getting an epoch value, using fully qualified type name */
struct utimbuf ut = {0, 0};
PQgetf(result, tup_num, "%pqt.epoch", field_num, &ut.modtime);
/* -------------------------------
 * EXAMPLE EPOCH SUB-CLASS IMPLEMENTATION
 */
/* convert a time_t to a PGtimestamp and call args->super() */
int epoch_put(PGtypeArgs *args)
{
	struct tm *tm;
	PGtimestamp ts;
	time_t t = va_arg(args->ap, time_t);
	tm = localtime(&t);
	ts.date.isbc   = 0;
	ts.date.year   = tm->tm_year + 1900; /* always 4-digit year */
	ts.date.mon    = tm->tm_mon;
	ts.date.mday   = tm->tm_mday;
	ts.time.hour   = tm->tm_hour;
	ts.time.min    = tm->tm_min;
	ts.time.sec    = tm->tm_sec;
	ts.time.usec   = 0;
	ts.time.gmtoff = tm->tm_gmtoff;
	/* Internally, this calls the base type´s put routine
	 * (the super class).  In this case, the super class
	 * expects a PGtimestamp as input.  The super function
	 * returns whatever the base type´s put routine returns
	 * (which for all puts is the byte count or -1 on error).
	 */
	return args->super(args, &ts);
}
/* Calls args->super() to get a PGtimestamp and then converts
 * it to a time_t value.
 */
int epoch_get(PGtypeArgs *args)
{
	PGtimestamp ts;
	time_t *t = va_arg(args->ap, time_t *);
	if(!t)
		return args->errorf(args, "time_t* cannot be NULL");
	/* zero user bits */
	*t = 0;
	/* Internally, this calls the base type´s get routine,
	 * which returns 0 or -1 on error.
	 */
	if(args->super(args, &ts) == -1)
		return -1; /* args->errorf called by super already */
	/* Since PGtimestamp contains an epoch member, we can
	 * just copy that value rather than calling mktime().
	 */
	*t = (time_t)ts.epoch;
	return 0;
}

CREATE TYPE simple AS (a int4, t text);
PGregisterType type = {"simple", NULL, NULL};
PQregisterTypes(conn, PQT_COMPOSITE, &type, 1, 0);