1.\" $OpenBSD: sysctl_int.9,v 1.4 2007/05/31 19:20:01 jmc 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: May 31 2007 $ 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.Fd #include <sys/types.h> 35.Fd #include <sys/sysctl.h> 36.Ft int 37.Fn sysctl_int "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "int *valp" 38.Ft int 39.Fn sysctl_int_arr "int **valpp" "int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" 40.Ft int 41.Fn sysctl_quad "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "int64_t *valp" 42.Ft int 43.Fn sysctl_string "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "char *str" "int maxlen" 44.Ft int 45.Fn sysctl_tstring "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "char *str" "int maxlen" 46.Ft int 47.Fn sysctl_rdint "void *oldp" "size_t *oldlenp" "void *newp" "int val" 48.Ft int 49.Fn sysctl_rdquad "void *oldp" "size_t *oldlenp" "void *newp" "int64_t val" 50.Ft int 51.Fn sysctl_rdstring "void *oldp" "size_t *oldlenp" "void *newp" "const char *str" 52.Ft int 53.Fn sysctl_rdstruct "void *oldp" "size_t *oldlenp" "void *newp" "const void *sp" "int len" 54.Ft int 55.Fn sysctl_struct "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "void *sp" "int len" 56.Sh DESCRIPTION 57These functions and data structures aim to simplify and partially 58implement operations for the kernel and user implementations of the 59.Xr sysctl 3 60interface. 61A single 62.Xr syscall 9 63is used to request and modify kernel variables. 64The 65.Fa mib 66argument is recursively scanned as an array of integers, either calling 67further functions for parsing the rest of the MIB for nodes or operating 68on kernel data for leaf nodes. 69.Ss Data Structures 70For each level of the MIB tree, the kernel header files provide a 71.Xr cpp 1 72macro initialiser for an array of the following data structures: 73.Bd -literal -offset indent 74struct ctlname { 75 char *ctl_name; /* subsystem name */ 76 int ctl_type; /* type of name */ 77}; 78.Ed 79.Pp 80For example: 81.Bd -literal -offset indent 82#define CTL_NAMES { \e 83 { 0, 0 }, \e 84 { "kern", CTLTYPE_NODE }, \e 85 { "vm", CTLTYPE_NODE }, \e 86 { "fs", CTLTYPE_NODE }, \e 87 { "net", CTLTYPE_NODE }, \e 88 { "debug", CTLTYPE_NODE }, \e 89 { "hw", CTLTYPE_NODE }, \e 90 { "machdep", CTLTYPE_NODE }, \e 91 { "user", CTLTYPE_NODE }, \e 92 { "ddb", CTLTYPE_NODE }, \e 93 { "vfs", CTLTYPE_NODE }, \e 94} 95.Ed 96.Pp 97Each array element initialiser maps the correspondent MIB identifier. 98The 99.Fa ctl_name 100field provides a string name. 101The 102.Fa ctl_type 103field describes the identifier type, where possible values are: 104.Pp 105.Bl -tag -width CTLTYPE_STRING_ -compact -offset indent 106.It CTLTYPE_NODE 107The name is a node; 108.It CTLTYPE_INT 109The name describes an integer; 110.It CTLTYPE_STRING 111The name describes a string; 112.It CTLTYPE_QUAD 113The name describes a 64-bit number; 114.It CTLTYPE_STRUCT 115The name describes a structure. 116.El 117.Pp 118For each of the types there are two functions provided to perform both 119read and write or only a read operation on the identifier (see the 120following subsection). 121.Pp 122These data structures are used by the 123.Xr sysctl 8 124program to provide mapping into MIB identifiers. 125.Ss Functions 126All of the functions perform a write provided that 127.Ar newp 128is not a 129.Dv NULL 130pointer and 131.Ar newlen 132specifies an appropriate data length. 133All read-only versions of the functions return 134.Dv EPERM 135if a write operation is requested. 136.Pp 137The following helper functions are provided to aid operation on the 138kernel data variables referenced by the leaf nodes in the MIBs: 139.Bl -tag -width sysctl_ 140.It Fn sysctl_int "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "int *valp" 141The variable referenced by 142.Ar valp 143is a 32-bit integer. 144Read or write returning the previous value in the user memory location 145pointed to by the 146.Ar oldp 147argument. 148The value pointed to by 149.Ar oldlenp 150has to be no less than four. 151.It Fn sysctl_rdint "void *oldp" "size_t *oldlenp" "void *newp" "int val" 152A read-only version of the above. 153.\" .It sysctl_int_arr 154.It Fn sysctl_quad "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "int64_t *valp" 155The variable referenced is a 64-bit integer. 156Read or write returning the previous value in the user memory location 157pointed to by the 158.Ar oldp 159argument. 160The value pointed to by 161.Ar oldlenp 162has to be no less than eight. 163.It Fn sysctl_rdquad "void *oldp" "size_t *oldlenp" "void *newp" "int64_t val" 164A read-only version of the above. 165.It Fn sysctl_string "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "char *str" "int maxlen" 166The variable referenced by the 167.Ar str 168argument is a string of maximum length of 169.Ar maxlen . 170The old value is copied out into a user buffer pointed to by the 171.Ar oldp 172argument. 173If there is not enough space to store it, an 174.Dv ENOMEM 175is returned. 176If 177.Ar newlen 178is larger than 179.Ar maxlen , 180an 181.Dv EINVAL 182error is returned. 183.It Fn sysctl_tstring "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "char *str" "int maxlen" 184A version of the above that truncates the old value that does not fit 185into the buffer provided by 186.Ar oldp 187instead of returning 188.Dv ENOMEM . 189.It Fn sysctl_rdstring "void *oldp" "size_t *oldlenp" "void *newp" "const char *str" 190A read-only version of 191.Fn sysctl_string . 192.It Fn sysctl_struct "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" "void *sp" "int len" 193Assume the area pointed to by the 194.Ar sp 195argument is an opaque array of bytes of size 196.Ar len . 197Old and new length checks are performed and data is copied in and/or out. 198.It Fn sysctl_rdstruct "void *oldp" "size_t *oldlenp" "void *newp" "const void *sp" "int len" 199A read-only version of the above. 200.El 201.Sh SEE ALSO 202.Xr sysctl 3 , 203.Xr sysctl.conf 5 , 204.Xr sysctl 8 , 205.Xr syscall 9 206.Sh HISTORY 207These functions first appeared in 208.Bx 4.4 . 209.\" .Sh AUTHORS 210