share/man/man9/gone_in.9

   1 .\" Copyright (c) 2021 The FreeBSD Foundation
   2 .\"
   3 .\" This document was written by Ed Maste under sponsorhip from
   4 .\" The FreeBSD Foundation.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .Dd August 16, 2021
  27 .Dt GONE_IN 9
  28 .Os
  29 .Sh NAME
  30 .Nm gone_in ,
  31 .Nm gone_in_dev
  32 .Nd deprecation notice functions
  33 .Sh SYNOPSIS
  34 .In sys/systm.h
  35 .Ft void
  36 .Fn gone_in "int major" "const char *msg"
  37 .Ft void
  38 .Fn gone_in_dev "device_t dev" "int major" "const char *msg"
  39 .Sh DESCRIPTION
  40 The
  41 .Fn gone_in
  42 functions are used to provide a notice that the kernel is using a driver or
  43 some other functionality that is deprecated, and will be removed in a future
  44 .Fx
  45 release.
  46 The notice is sent to the kernel
  47 .Xr dmesg 8
  48 log and will appear on the console.
  49 The
  50 .Fa major
  51 argument specifies the major version of the
  52 .Fx
  53 release that will remove the deprecated functionality.
  54 .Pp
  55 In releases before
  56 .Fa major
  57 the deprecation notice states
  58 .Do
  59 Deprecated code (to be removed in FreeBSD
  60 .Fa major Ns ):
  61 .Fa msg
  62 .Dc .
  63 In releases equal to and after
  64 .Fa major
  65 the notice states
  66 .Do
  67 Obsolete code will be removed soon:
  68 .Fa msg
  69 .Dc .
  70 .Sh EXAMPLES
  71 .Bd -literal -offset indent
  72 void
  73 sample_init(void)
  74 {
  75         /* Initializaiton code omitted. */
  76
  77         gone_in(14, "Giant-locked filesystem");
  78 }
  79
  80 int
  81 example_driver_attach(struct example_driver_softc *sc)
  82 {
  83         /* Attach code omitted. */
  84
  85         gone_in_dev(sc->dev, 14, "Giant-locked driver");
  86 }
  87 .Ed
  88 .Sh HISTORY
  89 The
  90 .Nm
  91 functions first appeared in
  92 .Fx 11 .