1.\" $OpenBSD: sysctl_int.9,v 1.8 2020/08/03 13:56:02 schwarze Exp $ 2.\" 3.\" Copyright (c) 2006 Michael Shalayeff 4.\" All rights reserved. 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: August 3 2020 $ 19.Dt SYSCTL_INT 9 20.Os 21.Sh NAME 22.Nm sysctl_int , 23.Nm sysctl_int_arr , 24.Nm sysctl_quad , 25.Nm sysctl_string , 26.Nm sysctl_tstring , 27.Nm sysctl_rdint , 28.Nm sysctl_rdquad , 29.Nm sysctl_rdstring , 30.Nm sysctl_rdstruct , 31.Nm sysctl_struct 32.Nd kernel sysctl interface 33.Sh SYNOPSIS 34.In sys/types.h 35.In sys/sysctl.h 36.Ft int 37.Fo sysctl_int 38.Fa "void *oldp" 39.Fa "size_t *oldlenp" 40.Fa "void *newp" 41.Fa "size_t newlen" 42.Fa "int *valp" 43.Fc 44.Ft int 45.Fo sysctl_int_arr 46.Fa "int **valpp" 47.Fa "u_int valplen" 48.Fa "int *name" 49.Fa "u_int namelen" 50.Fa "void *oldp" 51.Fa "size_t *oldlenp" 52.Fa "void *newp" 53.Fa "size_t newlen" 54.Fc 55.Ft int 56.Fo sysctl_quad 57.Fa "void *oldp" 58.Fa "size_t *oldlenp" 59.Fa "void *newp" 60.Fa "size_t newlen" 61.Fa "int64_t *valp" 62.Fc 63.Ft int 64.Fo sysctl_string 65.Fa "void *oldp" 66.Fa "size_t *oldlenp" 67.Fa "void *newp" 68.Fa "size_t newlen" 69.Fa "char *str" 70.Fa "int maxlen" 71.Fc 72.Ft int 73.Fo sysctl_tstring 74.Fa "void *oldp" 75.Fa "size_t *oldlenp" 76.Fa "void *newp" 77.Fa "size_t newlen" 78.Fa "char *str" 79.Fa "int maxlen" 80.Fc 81.Ft int 82.Fo sysctl_rdint 83.Fa "void *oldp" 84.Fa "size_t *oldlenp" 85.Fa "void *newp" 86.Fa "int val" 87.Fc 88.Ft int 89.Fo sysctl_rdquad 90.Fa "void *oldp" 91.Fa "size_t *oldlenp" 92.Fa "void *newp" 93.Fa "int64_t val" 94.Fc 95.Ft int 96.Fo sysctl_rdstring 97.Fa "void *oldp" 98.Fa "size_t *oldlenp" 99.Fa "void *newp" 100.Fa "const char *str" 101.Fc 102.Ft int 103.Fo sysctl_rdstruct 104.Fa "void *oldp" 105.Fa "size_t *oldlenp" 106.Fa "void *newp" 107.Fa "const void *sp" 108.Fa "int len" 109.Fc 110.Ft int 111.Fo sysctl_struct 112.Fa "void *oldp" 113.Fa "size_t *oldlenp" 114.Fa "void *newp" 115.Fa "size_t newlen" 116.Fa "void *sp" 117.Fa "int len" 118.Fc 119.Sh DESCRIPTION 120These functions and data structures aim to simplify and partially 121implement operations for the kernel and user implementations of the 122.Xr sysctl 2 123interface. 124A single 125.Xr syscall 9 126is used to request and modify kernel variables. 127The 128.Fa mib 129argument is recursively scanned as an array of integers, either calling 130further functions for parsing the rest of the MIB for nodes or operating 131on kernel data for leaf nodes. 132.Ss Data Structures 133For each level of the MIB tree, the kernel header files provide a 134.Xr cpp 1 135macro initialiser for an array of the following data structures: 136.Bd -literal -offset indent 137struct ctlname { 138 char *ctl_name; /* subsystem name */ 139 int ctl_type; /* type of name */ 140}; 141.Ed 142.Pp 143For example: 144.Bd -literal -offset indent 145#define CTL_NAMES { \e 146 { 0, 0 }, \e 147 { "kern", CTLTYPE_NODE }, \e 148 { "vm", CTLTYPE_NODE }, \e 149 { "fs", CTLTYPE_NODE }, \e 150 { "net", CTLTYPE_NODE }, \e 151 { "debug", CTLTYPE_NODE }, \e 152 { "hw", CTLTYPE_NODE }, \e 153 { "machdep", CTLTYPE_NODE }, \e 154 { "user", CTLTYPE_NODE }, \e 155 { "ddb", CTLTYPE_NODE }, \e 156 { "vfs", CTLTYPE_NODE }, \e 157} 158.Ed 159.Pp 160Each array element initialiser maps the correspondent MIB identifier. 161The 162.Fa ctl_name 163field provides a string name. 164The 165.Fa ctl_type 166field describes the identifier type, where possible values are: 167.Pp 168.Bl -tag -width CTLTYPE_STRING_ -compact -offset indent 169.It CTLTYPE_NODE 170The name is a node; 171.It CTLTYPE_INT 172The name describes an integer; 173.It CTLTYPE_STRING 174The name describes a string; 175.It CTLTYPE_QUAD 176The name describes a 64-bit number; 177.It CTLTYPE_STRUCT 178The name describes a structure. 179.El 180.Pp 181For each of the types there are two functions provided to perform both 182read and write or only a read operation on the identifier (see the 183following subsection). 184.Pp 185These data structures are used by the 186.Xr sysctl 8 187program to provide mapping into MIB identifiers. 188.Ss Functions 189All of the functions perform a write provided that 190.Ar newp 191is not a 192.Dv NULL 193pointer and 194.Ar newlen 195specifies an appropriate data length. 196All read-only versions of the functions return 197.Dv EPERM 198if a write operation is requested. 199.Pp 200The following helper functions are provided to aid operation on the 201kernel data variables referenced by the leaf nodes in the MIBs: 202.Bl -tag -width sysctl_ 203.It Fn sysctl_int "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "int *valp" 204The variable referenced by 205.Ar valp 206is a 32-bit integer. 207Read or write returning the previous value in the user memory location 208pointed to by the 209.Ar oldp 210argument. 211The value pointed to by 212.Ar oldlenp 213has to be no less than four. 214.It Fn sysctl_rdint "void *oldp" "size_t *oldlenp" "void *newp" "int val" 215A read-only version of the above. 216.\" .It sysctl_int_arr 217.It Fn sysctl_quad "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "int64_t *valp" 218The variable referenced is a 64-bit integer. 219Read or write returning the previous value in the user memory location 220pointed to by the 221.Ar oldp 222argument. 223The value pointed to by 224.Ar oldlenp 225has to be no less than eight. 226.It Fn sysctl_rdquad "void *oldp" "size_t *oldlenp" "void *newp" "int64_t val" 227A read-only version of the above. 228.It Fn sysctl_string "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "char *str" "int maxlen" 229The variable referenced by the 230.Ar str 231argument is a string of maximum length of 232.Ar maxlen . 233The old value is copied out into a user buffer pointed to by the 234.Ar oldp 235argument. 236If there is not enough space to store it, an 237.Dv ENOMEM 238is returned. 239If 240.Ar newlen 241is larger than 242.Ar maxlen , 243an 244.Dv EINVAL 245error is returned. 246.It Fn sysctl_tstring "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "char *str" "int maxlen" 247A version of the above that truncates the old value that does not fit 248into the buffer provided by 249.Ar oldp 250instead of returning 251.Dv ENOMEM . 252.It Fn sysctl_rdstring "void *oldp" "size_t *oldlenp" "void *newp" "const char *str" 253A read-only version of 254.Fn sysctl_string . 255.It Fn sysctl_struct "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "void *sp" "int len" 256Assume the area pointed to by the 257.Ar sp 258argument is an opaque array of bytes of size 259.Ar len . 260Old and new length checks are performed and data is copied in and/or out. 261.It Fn sysctl_rdstruct "void *oldp" "size_t *oldlenp" "void *newp" "const void *sp" "int len" 262A read-only version of the above. 263.El 264.Sh SEE ALSO 265.Xr sysctl 2 , 266.Xr sysctl.conf 5 , 267.Xr sysctl 8 , 268.Xr syscall 9 269.Sh HISTORY 270These functions first appeared in 271.Bx 4.4 . 272.\" .Sh AUTHORS 273