man2/iopl.2

   1 .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
   2 .\" Portions extracted from linux/kernel/ioport.c (no copyright notice).
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Modified Tue Aug  1 16:47    1995 by Jochen Karrer
   7 .\"                              <cip307@cip.physik.uni-wuerzburg.de>
   8 .\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
   9 .\" Modified Fri Nov 27 14:50:36 CET 1998 by Andries Brouwer <aeb@cwi.nl>
  10 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  11 .\"     Added notes on capability requirements
  12 .\"
  13 .TH IOPL 2 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  14 .SH NAME
  15 iopl \- change I/O privilege level
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <sys/io.h>
  22 .PP
  23 .BI "int iopl(int " level );
  24 .fi
  25 .SH DESCRIPTION
  26 .BR iopl ()
  27 changes the I/O privilege level of the calling thread,
  28 as specified by the two least significant bits in
  29 .IR level .
  30 .PP
  31 The I/O privilege level for a normal thread is 0.
  32 Permissions are inherited from parents to children.
  33 .PP
  34 This call is deprecated, is significantly slower than
  35 .BR ioperm (2),
  36 and is only provided for older X servers which require
  37 access to all 65536 I/O ports.
  38 It is mostly for the i386 architecture.
  39 On many other architectures it does not exist or will always
  40 return an error.
  41 .SH RETURN VALUE
  42 On success, zero is returned.
  43 On error, \-1 is returned, and
  44 .I errno
  45 is set to indicate the error.
  46 .SH ERRORS
  47 .TP
  48 .B EINVAL
  49 .I level
  50 is greater than 3.
  51 .TP
  52 .B ENOSYS
  53 This call is unimplemented.
  54 .TP
  55 .B EPERM
  56 The calling thread has insufficient privilege to call
  57 .BR iopl ();
  58 the
  59 .B CAP_SYS_RAWIO
  60 capability is required to raise the I/O privilege level
  61 above its current value.
  62 .SH STANDARDS
  63 .BR iopl ()
  64 is Linux-specific and should not be used in programs that are
  65 intended to be portable.
  66 .SH NOTES
  67 .\" Libc5 treats it as a system call and has a prototype in
  68 .\" .IR <unistd.h> .
  69 .\" Glibc1 does not have a prototype.
  70 Glibc2 has a prototype both in
  71 .I <sys/io.h>
  72 and in
  73 .IR <sys/perm.h> .
  74 Avoid the latter, it is available on i386 only.
  75 .PP
  76 Prior to Linux 5.5
  77 .BR iopl ()
  78 allowed the thread to disable interrupts while running
  79 at a higher I/O privilege level.
  80 This will probably crash the system, and is not recommended.
  81 .PP
  82 Prior to Linux 3.7,
  83 on some architectures (such as i386), permissions
  84 .I were
  85 inherited by the child produced by
  86 .BR fork (2)
  87 and were preserved across
  88 .BR execve (2).
  89 This behavior was inadvertently changed in Linux 3.7,
  90 and won't be reinstated.
  91 .SH SEE ALSO
  92 .BR ioperm (2),
  93 .BR outb (2),
  94 .BR capabilities (7)