man2/sysctl.2

   1 .\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Written 11 April 1996 by Andries Brouwer <aeb@cwi.nl>
   6 .\" 960412: Added comments from Stephen Tweedie
   7 .\" Modified Tue Oct 22 22:28:41 1996 by Eric S. Raymond <esr@thyrsus.com>
   8 .\" Modified Mon Jan  5 20:31:04 1998 by aeb.
   9 .\"
  10 .TH SYSCTL 2 2022-09-17 "Linux man-pages (unreleased)"
  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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .BR EACCES ", " EPERM
  60 No search permission for one of the encountered "directories",
  61 or no read permission where
  62 .I oldval
  63 was nonzero, or no write permission where
  64 .I newval
  65 was nonzero.
  66 .TP
  67 .B EFAULT
  68 The invocation asked for the previous value by setting
  69 .I oldval
  70 non-NULL, but allowed zero room in
  71 .IR oldlenp .
  72 .TP
  73 .B ENOTDIR
  74 .I name
  75 was not found.
  76 .SH VERSIONS
  77 This system call first appeared in Linux 1.3.57.
  78 It was removed in Linux 5.5; glibc support was removed in version 2.32.
  79 .SH STANDARDS
  80 This call is Linux-specific, and should not be used in programs
  81 intended to be portable.
  82 It originated in
  83 4.4BSD.
  84 Only Linux has the
  85 .I /proc/sys
  86 mirror, and the object naming schemes differ between Linux and 4.4BSD,
  87 but the declaration of the
  88 .BR sysctl ()
  89 function is the same in both.
  90 .SH NOTES
  91 Use of this system call was long discouraged:
  92 since Linux 2.6.24,
  93 uses of this system call result in warnings in the kernel log,
  94 and in Linux 5.5, the system call was finally removed.
  95 Use the
  96 .I /proc/sys
  97 interface instead.
  98 .PP
  99 Note that on older kernels where this system call still exists,
 100 it is available only if the kernel was configured with the
 101 .B CONFIG_SYSCTL_SYSCALL
 102 option.
 103 Furthermore, glibc does not provide a wrapper for this system call,
 104 necessitating the use of
 105 .BR syscall (2).
 106 .SH BUGS
 107 The object names vary between kernel versions,
 108 making this system call worthless for applications.
 109 .PP
 110 Not all available objects are properly documented.
 111 .PP
 112 It is not yet possible to change operating system by writing to
 113 .IR /proc/sys/kernel/ostype .
 114 .SH EXAMPLES
 115 .\" SRC BEGIN (sysctl.c)
 116 .EX
 117 #define _GNU_SOURCE
 118 #include <stdio.h>
 119 #include <stdlib.h>
 120 #include <string.h>
 121 #include <sys/syscall.h>
 122 #include <unistd.h>
 123
 124 #include <linux/sysctl.h>
 125
 126 #define ARRAY_SIZE(arr)  (sizeof(arr) / sizeof((arr)[0]))
 127
 128 int _sysctl(struct __sysctl_args *args);
 129
 130 #define OSNAMESZ 100
 131
 132 int
 133 main(void)
 134 {
 135     int                   name[] = { CTL_KERN, KERN_OSTYPE };
 136     char                  osname[OSNAMESZ];
 137     size_t                osnamelth;
 138     struct __sysctl_args  args;
 139
 140     memset(&args, 0, sizeof(args));
 141     args.name = name;
 142     args.nlen = ARRAY_SIZE(name);
 143     args.oldval = osname;
 144     args.oldlenp = &osnamelth;
 145
 146     osnamelth = sizeof(osname);
 147
 148     if (syscall(SYS__sysctl, &args) == \-1) {
 149         perror("_sysctl");
 150         exit(EXIT_FAILURE);
 151     }
 152     printf("This machine is running %*s\en", (int) osnamelth, osname);
 153     exit(EXIT_SUCCESS);
 154 }
 155 .EE
 156 .\" SRC END
 157 .SH SEE ALSO
 158 .BR proc (5)