Removed trailing white space at end of lines

[thirdparty/man-pages.git] / man2 / sysctl.2

diff --git a/man2/sysctl.2 b/man2/sysctl.2
index 48fa4c1a7e7d87bde839ca3d13c657cdf500ad4f..0b9693a67f362e9d801737d2aaa4450f7188ae75 100644 (file)
--- a/man2/sysctl.2
+++ b/man2/sysctl.2
@@ -1,5 +1,6 @@
 .\" Copyright (C) 1996 Andries Brouwer (aeb@cwi.nl)
 .\"
+.\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
 .\" preserved on all copies.
@@ -19,24 +20,30 @@
 .\"
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
 .\"
 .\" Written 11 April 1996 by Andries Brouwer <aeb@cwi.nl>
 .\" 960412: Added comments from Stephen Tweedie
 .\" Modified Tue Oct 22 22:28:41 1996 by Eric S. Raymond <esr@thyrsus.com>
 .\" Modified Mon Jan  5 20:31:04 1998 by aeb.
 .\"
-.TH SYSCTL 2 2007-06-01 "Linux" "Linux Programmer's Manual"
+.TH SYSCTL 2 2019-03-06 "Linux" "Linux Programmer's Manual"
 .SH NAME
 sysctl \- read/write system parameters
 .SH SYNOPSIS
 .nf
 .B #include <unistd.h>
-.br
 .B #include <linux/sysctl.h>
-.sp
+.PP
 .BI "int _sysctl(struct __sysctl_args *" args );
 .fi
+.PP
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
 .SH DESCRIPTION
+.B Do not use this system call!
+See NOTES.
+.PP
 The
 .BR _sysctl ()
 call reads and/or writes kernel parameters.
@@ -44,8 +51,8 @@ For example, the hostname,
 or the maximum number of open files.
 The argument has the form
 .PP
-.in +0.25i
-.nf
+.in +4n
+.EX
 struct __sysctl_args {
     int    *name;    /* integer vector describing variable */
     int     nlen;    /* length of this vector */
@@ -55,7 +62,7 @@ struct __sysctl_args {
     void   *newval;  /* 0 or address of new value */
     size_t  newlen;  /* size of new value */
 };
-.fi
+.EE
 .in
 .PP
 This call does a search in a tree structure, possibly resembling
@@ -63,7 +70,7 @@ a directory tree under
 .IR /proc/sys ,
 and if the requested item is found calls some appropriate routine
 to read or modify the value.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
 Upon successful completion,
 .BR _sysctl ()
 returns 0.
@@ -72,6 +79,14 @@ Otherwise, a value of \-1 is returned and
 is set to indicate the error.
 .SH ERRORS
 .TP
+.BR EACCES ", " EPERM
+No search permission for one of the encountered "directories",
+or no read permission where
+.I oldval
+was nonzero, or no write permission where
+.I newval
+was nonzero.
+.TP
 .B EFAULT
 The invocation asked for the previous value by setting
 .I oldval
@@ -81,16 +96,8 @@ non-NULL, but allowed zero room in
 .B ENOTDIR
 .I name
 was not found.
-.TP
-.B EPERM
-No search permission for one of the encountered `directories',
-or no read permission where
-.I oldval
-was non-zero, or no write permission where
-.I newval
-was non-zero.
-.SH "CONFORMING TO"
-This call is Linux specific, and should not be used in programs
+.SH CONFORMING TO
+This call is Linux-specific, and should not be used in programs
 intended to be portable.
 A
 .BR sysctl ()
@@ -101,24 +108,39 @@ Only Linux has the
 .I /proc/sys
 mirror, and the object naming schemes differ between Linux and 4.4BSD,
 but the declaration of the
-.BR sysctl (2)
+.BR sysctl ()
 function is the same in both.
 .SH NOTES
 Glibc does not provide a wrapper for this system call; call it using
 .BR syscall (2).
-.SH BUGS
-The object names vary between kernel versions.
-THIS MAKES THIS SYSTEM CALL WORTHLESS FOR APPLICATIONS.
-Use the
+Or rather...
+.I don't
+call it:
+use of this system call has long been discouraged,
+and it is so unloved that
+\fBit is likely to disappear in a future kernel version\fP.
+.\" See http://lwn.net/Articles/247243/
+Since Linux 2.6.24,
+uses of this system call result in warnings in the kernel log.
+.\" Though comments in suggest that it is needed by old glibc binaries,
+.\" so maybe it's not going away.
+Remove it from your programs now; use the
 .I /proc/sys
 interface instead.
 .PP
+This system call is available only if the kernel was configured with the
+.B CONFIG_SYSCTL_SYSCALL
+option.
+.SH BUGS
+The object names vary between kernel versions,
+making this system call worthless for applications.
+.PP
 Not all available objects are properly documented.
 .PP
 It is not yet possible to change operating system by writing to
 .IR /proc/sys/kernel/ostype .
 .SH EXAMPLE
-.nf
+.EX
 #define _GNU_SOURCE
 #include <unistd.h>
 #include <sys/syscall.h>
@@ -144,16 +166,16 @@ main(void)
     args.nlen = sizeof(name)/sizeof(name[0]);
     args.oldval = osname;
     args.oldlenp = &osnamelth;
- 
+
     osnamelth = sizeof(osname);
-    
+
     if (syscall(SYS__sysctl, &args) == \-1) {
         perror("_sysctl");
         exit(EXIT_FAILURE);
     }
-    printf("This machine is running %*s\\n", osnamelth, osname);
+    printf("This machine is running %*s\en", osnamelth, osname);
     exit(EXIT_SUCCESS);
 }
-.fi
-.SH "SEE ALSO"
+.EE
+.SH SEE ALSO
 .BR proc (5)