Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PQgetf(3)		       libpqtypes Manual		     PQgetf(3)

NAME
       PQgetf -	Gets one or more values	from a PGresult	in a scanf fashion.

SYNOPSIS
       #include	<libpqtypes.h>

       int PQgetf(const	PGresult *res, int tup_num,
		  const	char *format, ...);
       int PQgetvf(const PGresult *res,	int tup_num,
		  const	char *format, va_list ap);

DESCRIPTION
       The  PQgetf() and PQgetvf() functions get one or	more field values from
       a PGresult using	a scanf	style interface.  The tup_num  argument	 indi-
       cates which tuple to read values	from; values can only be read from one
       tuple at	a time.

       The format argument is a	data type specifier string indicating the val-
       ues  to	retrieve,  like	%int4 or #timestamp.  Any number of fields, in
       any order, can be retrieved in a	single call.  Each data	type specifier
       has  a  cooresponding field_num,	type-args, [...]  contained within the
       function's variable argument list.  The field_num either	indicates  tu-
       ple  field  number  or  tuple field name, depending on whether the data
       type in format used a '%' or '#'	specifer  mark	(`man  pqt-specs(3)').
       The  type-args  can  be	one or more arguments required by the specific
       data type: for example, "%int4" would require a pointer	to  a  PGint4.
       All built-in PostgreSQL data types require a single pointer value.

RETURN VALUE
       On  success,  a non-zero	value is returned.  On error, zero is returned
       and PQgeterror(3) will contain an error message.

       If the retrieval	of any field fails, the	get operation is  aborted  and
       function	will fail.  Eventhough some fields may have succeeded prior to
       the failure, their values should	not be trusted.	 Instead, make another
       PQgetf()	 call.	 Getting  an  array  or	a composite can	lead to	memory
       leaks when getf fails.  This is because these types allocate a PGresult
       object that must	be cleared.  To	avoid leaks, it	is recommended to per-
       form cleanup even if getf fails,	 retrieve  arrays  and	composites  by
       themselves or make them the last	field in a getf	call.

EXAMPLES
   Using PQgetf	on a PGresult
       The  example uses the libpq PQexec function to execute a	query and then
       uses PQgetf() to	retrieve field values.	It is important	to  note  that
       libpqtypes  execution  functions,  like	PQparamExec(3),	do not need to
       generate	the PGresult provided to PQgetf().

	      int success;
	      PGint4 i4;
	      PGtext text;
	      PGbytea bytea;
	      PGpoint pt;
	      PGresult *res = PQexec(conn, "SELECT i,t,b,p FROM	tbl");

	      /* Get some field	values from the	result (order doesn't matter) */
	      success =	PQgetf(res,
		   0,		 /* get	field values from tuple	0 */
		   "%int4 #text	%bytea %point",
				 /* type format	specifiers (get	text by	name '#') */
		   0,	&i4,	 /* get	an int4	from field num 0 */
		   "t",	&text,	 /* get	a text from field name "t" */
		   2,	&bytea,	 /* get	a bytea	from field num 2 */
		   3,	&pt);	 /* get	a point	from field num 3 */

	      /* Output	an error message using PQgeterror(3). */
	      if(!success)
		   fprintf(stderr, "*ERROR: %s\n", PQgeterror());

	      /* Output	the values, do this before PQclear() */
	      else
		   printf("int4=%d, text=%s, bytea=%d bytes, point=(%f,%f)\n",
			i4, text, bytea.len, pt.x, pt.y);

	      PQclear(res);

AUTHOR
       A contribution of eSilo,	LLC. for the  PostgreSQL  Database  Management
       System.	Written	by Andrew Chernow and Merlin Moncure.

REPORTING BUGS
       Report bugs to <libpqtypes@esilo.com>.

COPYRIGHT
       Copyright (c) 2011 eSilo, LLC. All rights reserved.
       This is free software; see the source for copying conditions.  There is
       NO warranty; not	even for MERCHANTABILITY or  FITNESS FOR A  PARTICULAR
       PURPOSE.

SEE ALSO
       pqt-specs(3), PQgeterror(3)

libpqtypes			     2011			     PQgetf(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | EXAMPLES | AUTHOR | REPORTING BUGS | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PQgetf&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help