usr.bin/numactl/numactl.1

   1 .\" Copyright (c) 2015 Adrian Chadd <adrian@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd May 9, 2015
  28 .Dt NUMACTL 1
  29 .Os
  30 .Sh NAME
  31 .Nm numactl
  32 .Nd "manage NUMA policy configuration"
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl l Ar policy
  36 .Op Fl m Ar domain
  37 .Op Fl c Ar domain
  38 .Ar cmd ...
  39 .Nm
  40 .Fl g
  41 .Op Fl p Ar pid
  42 .Op Fl t Ar tid
  43 .Nm
  44 .Fl s
  45 .Op Fl l Ar policy
  46 .Op Fl m Ar domain
  47 .Op Fl c Ar domain
  48 .Op Fl p Ar pid
  49 .Op Fl t Ar tid
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 command can be used to assign NUMA policies to processes/threads,
  54 run commands with a given NUMA policy, and query information
  55 about NUMA policies on running processes.
  56 .Pp
  57 .Nm
  58 requires a target to modify or query.
  59 The target may be specified as a command, process id or a thread id.
  60 Using
  61 .Fl -get
  62 the target's NUMA policy may be queried.
  63 Using
  64 .Fl -set
  65 the target's NUMA policy may be queried.
  66 If no target is specified,
  67 .Nm
  68 operates on itself.
  69 Not all combinations of operations and targets are supported.
  70 For example,
  71 you may not set the id of an existing set or query and launch a command
  72 at the same time.
  73 .Pp
  74 Each process and thread has a NUMA policy.
  75 By default the policy is NONE.
  76 If a thread policy is NONE, then the policy will fall back to the process.
  77 If the process policy is NONE, then the policy will fall back to the
  78 system default.
  79 The policy may be queried by using
  80 .Fl -get.
  81 .Pp
  82 The options are as follows:
  83 .Bl -tag -width ".Fl -cpudomain Ar domain"
  84 .It Fl -cpudomain Ar domain , Fl c Ar domain
  85 Set the given CPU scheduling policy.
  86 Constrain the object (tid, pid, command) to run on CPUs
  87 that belong to the given domain.
  88 .It Fl -get , Fl g
  89 Retrieve the NUMA policy for the given thread or process id.
  90 .It Fl -set , Fl s
  91 Set the NUMA policy for the given thread or process id.
  92 .It Fl -memdomain Ar domain , Fl m Ar domain
  93 Constrain the object (tid, pid, command) to the given
  94 domain.
  95 This is only valid for fixed-domain and fixed-domain-rr.
  96 It must not be set for other policies.
  97 .It Fl -mempolicy Ar policy , Fl l Ar policy
  98 Set the given memory allocation policy.
  99 Valid policies are none, rr, fixed-domain, fixed-domain-rr,
 100 first-touch, and first-touch-rr.
 101 A memdomain argument is required for fixed-domain and
 102 fixed-domain-rr.
 103 .It Fl -pid Ar pid , Fl p Ar pid
 104 Operate on the given pid.
 105 .It Fl -tid Ar tid , Fl t Ar tid
 106 Operate on the given tid.
 107 .El
 108 .Sh EXIT STATUS
 109 .Ex -std
 110 .Sh EXAMPLES
 111 Create a
 112 .Pa /bin/sh
 113 process with memory coming from domain 0, but
 114 CPUs coming from domain 1:
 115 .Dl numactl --mempolicy=fixed-domain --memdomain=0 --cpudomain=1 /bin/sh
 116 .Pp
 117 Query the NUMA policy for the
 118 .Aq sh pid :
 119 .Dl numactl --get --pid=<sh pid>
 120 .Pp
 121 Set the NUMA policy for the given TID to round-robin:
 122 .Dl numactl --set --mempolicy=rr --tid=<tid>
 123 .Sh SEE ALSO
 124 .Xr cpuset 2 ,
 125 .Xr numa 4
 126 .Sh HISTORY
 127 The
 128 .Nm
 129 command first appeared in
 130 .Fx 11.0 .
 131 .Sh AUTHORS
 132 .An Adrian Chadd Aq Mt adrian@FreeBSD.org