usr/src/man/man9f/mac_alloc.9f

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2016 Joyent, Inc.
  13 .\"
  14 .Dd May 31, 2016
  15 .Dt MAC_ALLOC 9F
  16 .Os
  17 .Sh NAME
  18 .Nm mac_alloc ,
  19 .Nm mac_free
  20 .Nd allocate and free mac registration structures
  21 .Sh SYNOPSIS
  22 .In sys/mac_provider.h
  23 .Ft "mac_register_t *"
  24 .Fo mac_alloc
  25 .Fa "uint_t mac_version"
  26 .Fc
  27 .Ft void
  28 .Fo mac_free
  29 .Fa "mac_register_t *mregp"
  30 .Fc
  31 .Sh INTERFACE LEVEL
  32 illumos DDI specific
  33 .Sh PARAMETERS
  34 .Bl -tag -width Fa
  35 .It Fa mac_version
  36 An integer corresponding to the version of the MAC interface that the
  37 device driver was built against.
  38 .It Fa mregp
  39 A pointer to an allocated mac_register_t structure that was obtained
  40 from calling the
  41 .Fn mac_alloc
  42 function.
  43 .El
  44 .Sh DESCRIPTION
  45 The
  46 .Fn mac_alloc
  47 and
  48 .Fn mac_free
  49 routines are used to allocate and free the structures used to register a
  50 device driver with
  51 .Xr mac 9E .
  52 The device driver should call
  53 .Fn mac_alloc
  54 with the value of
  55 .Dv MAC_VERSION
  56 to indicate the current version of the MAC framework that it supports.
  57 The device driver will be returned an instance of a
  58 .Xr mac_register 9S
  59 structure which it can then use to call
  60 .Xr mac_register 9F .
  61 For more information on the order of events, see the
  62 .Sx Initializing MAC Support
  63 section of
  64 .Xr mac 9E .
  65 .Pp
  66 When the driver is done with the
  67 .Xr mac_register 9S
  68 structure, it must call the
  69 .Xr mac_free 9F
  70 function to release any associated memory.
  71 .Sh CONTEXT
  72 The
  73 .Fn mac_alloc
  74 and
  75 .Fn mac_free
  76 routines are generally called from the context of a device driver's
  77 .Xr attach 9E
  78 entry point; however, they may be called from both
  79 .Sy user
  80 and
  81 .Sy kernel
  82 context.
  83 .Sh RETURN VALUES
  84 Upon successful completion, the
  85 .Fn mac_register
  86 function will return a pointer to an allocated
  87 .Sy mac_register_t
  88 structure that can be filled in by the driver.
  89 Otherwise,
  90 .Dv NULL
  91 is returned to indicate that the structure could not be allocated.
  92 The most common cause for this is that the value of
  93 .Fa mac_version
  94 is not supported by the kernel.
  95 .Sh SEE ALSO
  96 .Xr attach 9E ,
  97 .Xr mac 9E ,
  98 .Xr mac_register 9F ,
  99 .Xr mac_register 9S