1.\" $Id: ksql_alloc_child.3,v 1.10 2018/05/07 04:46:56 kristaps Exp $ 2.\" 3.\" Copyright (c) 2017--2018 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: May 7 2018 $ 18.Dt KSQL_ALLOC_CHILD 3 19.Os 20.Sh NAME 21.Nm ksql_alloc_child 22.Nd allocate a ksql database handle in split-process mode 23.Sh LIBRARY 24.Lb ksql 25.Sh SYNOPSIS 26.In sys/types.h 27.In stdint.h 28.In ksql.h 29.Ft struct ksql * 30.Fo ksql_alloc_child 31.Fa "const struct ksqlcfg *cfg" 32.Fa "void (*onfork)(void *arg)" 33.Fa "void *arg" 34.Fc 35.Sh DESCRIPTION 36The 37.Nm 38function creates a SQLite database handle. 39It must be matched by a call to 40.Xr ksql_free 3 41unless 42.Dv KSQL_SAFE_EXIT 43is specified, in which case it will be freed on exit. 44(It is still good practice to manually free.) 45It is usually followed by 46.Xr ksql_open 3 . 47.Pp 48The 49.Nm 50function differs from 51.Xr ksql_alloc 3 52in that the database is opened in a child process instead of within the 53current process, with all database queries running over a communication 54socket. 55This way, the caller can safely sandbox after the function returns. 56.Pp 57If 58.Fa cfg 59is 60.Dv NULL , 61a configuration from 62.Xr ksql_cfg_defaults 3 63is used. 64.Pp 65The 66.Fa onfork 67function, if specified, is invoked by the child after a successful 68.Xr fork 2 69with the 70.Fa arg 71variable. 72The process environment within which 73.Fa onfork 74is invoked is prior to its being sandboxed. 75.\" .Sh CONTEXT 76.\" For section 9 functions only. 77.\" .Sh IMPLEMENTATION NOTES 78.\" Not used in OpenBSD. 79.Sh RETURN VALUES 80This returns the allocated database handle or 81.Dv NULL 82if an error occurs. 83.\" For sections 2, 3, and 9 function return values only. 84.\" .Sh ENVIRONMENT 85.\" For sections 1, 6, 7, and 8 only. 86.\" .Sh FILES 87.\" .Sh EXIT STATUS 88.\" For sections 1, 6, and 8 only. 89.\" .Sh EXAMPLES 90.\" .Sh DIAGNOSTICS 91.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. 92.\" .Sh ERRORS 93.\" For sections 2, 3, 4, and 9 errno settings only. 94.Sh SEE ALSO 95.Xr ksql_cfg_defaults 3 , 96.Xr ksql_free 3 97.\" .Sh STANDARDS 98.\" .Sh HISTORY 99.\" .Sh AUTHORS 100.\" .Sh CAVEATS 101.\" .Sh BUGS 102.\" .Sh SECURITY CONSIDERATIONS 103.\" Not used in OpenBSD. 104