1.\" $Id: ksql_role.3,v 1.5 2018/04/05 15:15:34 kristaps Exp $ 2.\" 3.\" Copyright (c) 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: April 5 2018 $ 18.Dt KSQL_ROLE 3 19.Os 20.Sh NAME 21.Nm ksql_role 22.Nd set role in ksql context 23.Sh LIBRARY 24.Lb ksql 25.Sh SYNOPSIS 26.In sys/types.h 27.In stdint.h 28.In ksql.h 29.Ft void 30.Fo ksql_role 31.Fa "struct ksql *sql" 32.Fa "size_t role" 33.Fc 34.Sh DESCRIPTION 35The 36.Nm 37function sets the current role of 38.Fa sql . 39The 40.Fa role 41is the index of a role defined in 42.Fa cfg->roles 43as passed to 44.Xr ksql_alloc 3 45or 46.Xr ksql_alloc_child 3 . 47The role affects all subsequent 48.Xr ksql_exec 3 49and 50.Xr ksql_stmt_alloc 3 51calls. 52.Pp 53The new role must be allowed by having a non-zero value in the 54.Fa roles 55array within the current role's 56.Ft struct ksqlrole 57object. 58Otherwise, the situation is logged to 59.Dv stderr 60and the program is immediately terminated. 61.Pp 62In split-process mode, 63.Fn ksql_role 64automatically sets 65.Dv KSQL_EXIT_ON_ERR 66on 67.Fa cfg->flags 68and 69.Fa cfg->err 70to 71.Dv NULL , 72restoring both if/when it returns. 73These guarantee that the function will never return without having properly set 74the new role. 75.\" .Sh CONTEXT 76.\" For section 9 functions only. 77.\" .Sh IMPLEMENTATION NOTES 78.\" Not used in OpenBSD. 79.\" .Sh RETURN VALUES 80.\" For sections 2, 3, and 9 function return values only. 81.\" .Sh ENVIRONMENT 82.\" For sections 1, 6, 7, and 8 only. 83.\" .Sh FILES 84.\" .Sh EXIT STATUS 85.\" For sections 1, 6, and 8 only. 86.\" .Sh EXAMPLES 87.\" .Sh DIAGNOSTICS 88.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. 89.\" .Sh ERRORS 90.\" For sections 2, 3, 4, and 9 errno settings only. 91.Sh SEE ALSO 92.Xr ksql_alloc 3 , 93.Xr ksql_alloc_child 3 , 94.Xr ksql_exec 3 , 95.Xr ksql_stmt_alloc 3 96.\" .Sh STANDARDS 97.\" .Sh HISTORY 98.\" .Sh AUTHORS 99.\" .Sh CAVEATS 100.\" .Sh BUGS 101.\" .Sh SECURITY CONSIDERATIONS 102.\" Not used in OpenBSD. 103