lib/libc/sys/procctl.2

   1 .\" Copyright (c) 2013 Hudson River Trading LLC
   2 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Copyright (c) 2014 The FreeBSD Foundation
   6 .\" Portions of this documentation were written by Konstantin Belousov
   7 .\" under sponsorship from the FreeBSD Foundation.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .Dd October 26, 2023
  31 .Dt PROCCTL 2
  32 .Os
  33 .Sh NAME
  34 .Nm procctl
  35 .Nd control processes
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In sys/procctl.h
  40 .Ft int
  41 .Fn procctl "idtype_t idtype" "id_t id" "int cmd" "void *data"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn procctl
  45 system call provides for control over processes.
  46 The
  47 .Fa idtype
  48 and
  49 .Fa id
  50 arguments specify the set of processes to control.
  51 If multiple processes match the identifier,
  52 .Nm
  53 will make a
  54 .Dq best effort
  55 to control as many of the selected processes as possible.
  56 An error is only returned if no selected processes successfully complete
  57 the request.
  58 The following identifier types are supported:
  59 .Bl -tag -width P_PGID
  60 .It Dv P_PID
  61 Control the process with the process ID
  62 .Fa id .
  63 .Fa id
  64 zero is a shortcut for the calling process ID.
  65 .It Dv P_PGID
  66 Control processes belonging to the process group with the ID
  67 .Fa id .
  68 .El
  69 .Pp
  70 The control request to perform is specified by the
  71 .Fa cmd
  72 argument.
  73 .Pp
  74 All status changing requests
  75 .Dv *_CTL
  76 require the caller to have the right to debug the target.
  77 All status query requests
  78 .DV *_STATUS
  79 require the caller to have the right to observe the target.
  80 .Pp
  81 The following commands are supported:
  82 .Bl -tag -width PROC_TRAPCAP_STATUS
  83 .It Dv PROC_ASLR_CTL
  84 Controls the Address Space Layout Randomization (ASLR) in the program
  85 images created
  86 by
  87 .Xr execve 2
  88 in the specified process or its descendants that do not either change
  89 the control or modify it by other means.
  90 The
  91 .Fa data
  92 parameter must point to the integer variable holding one of the following
  93 values:
  94 .Bl -tag -width PROC_ASLR_FORCE_DISABLE
  95 .It Dv PROC_ASLR_FORCE_ENABLE
  96 Request that ASLR is enabled after execution, even if it is disabled
  97 system-wide.
  98 The image flag and set-uid might prevent ASLR enablement still.
  99 .It Dv PROC_ASLR_FORCE_DISABLE
 100 Request that ASLR is disabled after execution.
 101 Same notes as for
 102 .Dv PROC_ASLR_FORCE_ENABLE
 103 apply.
 104 .It Dv PROC_ASLR_NOFORCE
 105 Use the system-wide configured policy for ASLR.
 106 .El
 107 .It Dv PROC_ASLR_STATUS
 108 Returns the current status of ASLR enablement for the target process.
 109 The
 110 .Fa data
 111 parameter must point to the integer variable, where one of the
 112 following values is written:
 113 .Bl -tag -width PROC_ASLR_FORCE_DISABLE
 114 .It Dv PROC_ASLR_FORCE_ENABLE
 115 .It Dv PROC_ASLR_FORCE_DISABLE
 116 .It Dv PROC_ASLR_NOFORCE
 117 .El
 118 .Pp
 119 If the currently executed image in the process itself has ASLR enabled,
 120 the
 121 .Dv PROC_ASLR_ACTIVE
 122 flag is or-ed with the value listed above.
 123 .It Dv PROC_PROTMAX_CTL
 124 Controls implicit application of PROT_MAX protection equal to the
 125 .Fa prot
 126 argument of the
 127 .Xr mmap 2
 128 syscall, in the target process.
 129 The
 130 .Fa data
 131 parameter must point to the integer variable holding one of the following
 132 values:
 133 .Bl -tag -width PROC_PROTMAX_FORCE_DISABLE
 134 .It Dv PROC_PROTMAX_FORCE_ENABLE
 135 Enables implicit PROT_MAX application,
 136 even if it is disabled system-wide by the sysctl
 137 .Va vm.imply_prot_max .
 138 The image flag might still prevent the enablement.
 139 .It Dv PROC_PROTMAX_FORCE_DISABLE
 140 Request that implicit application of PROT_MAX be disabled.
 141 Same notes as for
 142 .Dv PROC_PROTMAX_FORCE_ENABLE
 143 apply.
 144 .It Dv PROC_PROTMAX_NOFORCE
 145 Use the system-wide configured policy for PROT_MAX.
 146 .El
 147 .It Dv PROC_PROTMAX_STATUS
 148 Returns the current status of implicit PROT_MAX enablement for the
 149 target process.
 150 The
 151 .Fa data
 152 parameter must point to the integer variable, where one of the
 153 following values is written:
 154 .Bl -tag -width PROC_PROTMAX_FORCE_DISABLE
 155 .It Dv PROC_PROTMAX_FORCE_ENABLE
 156 .It Dv PROC_PROTMAX_FORCE_DISABLE
 157 .It Dv PROC_PROTMAX_NOFORCE
 158 .El
 159 .Pp
 160 If the currently executed image in the process itself has implicit PROT_MAX
 161 application enabled, the
 162 .Dv PROC_PROTMAX_ACTIVE
 163 flag is or-ed with the value listed above.
 164 .It Dv PROC_SPROTECT
 165 Set process protection state.
 166 This is used to mark a process as protected from being killed if the system
 167 exhausts the available memory and swap.
 168 The
 169 .Fa data
 170 parameter must point to an integer containing an operation and zero or more
 171 optional flags.
 172 The following operations are supported:
 173 .Bl -tag -width PPROT_CLEAR
 174 .It Dv PPROT_SET
 175 Mark the selected processes as protected.
 176 .It Dv PPROT_CLEAR
 177 Clear the protected state of selected processes.
 178 .El
 179 .Pp
 180 The following optional flags are supported:
 181 .Bl -tag -width PPROT_DESCEND
 182 .It Dv PPROT_DESCEND
 183 Apply the requested operation to all child processes of each selected process
 184 in addition to each selected process.
 185 .It Dv PPROT_INHERIT
 186 When used with
 187 .Dv PPROT_SET ,
 188 mark all future child processes of each selected process as protected.
 189 Future child processes will also mark all of their future child processes.
 190 .El
 191 .It Dv PROC_REAP_ACQUIRE
 192 Acquires the reaper status for the current process.
 193 Reaper status means that children orphaned by the reaper's descendants
 194 that were forked after the acquisition of reaper status are reparented to the
 195 reaper process.
 196 After system initialization,
 197 .Xr init 8
 198 is the default reaper.
 199 .It Dv PROC_REAP_RELEASE
 200 Release the reaper state for the current process.
 201 The reaper of the current process becomes the new reaper of the
 202 current process's descendants.
 203 .It Dv PROC_REAP_STATUS
 204 Provides information about the reaper of the specified process,
 205 or the process itself when it is a reaper.
 206 The
 207 .Fa data
 208 argument must point to a
 209 .Vt procctl_reaper_status
 210 structure which is filled in by the syscall on successful return.
 211 .Bd -literal
 212 struct procctl_reaper_status {
 213         u_int   rs_flags;
 214         u_int   rs_children;
 215         u_int   rs_descendants;
 216         pid_t   rs_reaper;
 217         pid_t   rs_pid;
 218 };
 219 .Ed
 220 The
 221 .Fa rs_flags
 222 may have the following flags returned:
 223 .Bl -tag -width REAPER_STATUS_REALINIT
 224 .It Dv REAPER_STATUS_OWNED
 225 The specified process has acquired reaper status and has not
 226 released it.
 227 When the flag is returned, the specified process
 228 .Fa id ,
 229 pid, identifies the reaper, otherwise the
 230 .Fa rs_reaper
 231 field of the structure is set to the pid of the reaper
 232 for the specified process id.
 233 .It Dv REAPER_STATUS_REALINIT
 234 The specified process is the root of the reaper tree, i.e.,
 235 .Xr init 8 .
 236 .El
 237 .Pp
 238 The
 239 .Fa rs_children
 240 field returns the number of children of the reaper among the descendants.
 241 It is possible to have a child whose reaper is not the specified process,
 242 since the reaper for any existing children is not reset on the
 243 .Dv PROC_REAP_ACQUIRE
 244 operation.
 245 The
 246 .Fa rs_descendants
 247 field returns the total number of descendants of the reaper(s),
 248 not counting descendants of the reaper in the subtree.
 249 The
 250 .Fa rs_reaper
 251 field returns the reaper pid.
 252 The
 253 .Fa rs_pid
 254 returns the pid of one reaper child if there are any descendants.
 255 .It Dv PROC_REAP_GETPIDS
 256 Queries the list of descendants of the reaper of the specified process.
 257 The request takes a pointer to a
 258 .Vt procctl_reaper_pids
 259 structure in the
 260 .Fa data
 261 parameter.
 262 .Bd -literal
 263 struct procctl_reaper_pids {
 264         u_int   rp_count;
 265         struct procctl_reaper_pidinfo *rp_pids;
 266 };
 267 .Ed
 268 When called, the
 269 .Fa rp_pids
 270 field must point to an array of
 271 .Vt procctl_reaper_pidinfo
 272 structures, to be filled in on return,
 273 and the
 274 .Fa rp_count
 275 field must specify the size of the array,
 276 into which no more than
 277 .Fa rp_count
 278 elements will be filled in by the kernel.
 279 .Pp
 280 The
 281 .Vt "struct procctl_reaper_pidinfo"
 282 structure provides some information about one of the reaper's descendants.
 283 Note that for a descendant that is not a child, it may be incorrectly
 284 identified because of a race in which the original child process exited
 285 and the exited process's pid was reused for an unrelated process.
 286 .Bd -literal
 287 struct procctl_reaper_pidinfo {
 288         pid_t   pi_pid;
 289         pid_t   pi_subtree;
 290         u_int   pi_flags;
 291 };
 292 .Ed
 293 The
 294 .Fa pi_pid
 295 field is the process id of the descendant.
 296 The
 297 .Fa pi_subtree
 298 field provides the pid of the child of the reaper, which is the (grand-)parent
 299 of the process.
 300 The
 301 .Fa pi_flags
 302 field returns the following flags, further describing the descendant:
 303 .Bl -tag -width REAPER_PIDINFO_EXITING
 304 .It Dv REAPER_PIDINFO_VALID
 305 Set to indicate that the
 306 .Vt procctl_reaper_pidinfo
 307 structure was filled in by the kernel.
 308 Zero-filling the
 309 .Fa rp_pids
 310 array and testing the
 311 .Dv REAPER_PIDINFO_VALID
 312 flag allows the caller to detect the end
 313 of the returned array.
 314 .It Dv REAPER_PIDINFO_CHILD
 315 The
 316 .Fa pi_pid
 317 field identifies the direct child of the reaper.
 318 .It Dv REAPER_PIDINFO_REAPER
 319 The reported process is itself a reaper.
 320 The descendants of the subordinate reaper are not reported.
 321 .It Dv REAPER_PIDINFO_ZOMBIE
 322 The reported process is in the zombie state, ready to be reaped.
 323 .It Dv REAPER_PIDINFO_STOPPED
 324 The reported process is stopped by a SIGSTOP/SIGTSTP signal.
 325 .It Dv REAPER_PIDINFO_EXITING
 326 The reported process is in the process of exiting (but not yet a zombie).
 327 .El
 328 .It Dv PROC_REAP_KILL
 329 Request to deliver a signal to some subset of the descendants of the reaper.
 330 The
 331 .Fa data
 332 parameter must point to a
 333 .Vt procctl_reaper_kill
 334 structure, which is used both for parameters and status return.
 335 .Bd -literal
 336 struct procctl_reaper_kill {
 337         int     rk_sig;
 338         u_int   rk_flags;
 339         pid_t   rk_subtree;
 340         u_int   rk_killed;
 341         pid_t   rk_fpid;
 342 };
 343 .Ed
 344 The
 345 .Fa rk_sig
 346 field specifies the signal to be delivered.
 347 Zero is not a valid signal number, unlike for
 348 .Xr kill 2 .
 349 The
 350 .Fa rk_flags
 351 field further directs the operation.
 352 It is or-ed from the following flags:
 353 .Bl -tag -width REAPER_KILL_CHILDREN
 354 .It Dv REAPER_KILL_CHILDREN
 355 Deliver the specified signal only to direct children of the reaper.
 356 .It Dv REAPER_KILL_SUBTREE
 357 Deliver the specified signal only to descendants that were forked by
 358 the direct child with pid specified in the
 359 .Fa rk_subtree
 360 field.
 361 .El
 362 If neither the
 363 .Dv REAPER_KILL_CHILDREN
 364 nor the
 365 .Dv REAPER_KILL_SUBTREE
 366 flags are specified, all current descendants of the reaper are signalled.
 367 .Pp
 368 If a signal was delivered to any process, the return value from the request
 369 is zero.
 370 In this case, the
 371 .Fa rk_killed
 372 field identifies the number of processes signalled.
 373 The
 374 .Fa rk_fpid
 375 field is set to the pid of the first process for which signal
 376 delivery failed, e.g., due to permission problems.
 377 If no such process exists, the
 378 .Fa rk_fpid
 379 field is set to -1.
 380 .It Dv PROC_TRACE_CTL
 381 Enable or disable tracing of the specified process(es), according to the
 382 value of the integer argument.
 383 Tracing includes attachment to the process using the
 384 .Xr ptrace 2
 385 and
 386 .Xr ktrace 2 ,
 387 debugging sysctls,
 388 .Xr hwpmc 4 ,
 389 .Xr dtrace 1 ,
 390 and core dumping.
 391 Possible values for the
 392 .Fa data
 393 argument are:
 394 .Bl -tag -width PROC_TRACE_CTL_DISABLE_EXEC
 395 .It Dv PROC_TRACE_CTL_ENABLE
 396 Enable tracing, after it was disabled by
 397 .Dv PROC_TRACE_CTL_DISABLE .
 398 Only allowed for self.
 399 .It Dv PROC_TRACE_CTL_DISABLE
 400 Disable tracing for the specified process.
 401 Tracing is re-enabled when the process changes the executing
 402 program with the
 403 .Xr execve 2
 404 syscall.
 405 A child inherits the trace settings from the parent on
 406 .Xr fork 2 .
 407 .It Dv PROC_TRACE_CTL_DISABLE_EXEC
 408 Same as
 409 .Dv PROC_TRACE_CTL_DISABLE ,
 410 but the setting persists for the process even after
 411 .Xr execve 2 .
 412 .El
 413 .It Dv PROC_TRACE_STATUS
 414 Returns the current tracing status for the specified process in
 415 the integer variable pointed to by
 416 .Fa data .
 417 If tracing is disabled,
 418 .Fa data
 419 is set to -1.
 420 If tracing is enabled, but no debugger is attached by the
 421 .Xr ptrace 2
 422 syscall,
 423 .Fa data
 424 is set to 0.
 425 If a debugger is attached,
 426 .Fa data
 427 is set to the pid of the debugger process.
 428 .It Dv PROC_TRAPCAP_CTL
 429 Controls the capability mode sandbox actions for the specified
 430 sandboxed processes,
 431 on a return from any syscall which gives either a
 432 .Er ENOTCAPABLE
 433 or
 434 .Er ECAPMODE
 435 error.
 436 If the control is enabled, such errors from the syscalls cause
 437 delivery of the synchronous
 438 .Dv SIGTRAP
 439 signal to the thread immediately before returning from the syscalls.
 440 .Pp
 441 Possible values for the
 442 .Fa data
 443 argument are:
 444 .Bl -tag -width PROC_TRAPCAP_CTL_DISABLE
 445 .It Dv PROC_TRAPCAP_CTL_ENABLE
 446 Enable the
 447 .Dv SIGTRAP
 448 signal delivery on capability mode access violations.
 449 The enabled mode is inherited by the children of the process,
 450 and is kept after
 451 .Xr fexecve 2
 452 calls.
 453 .It Dv PROC_TRAPCAP_CTL_DISABLE
 454 Disable the signal delivery on capability mode access violations.
 455 Note that the global sysctl
 456 .Dv kern.trap_enotcap
 457 might still cause the signal to be delivered.
 458 See
 459 .Xr capsicum 4 .
 460 .El
 461 .Pp
 462 On signal delivery, the
 463 .Va si_errno
 464 member of the
 465 .Fa siginfo
 466 signal handler parameter is set to the syscall error value,
 467 and the
 468 .Va si_code
 469 member is set to
 470 .Dv TRAP_CAP .
 471 The system call number is stored in the
 472 .Va si_syscall
 473 field of the
 474 .Fa siginfo
 475 signal handler parameter.
 476 The other system call parameters can be read from the
 477 .Fa ucontext_t
 478 but the system call number is typically stored in the register
 479 that also contains the return value and so is unavailable in the
 480 signal handler.
 481 .Pp
 482 See
 483 .Xr capsicum 4
 484 for more information about the capability mode.
 485 .It Dv PROC_TRAPCAP_STATUS
 486 Return the current status of signalling capability mode access
 487 violations for the specified process.
 488 The integer value pointed to by the
 489 .Fa data
 490 argument is set to the
 491 .Dv PROC_TRAPCAP_CTL_ENABLE
 492 value if the process control enables signal delivery, and to
 493 .Dv PROC_TRAPCAP_CTL_DISABLE
 494 otherwise.
 495 .Pp
 496 See the note about sysctl
 497 .Dv kern.trap_enotcap
 498 above, which gives independent global control of signal delivery.
 499 .It Dv PROC_PDEATHSIG_CTL
 500 Request the delivery of a signal when the parent of the calling
 501 process exits.
 502 .Fa idtype
 503 must be
 504 .Dv P_PID
 505 and
 506 .Fa id
 507 must be the either caller's pid or zero, with no difference in effect.
 508 The value is cleared for child processes
 509 and when executing set-user-ID or set-group-ID binaries.
 510 .Fa data
 511 must point to a value of type
 512 .Vt int
 513 indicating the signal
 514 that should be delivered to the caller.
 515 Use zero to cancel a previously requested signal delivery.
 516 .It Dv PROC_PDEATHSIG_STATUS
 517 Query the current signal number that will be delivered when the parent
 518 of the calling process exits.
 519 .Fa idtype
 520 must be
 521 .Dv P_PID
 522 and
 523 .Fa id
 524 must be the either caller's pid or zero, with no difference in effect.
 525 .Fa data
 526 must point to a memory location that can hold a value of type
 527 .Vt int .
 528 If signal delivery has not been requested, it will contain zero
 529 on return.
 530 .It Dv PROC_STACKGAP_CTL
 531 Controls the stack gaps in the specified process.
 532 A stack gap is the part of the growth area for a
 533 .Dv MAP_STACK
 534 mapped region that is reserved and never filled by memory.
 535 Instead, the process is guaranteed to receive a
 536 .Dv SIGSEGV
 537 signal on accessing pages in the gap.
 538 Gaps protect against stack overflow corrupting memory adjacent
 539 to the stack.
 540 .Pp
 541 The
 542 .Fa data
 543 argument must point to an integer variable containing flags.
 544 The following flags are allowed:
 545 .Bl -tag -width PROC_STACKGAP_DISABLE_EXEC
 546 .It Dv PROC_STACKGAP_ENABLE
 547 This flag is only accepted for consistency with
 548 .Dv PROC_STACKGAP_STATUS .
 549 If stack gaps are enabled, the flag is ignored.
 550 If disabled, the flag causes an
 551 .Ev EINVAL
 552 error to be returned.
 553 After gaps are disabled in a process, they can only be re-enabled when an
 554 .Xr execve 2
 555 is performed.
 556 .It Dv PROC_STACKGAP_DISABLE
 557 Disable stack gaps for the process.
 558 For existing stacks, the gap is no longer a reserved part of the growth
 559 area and can be filled by memory on access.
 560 .It Dv PROC_STACKGAP_ENABLE_EXEC
 561 Enable stack gaps for programs started after an
 562 .Xr execve 2
 563 by the specified process.
 564 .It Dv PROC_STACKGAP_DISABLE_EXEC
 565 Inherit disabled stack gaps state after
 566 .Xr execve 2 .
 567 In other words, if the currently executing program has stack gaps disabled,
 568 they are kept disabled on exec.
 569 If gaps were enabled, they are kept enabled after exec.
 570 .El
 571 .Pp
 572 The stack gap state is inherited from the parent on
 573 .Xr fork 2 .
 574 .It Dv PROC_STACKGAP_STATUS
 575 Returns the current stack gap state for the specified process.
 576 .Fa data
 577 must point to an integer variable, which is used to return a bitmask
 578 consisting of the following flags:
 579 .Bl -tag -width PROC_STACKGAP_DISABLE_EXEC
 580 .It Dv PROC_STACKGAP_ENABLE
 581 Stack gaps are enabled.
 582 .It Dv PROC_STACKGAP_DISABLE
 583 Stack gaps are disabled.
 584 .It Dv PROC_STACKGAP_ENABLE_EXEC
 585 Stack gaps are enabled in the process after
 586 .Xr execve 2 .
 587 .It Dv PROC_STACKGAP_DISABLE_EXEC
 588 Stack gaps are disabled in the process after
 589 .Xr execve 2 .
 590 .El
 591 .It Dv PROC_NO_NEW_PRIVS_CTL
 592 Allows one to ignore the SUID and SGID bits on the program
 593 images activated by
 594 .Xr execve 2
 595 in the specified process and its future descendants.
 596 The
 597 .Fa data
 598 parameter must point to the integer variable holding the following
 599 value:
 600 .Bl -tag -width PROC_NO_NEW_PRIVS_ENABLE
 601 .It Dv PROC_NO_NEW_PRIVS_ENABLE
 602 Request SUID and SGID bits to be ignored.
 603 .El
 604 .Pp
 605 It is not possible to disable it once it has been enabled.
 606 .It Dv PROC_NO_NEW_PRIVS_STATUS
 607 Returns the current status of SUID/SGID enablement for the target process.
 608 The
 609 .Fa data
 610 parameter must point to the integer variable, where one of the
 611 following values is written:
 612 .Bl -tag -width PROC_NO_NEW_PRIVS_DISABLE
 613 .It Dv PROC_NO_NEW_PRIVS_ENABLE
 614 .It Dv PROC_NO_NEW_PRIVS_DISABLE
 615 .El
 616 .It Dv PROC_WXMAP_CTL
 617 Controls the 'write exclusive against execution' permissions for the
 618 mappings in the process address space.
 619 It overrides the global settings established by the
 620 .Dv kern.elf{32/64}.allow_wx
 621 sysctl,
 622 and the corresponding bit in the ELF control note, see
 623 .Xr elfctl 1 .
 624 .Pp
 625 The
 626 .Fa data
 627 parameter must point to the integer variable holding one of the
 628 following values:
 629 .Bl -tag -width PROC_WX_MAPPINGS_DISALLOW_EXEC
 630 .It Dv PROC_WX_MAPPINGS_PERMIT
 631 Enable creation of mappings that have both write and execute
 632 protection attributes, in the specified process' address space.
 633 .It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC
 634 In the new address space created by
 635 .Xr execve 2 ,
 636 disallow creation of mappings that have both write and execute
 637 permissions.
 638 .El
 639 .Pp
 640 Once creation of writeable and executable mappings is allowed,
 641 it is impossible (and pointless) to disallow it.
 642 The only way to ensure the absence of such mappings after they
 643 were enabled in a given process, is to set the
 644 .Dv PROC_WX_MAPPINGS_DISALLOW_EXEC
 645 flag and
 646 .Xr execve 2
 647 an image.
 648 .It Dv PROC_WXMAP_STATUS
 649 Returns the current status of the 'write exclusive against execution'
 650 enforcement for the specified process.
 651 The
 652 .Dv data
 653 parameter must point to the integer variable, where one of the
 654 following values is written:
 655 .Bl -tag -width PROC_WX_MAPPINGS_DISALLOW_EXEC
 656 .It Dv PROC_WX_MAPPINGS_PERMIT
 657 Creation of simultaneously writable and executable mapping is permitted,
 658 otherwise the process cannot create such mappings.
 659 .It Dv PROC_WX_MAPPINGS_DISALLOW_EXEC
 660 After
 661 .Xr execve 2 ,
 662 the new address space should disallow creation of simultaneously
 663 writable and executable mappings.
 664 .El
 665 .Pp
 666 Additionally, if the address space of the process disallows
 667 creation of simultaneously writable and executable mappings and
 668 it is guaranteed that no such mapping was created since address space
 669 creation, the
 670 .Dv PROC_WXORX_ENFORCE
 671 flag is set in the returned value.
 672 .El
 673 .Sh x86 MACHINE-SPECIFIC REQUESTS
 674 .Bl -tag -width PROC_KPTI_STATUS
 675 .It Dv PROC_KPTI_CTL
 676 AMD64 only.
 677 Controls the Kernel Page Table Isolation (KPTI) option for the children
 678 of the specified process.
 679 For the command to work, the
 680 .Va vm.pmap.kpti
 681 tunable must be enabled on boot.
 682 It is not possible to change the KPTI setting for a running process,
 683 except at the
 684 .Xr execve 2 ,
 685 where the address space is reinitialized.
 686 .Pp
 687 The
 688 .Fa data
 689 parameter must point to an integer variable containing one of the
 690 following commands:
 691 .Bl -tag -width PROC_KPTI_CTL_DISABLE_ON_EXEC
 692 .It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC
 693 Enable KPTI after
 694 .Xr execve 2 .
 695 .It Dv PROC_KPTI_CTL_DISABLE_ON_EXEC
 696 Disable KPTI after
 697 .Xr execve 2 .
 698 Only root or a process having the
 699 .Va PRIV_IO
 700 privilege might use this option.
 701 .El
 702 .It Dv PROC_KPTI_STATUS
 703 Returns the current KPTI status for the specified process.
 704 .Fa data
 705 must point to the integer variable, which returns the
 706 following statuses:
 707 .Bl -tag -width PROC_KPTI_CTL_DISABLE_ON_EXEC
 708 .It Dv PROC_KPTI_CTL_ENABLE_ON_EXEC
 709 .It Dv PROC_KPTI_CTL_DISABLE_ON_EXEC
 710 .El
 711 .Pp
 712 The status is or-ed with the
 713 .Va PROC_KPTI_STATUS_ACTIVE
 714 in case KPTI is active for the current address space of the process.
 715 .Sh NOTES
 716 Disabling tracing on a process should not be considered a security
 717 feature, as it is bypassable both by the kernel and privileged processes,
 718 and via other system mechanisms.
 719 As such, it should not be utilized to reliably protect cryptographic
 720 keying material or other confidential data.
 721 .Pp
 722 Note that processes can trivially bypass the 'no simultaneously
 723 writable and executable mappings' policy by first marking some mapping
 724 as writeable and write code to it, then removing write and adding
 725 execute permission.
 726 This may be legitimately required by some programs, such as JIT compilers.
 727 .Sh RETURN VALUES
 728 If an error occurs, a value of -1 is returned and
 729 .Va errno
 730 is set to indicate the error.
 731 .Sh ERRORS
 732 The
 733 .Fn procctl
 734 system call
 735 will fail if:
 736 .Bl -tag -width Er
 737 .It Bq Er EFAULT
 738 The
 739 .Fa data
 740 parameter points outside the process's allocated address space.
 741 .It Bq Er EINVAL
 742 The
 743 .Fa cmd
 744 argument specifies an unsupported command.
 745 .Pp
 746 The
 747 .Fa idtype
 748 argument specifies an unsupported identifier type.
 749 .It Bq Er EPERM
 750 The calling process does not have permission to perform the requested
 751 operation on any of the selected processes.
 752 .It Bq Er ESRCH
 753 No processes matched the requested
 754 .Fa idtype
 755 and
 756 .Fa id .
 757 .It Bq Er EINVAL
 758 An invalid operation or flag was passed in
 759 .Fa data
 760 for a
 761 .Dv PROC_SPROTECT
 762 command.
 763 .It Bq Er EPERM
 764 The
 765 .Fa idtype
 766 argument is not equal to
 767 .Dv P_PID ,
 768 or
 769 .Fa id
 770 is not equal to the pid of the calling process, for
 771 .Dv PROC_REAP_ACQUIRE
 772 or
 773 .Dv PROC_REAP_RELEASE
 774 requests.
 775 .It Bq Er EINVAL
 776 Invalid or undefined flags were passed to a
 777 .Dv PROC_REAP_KILL
 778 request.
 779 .It Bq Er EINVAL
 780 An invalid or zero signal number was requested for a
 781 .Dv PROC_REAP_KILL
 782 request.
 783 .It Bq Er EINVAL
 784 The
 785 .Dv PROC_REAP_RELEASE
 786 request was issued by the
 787 .Xr init 8
 788 process.
 789 .It Bq Er EBUSY
 790 The
 791 .Dv PROC_REAP_ACQUIRE
 792 request was issued by a process that had already acquired reaper status
 793 and has not yet released it.
 794 .It Bq Er EBUSY
 795 The
 796 .Dv PROC_TRACE_CTL
 797 request was issued for a process already being traced.
 798 .It Bq Er EPERM
 799 The
 800 .Dv PROC_TRACE_CTL
 801 request to re-enable tracing of the process
 802 .Po Dv PROC_TRACE_CTL_ENABLE Pc ,
 803 or to disable persistence of
 804 .Dv PROC_TRACE_CTL_DISABLE
 805 on
 806 .Xr execve 2
 807 was issued for a non-current process.
 808 .It Bq Er EINVAL
 809 The value of the integer
 810 .Fa data
 811 parameter for the
 812 .Dv PROC_TRACE_CTL
 813 or
 814 .Dv PROC_TRAPCAP_CTL
 815 request is invalid.
 816 .It Bq Er EINVAL
 817 The
 818 .Dv PROC_PDEATHSIG_CTL
 819 or
 820 .Dv PROC_PDEATHSIG_STATUS
 821 request referenced an unsupported
 822 .Fa id ,
 823 .Fa idtype
 824 or invalid signal number.
 825 .El
 826 .Sh SEE ALSO
 827 .Xr dtrace 1 ,
 828 .Xr proccontrol 1 ,
 829 .Xr protect 1 ,
 830 .Xr cap_enter 2 ,
 831 .Xr kill 2 ,
 832 .Xr ktrace 2 ,
 833 .Xr mmap 2 ,
 834 .Xr mprotect 2 ,
 835 .Xr ptrace 2 ,
 836 .Xr wait 2 ,
 837 .Xr capsicum 4 ,
 838 .Xr hwpmc 4 ,
 839 .Xr init 8
 840 .Sh HISTORY
 841 The
 842 .Fn procctl
 843 function appeared in
 844 .Fx 10.0 .
 845 .Pp
 846 The reaper facility is based on a similar feature of Linux and
 847 DragonflyBSD, and first appeared in
 848 .Fx 10.2 .
 849 .Pp
 850 The
 851 .Dv PROC_PDEATHSIG_CTL
 852 facility is based on the prctl(PR_SET_PDEATHSIG, ...) feature of Linux,
 853 and first appeared in
 854 .Fx 11.2 .
 855 .Pp
 856 The ASLR support was added to system for the checklists compliance in
 857 .Fx 13.0 .