lib/libc/sys/setfib.2

   1 .\" Copyright (c) 2008 Cisco Systems.  All rights reserved.
   2 .\"    Author: Julian Elischer
   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. Neither the name of the Cisco Systems nor the names of its employees
  10 .\"    may be used to endorse or promote products derived from this software
  11 .\"    without specific prior written permission.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``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 AUTHORS 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 March 19, 2012
  28 .Dt SETFIB 2
  29 .Os
  30 .Sh NAME
  31 .Nm setfib
  32 .Nd set the default FIB (routing table) for the calling process.
  33 .Sh LIBRARY
  34 .Lb libc
  35 .Sh SYNOPSIS
  36 .In sys/socket.h
  37 .Ft int
  38 .Fn setfib "int fib"
  39 .Sh DESCRIPTION
  40 The
  41 .Fn setfib
  42 system call sets the associated fib for all sockets opened
  43 subsequent to the call, to be that of the argument
  44 .Fa fib .
  45 The
  46 .Fa fib
  47 argument
  48 must be greater than or equal to 0
  49 and less than the current system maximum which
  50 may be retrieved by the
  51 .Va net.fibs
  52 sysctl.
  53 The system maximum is set in the kernel configuration file with
  54 .Bd -ragged -offset indent
  55 .Cd "options ROUTETABLES=" Ns Em N
  56 .Ed
  57 .Pp
  58 or in
  59 .Pa /boot/loader.conf
  60 with
  61 .Pp
  62 .Dl net.fibs= Ns Qq Em N
  63 .Pp
  64 where
  65 .Em N
  66 is an integer.
  67 This maximum is capped at 65536 due to the implementation storing
  68 the fib number in a 16-bit field in the
  69 .Xr mbuf 9
  70 packet header, however it is not suggested that one use such a large number
  71 as memory is allocated for every FIB regardless of whether it is used, and
  72 there are places where all FIBs are iterated over.
  73 .Pp
  74 The default fib of the process will be applied to all protocol families
  75 that support multiple fibs, and ignored by those that do not.
  76 The default fib for a process may be overridden for a socket with the use
  77 of the
  78 .Dv SO_SETFIB
  79 socket option.
  80 .Sh RETURN VALUES
  81 .Rv -std setfib
  82 .Sh ERRORS
  83 The
  84 .Fn setfib
  85 system call
  86 will fail and no action will be taken and return
  87 .Er EINVAL
  88 if the
  89 .Fa fib
  90 argument is greater than the current system maximum.
  91 .Sh SEE ALSO
  92 .Xr setfib 1 ,
  93 .Xr setsockopt 2
  94 .Sh STANDARDS
  95 The
  96 .Fn setfib
  97 system call is a
  98 .Fx
  99 extension however similar extensions
 100 have been added to many other
 101 .Ux
 102 style kernels.
 103 .Sh HISTORY
 104 The
 105 .Fn setfib
 106 function appeared in
 107 .Fx 7.1 .