Debian Codegraph @

upstream/debian-trixie/man2/sysctl.2

raw
1 .\" Copyright (C) 1996 Andries Brouwer ([email protected])
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .\" Written 11 April 1996 by Andries Brouwer <[email protected]>
6 .\" 960412: Added comments from Stephen Tweedie
7 .\" Modified Tue Oct 22 22:28:41 1996 by Eric S. Raymond <[email protected]>
8 .\" Modified Mon Jan 5 20:31:04 1998 by aeb.
9 .\"
10 .TH sysctl 2 2024-06-15 "Linux man-pages 6.9.1"
11 .SH NAME
12 sysctl \- read/write system parameters
13 .SH SYNOPSIS
14 .nf
15 .B #include <unistd.h>
16 .B #include <linux/sysctl.h>
17 .P
18 .BI "[[deprecated]] int _sysctl(struct __sysctl_args *" args );
19 .fi
20 .SH DESCRIPTION
21 .B This system call no longer exists on current kernels!
22 See NOTES.
23 .P
24 The
25 .BR _sysctl ()
26 call reads and/or writes kernel parameters.
27 For example, the hostname,
28 or the maximum number of open files.
29 The argument has the form
30 .P
31 .in +4n
32 .EX
33 struct __sysctl_args {
34 int *name; /* integer vector describing variable */
35 int nlen; /* length of this vector */
36 void *oldval; /* 0 or address where to store old value */
37 size_t *oldlenp; /* available room for old value,
38 overwritten by actual size of old value */
39 void *newval; /* 0 or address of new value */
40 size_t newlen; /* size of new value */
41 };
42 .EE
43 .in
44 .P
45 This call does a search in a tree structure, possibly resembling
46 a directory tree under
47 .IR /proc/sys ,
48 and if the requested item is found calls some appropriate routine
49 to read or modify the value.
50 .SH RETURN VALUE
51 Upon successful completion,
52 .BR _sysctl ()
53 returns 0.
54 Otherwise, a value of \-1 is returned and
55 .I errno
56 is set to indicate the error.
57 .SH ERRORS
58 .TP
59 .B EACCES
60 .TQ
61 .B EPERM
62 No search permission for one of the encountered "directories",
63 or no read permission where
64 .I oldval
65 was nonzero, or no write permission where
66 .I newval
67 was nonzero.
68 .TP
69 .B EFAULT
70 The invocation asked for the previous value by setting
71 .I oldval
72 non-NULL, but allowed zero room in
73 .IR oldlenp .
74 .TP
75 .B ENOTDIR
76 .I name
77 was not found.
78 .SH STANDARDS
79 Linux.
80 .SH HISTORY
81 Linux 1.3.57.
82 Removed in Linux 5.5, glibc 2.32.
83 .P
84 It originated in
85 4.4BSD.
86 Only Linux has the
87 .I /proc/sys
88 mirror, and the object naming schemes differ between Linux and 4.4BSD,
89 but the declaration of the
90 .BR sysctl ()
91 function is the same in both.
92 .SH NOTES
93 Use of this system call was long discouraged:
94 since Linux 2.6.24,
95 uses of this system call result in warnings in the kernel log,
96 and in Linux 5.5, the system call was finally removed.
97 Use the
98 .I /proc/sys
99 interface instead.
100 .P
101 Note that on older kernels where this system call still exists,
102 it is available only if the kernel was configured with the
103 .B CONFIG_SYSCTL_SYSCALL
104 option.
105 Furthermore, glibc does not provide a wrapper for this system call,
106 necessitating the use of
107 .BR syscall (2).
108 .SH BUGS
109 The object names vary between kernel versions,
110 making this system call worthless for applications.
111 .P
112 Not all available objects are properly documented.
113 .P
114 It is not yet possible to change operating system by writing to
115 .IR /proc/sys/kernel/ostype .
116 .SH EXAMPLES
117 .\" SRC BEGIN (sysctl.c)
118 .EX
119 #define _GNU_SOURCE
120 #include <stdio.h>
121 #include <stdlib.h>
122 #include <string.h>
123 #include <sys/syscall.h>
124 #include <unistd.h>
125 \&
126 #include <linux/sysctl.h>
127 \&
128 #define ARRAY_SIZE(arr) (sizeof(arr) / sizeof((arr)[0]))
129 \&
130 int _sysctl(struct __sysctl_args *args);
131 \&
132 #define OSNAMESZ 100
133 \&
134 int
135 main(void)
136 {
137 int name[] = { CTL_KERN, KERN_OSTYPE };
138 char osname[OSNAMESZ];
139 size_t osnamelth;
140 struct __sysctl_args args;
141 \&
142 memset(&args, 0, sizeof(args));
143 args.name = name;
144 args.nlen = ARRAY_SIZE(name);
145 args.oldval = osname;
146 args.oldlenp = &osnamelth;
147 \&
148 osnamelth = sizeof(osname);
149 \&
150 if (syscall(SYS__sysctl, &args) == \-1) {
151 perror("_sysctl");
152 exit(EXIT_FAILURE);
153 }
154 printf("This machine is running %*s\[rs]n", (int) osnamelth, osname);
155 exit(EXIT_SUCCESS);
156 }
157 .EE
158 .\" SRC END
159 .SH SEE ALSO
160 .BR proc (5)