X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man2%2Fsysctl.2;h=0b9693a67f362e9d801737d2aaa4450f7188ae75;hb=880c3f67ef130e0e9c625ae2e48d9519a180cbe8;hp=7a27d4c2e6d763b30e106690d244d3f601e5e127;hpb=c13182efa3b3d77f2563034c8212c0ca798243ca;p=thirdparty%2Fman-pages.git diff --git a/man2/sysctl.2 b/man2/sysctl.2 index 7a27d4c2e6..0b9693a67f 100644 --- 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,31 +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 .\" 960412: Added comments from Stephen Tweedie .\" Modified Tue Oct 22 22:28:41 1996 by Eric S. Raymond .\" Modified Mon Jan 5 20:31:04 1998 by aeb. .\" -.TH SYSCTL 2 1996-04-11 "Linux 1.3.85" "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 -.br -.B #include -.br .B #include -.br -.B #include -.sp -.B _syscall1(int, _sysctl, struct __sysctl_args *, args) - /* Using \fBsyscall\fP(2) may be preferable; see \fBintro\fP(2) */ -.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. @@ -51,57 +51,26 @@ For example, the hostname, or the maximum number of open files. The argument has the form .PP -.nf +.in +4n +.EX struct __sysctl_args { - int *name; /* integer vector describing variable */ - int nlen; /* length of this vector */ - void *oldval; /* 0 or address where to store old value */ - size_t *oldlenp; /* available room for old value, - overwritten by actual size of old value */ - void *newval; /* 0 or address of new value */ - size_t newlen; /* size of new value */ + int *name; /* integer vector describing variable */ + int nlen; /* length of this vector */ + void *oldval; /* 0 or address where to store old value */ + size_t *oldlenp; /* available room for old value, + overwritten by actual size of old value */ + 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 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 EXAMPLE -.nf -#include -#include -#include - -_syscall1(int, _sysctl, struct __sysctl_args *, args); -int sysctl(int *name, int nlen, void *oldval, size_t *oldlenp, - void *newval, size_t newlen) -{ - struct __sysctl_args args = { name, nlen, oldval, oldlenp, - newval, newlen }; - return _sysctl(&args); -} - -#define SIZE(x) sizeof(x)/sizeof(x[0]) -#define OSNAMESZ 100 - -char osname[OSNAMESZ]; -int osnamelth; -int name[] = { CTL_KERN, KERN_OSTYPE }; - -int -main(void) -{ - osnamelth = sizeof(osname); - if (sysctl(name, SIZE(name), osname, &osnamelth, 0, 0)) - perror("sysctl"); - else - printf("This machine is running %*s\en", osnamelth, osname); - return 0; -} -.fi -.SH "RETURN VALUE" +.SH RETURN VALUE Upon successful completion, .BR _sysctl () returns 0. @@ -110,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 @@ -119,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 () @@ -139,18 +108,74 @@ 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 BUGS -The object names vary between kernel versions. -THIS MAKES THIS SYSTEM CALL WORTHLESS FOR APPLICATIONS. -Use the +.SH NOTES +Glibc does not provide a wrapper for this system call; call it using +.BR syscall (2). +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. -.br +.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. -.br +.PP It is not yet possible to change operating system by writing to .IR /proc/sys/kernel/ostype . -.SH "SEE ALSO" +.SH EXAMPLE +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include + +int _sysctl(struct __sysctl_args *args ); + +#define OSNAMESZ 100 + +int +main(void) +{ + struct __sysctl_args args; + char osname[OSNAMESZ]; + size_t osnamelth; + int name[] = { CTL_KERN, KERN_OSTYPE }; + + memset(&args, 0, sizeof(struct __sysctl_args)); + args.name = name; + 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\en", osnamelth, osname); + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO .BR proc (5)