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

FreeBSD Manual Pages

  
 
  

home | help
KSQL_ALLOC(3)		 BSD Library Functions Manual		 KSQL_ALLOC(3)

NAME
     ksql_alloc	-- allocate a ksql database handle

LIBRARY
     library "ksql"

SYNOPSIS
     #include <ksql.h>

     struct ksql *
     ksql_alloc(const struct ksqlconfig	*cfg);

DESCRIPTION
     The ksql_alloc function creates a SQLite database handle.	This must be
     matched by	a call to ksql_free(3) (unless KSQL_SAFE_EXIT is specified, in
     which case	it will	be freed on exit) and is usually followed by
     ksql_open(3).  If cfg is NULL, useful defaults are	used.

     The defaults on cfg are that the KSQL_EXIT_ON_ERR and KSQL_SAFE_EXIT
     flags are set, which means	that any errors	in using database routines
     will trigger an exit; and upon exiting in such a state, the database will
     be	properly cleaned up.  Moreover,	a simple message will be written to
     stderr with the full error	message	and error code for both	regular	and
     database errors.

     The struct	ksqlconfig structure consists of the following:

     unsigned int flags
	     A bit-field which may consists of KSQL_EXIT_ON_ERR, which causes
	     the system	to exit(3) if any database errors occur;
	     KSQL_FOREIGN_KEYS,	which causes the database to be	subsequently
	     opened with foreign key support; and KSQL_SAFE_EXIT, which	causes
	     the library to register an	atexit(3) hook to free the database if
	     it	hasn't be freed	prior to exit.	The KSQL_SAFE_EXIT flag	will
	     also cause	the SIGABRT and	SIGSEGV	signals	to be caught and
	     siglongjmp(3) into	an exit	handler, which will then close out
	     open databases.

     ksqlmsg err
	     Supply a function that will be invoked upon a non-database	error,
	     for example, memory allocation.

     ksqldbmsg dberr
	     A function	that will be invoked upon a database error, for	exam-
	     ple, if sqlite3_step(3) does not return an	SQLITE_DONE or
	     SQLITE_ROW	code.

     arg     The private argument passed to err	and dberr.

     The ksqlmsg function is invoked as	void ksqlmsg(void *arg,
     enum ksqlc	code, const char *file,	const char *msg), with arg being the
     private argument, argc being the error code in question, the database
     file (which may be	NULL), and msg being an	ASCII string describing	the
     error (in English).

     The ksqldbmsg function is void ksqldbmsg(void *arg, int sqlerr,
     int sqlexterr, const char *file, const char *msg),	which also has the
     sqlerr and	sqlexterr SQLite error and extended error code,	and and	the
     SQLite string error message msg.  The library exports two functions,
     ksqlitemsg() and ksqlitedbmsg(), which are	used as	the defaults.

RETURN VALUES
     This returns the allocated	database handle	or NULL	if memory allocations
     failed.

BSD				April 25, 2016				   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES

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

home | help