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

FreeBSD Manual Pages

  
 
  

home | help
KSQL_CFG_DEFAULTS(3)   FreeBSD Library Functions Manual	  KSQL_CFG_DEFAULTS(3)

NAME
     ksql_cfg_defaults -- set defaults for a ksql configuration

LIBRARY
     library "ksql"

SYNOPSIS
     #include <sys/types.h>
     #include <stdint.h>
     #include <ksql.h>

     void
     ksql_cfg_defaults(struct ksqlcfg *cfg);

DESCRIPTION
     The ksql_cfg_defaults function initialises	cfg with useful	defaults: 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.	 The
     ksqlitemsg() and ksqlitedbmsg() functions are set as error	message	log-
     gers.  These output to stderr the full error message and error code for
     both regular and database errors.

     The struct	ksqlcfg	structure consists of the following:

     void *arg
	     The private argument passed to err	and dberr.

     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.

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

     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.

     struct ksqlroles roles
	     Role-based	access control configuration.  Roles map a caller role
	     to	stored statements in stmts and set the availability of further
	     role transition with ksql_role(3).

     struct ksqlstmts stmts
	     Structure containing stored statement information.	 If stored
	     statements	are provided, ksql_stmt_alloc(3) and ksql_exec(3) will
	     only draw from the	stored statements.

     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 stmts variable	configures stored statements.  These provide an	extra
     measure of	security for ksql_alloc_child(3) contexts where	the protected
     child process manages pre-set SQL statements that cannot be changed by
     the caller.  It contains the following:

     const char	*const *stmts
	     An	array of SQL statement strings,	none of	which may be NULL.

     size_t stmtsz
	     The number	of entries in stmts.

     The roles variable	configures role-based access control mapping roles to
     stored statements set in stmts.  Stored statements	may be used without
     roles, but	roles require stored statements.  The structure	consists of
     the following:

     struct ksqlrole *roles
	     The role array.  Each struct ksqlrole entry consists of roles, a
	     list of possible roles that may be	subsequently set with
	     ksql_role(3) from the current role; flags,	a bit-field consisting
	     only of KSQLROLE_OPEN, which indicates that the role may open
	     databases;	and stmts, a list of all possible statements.  The in-
	     dex of a statement	in stmts and the role in roles corresponds to
	     the id passed to ksql_stmt_alloc(3) and ksql_exec(3).  If it zero
	     if	false (the role	may not	execute	the statement, or the role may
	     not be entered from the given role), non-zero if it may.

     size_t rolesz
	     The length	of roles.

     size_t defrole
	     The index of the default role set upon ksql_alloc(3) or
	     ksql_alloc_child(3).

EXAMPLES
     In	this simple example, a default configuration is	extended with stored
     statements, then the connection is	started	in split-process mode and the
     caller sandboxes.	(The sandboxing	is only	available on OpenBSD.)	For
     brevity, no error checking	is performed.

     struct ksqlcfg cfg;
     struct ksql *sql;
     const char	*const stmts[] = {
       "INSERT INTO test (foo) VALUES (?)",
       "SELECT foo FROM	test"
     };

     ksql_cfg_defaults(&cfg);
     cfg.stmts.stmts = stmts;
     cfg.stmts.stmtsz =	2;

     sql = ksql_alloc_child(&cfg, NULL,	NULL);
     pledge("stdio", NULL);

SEE ALSO
     ksql_alloc(3), ksql_alloc_child(3), ksql_exec(3), ksql_stmt_alloc(3)

FreeBSD	13.0			 April 5, 2018			  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO

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

home | help