1.\" $OpenBSD: sysctl_int.9,v 1.9 2020/09/01 01:57:15 gnezdo 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: September 1 2020 $ 19.Dt SYSCTL_INT 9 20.Os 21.Sh NAME 22.Nm sysctl_int , 23.Nm sysctl_bounded_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_bounded_arr 46.Fa "const struct sysctl_bounded_args *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 Fn sysctl_bounded_arr "const struct sysctl_bounded_args *valpp" "u_int valplen" "int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" 217Asserts the new value is in the range specified by the element of 218.Ar valpp 219with the value of the 220.Va mib 221field equal to 222.Ar name[0] , 223before invoking 224.Fn sysctl_int 225to read/write as normal. 226.It Fn sysctl_quad "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "int64_t *valp" 227The variable referenced is a 64-bit integer. 228Read or write returning the previous value in the user memory location 229pointed to by the 230.Ar oldp 231argument. 232The value pointed to by 233.Ar oldlenp 234has to be no less than eight. 235.It Fn sysctl_rdquad "void *oldp" "size_t *oldlenp" "void *newp" "int64_t val" 236A read-only version of the above. 237.It Fn sysctl_string "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "char *str" "int maxlen" 238The variable referenced by the 239.Ar str 240argument is a string of maximum length of 241.Ar maxlen . 242The old value is copied out into a user buffer pointed to by the 243.Ar oldp 244argument. 245If there is not enough space to store it, an 246.Dv ENOMEM 247is returned. 248If 249.Ar newlen 250is larger than 251.Ar maxlen , 252an 253.Dv EINVAL 254error is returned. 255.It Fn sysctl_tstring "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "char *str" "int maxlen" 256A version of the above that truncates the old value that does not fit 257into the buffer provided by 258.Ar oldp 259instead of returning 260.Dv ENOMEM . 261.It Fn sysctl_rdstring "void *oldp" "size_t *oldlenp" "void *newp" "const char *str" 262A read-only version of 263.Fn sysctl_string . 264.It Fn sysctl_struct "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "void *sp" "int len" 265Assume the area pointed to by the 266.Ar sp 267argument is an opaque array of bytes of size 268.Ar len . 269Old and new length checks are performed and data is copied in and/or out. 270.It Fn sysctl_rdstruct "void *oldp" "size_t *oldlenp" "void *newp" "const void *sp" "int len" 271A read-only version of the above. 272.El 273.Sh SEE ALSO 274.Xr sysctl 2 , 275.Xr sysctl.conf 5 , 276.Xr sysctl 8 , 277.Xr syscall 9 278.Sh HISTORY 279These functions first appeared in 280.Bx 4.4 . 281.\" .Sh AUTHORS 282