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