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 2019 Joyent, Inc. 13.\" 14.Dd July 22, 2019 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 32illumos DDI specific 33.Sh PARAMETERS 34.Bl -tag -width Fa 35.It Fa mac_version 36An integer corresponding to the version of the MAC interface that the 37device driver was built against. 38.It Fa mregp 39A pointer to an allocated mac_register_t structure that was obtained 40from calling the 41.Fn mac_alloc 42function. 43.El 44.Sh DESCRIPTION 45The 46.Fn mac_alloc 47and 48.Fn mac_free 49routines are used to allocate and free the structures used to register a 50device driver with 51.Xr mac 9E . 52The device driver should call 53.Fn mac_alloc 54with the value of 55.Dv MAC_VERSION 56to indicate the current version of the MAC framework that it supports. 57The device driver will be returned an instance of a 58.Xr mac_register 9S 59structure which it can then use to call 60.Xr mac_register 9F . 61For more information on the order of events, see the 62.Sx Initializing MAC Support 63section of 64.Xr mac 9E . 65.Pp 66When the driver is done with the 67.Xr mac_register 9S 68structure, it must call the 69.Fn mac_free 70function to release any memory associated with the handle. 71.Pp 72After the driver has called 73.Xr mac_register 9F 74during its 75.Xr attach 9E 76entry point, the 77.Xr mac_register 9S 78structure is no longer needed and can be freed. 79.Sh CONTEXT 80The 81.Fn mac_alloc 82and 83.Fn mac_free 84routines are generally called from the context of a device driver's 85.Xr attach 9E 86entry point; however, they may be called from both 87.Sy user 88and 89.Sy kernel 90context. 91.Sh RETURN VALUES 92Upon successful completion, the 93.Fn mac_alloc 94function will return a pointer to an allocated 95.Sy mac_register_t 96structure that can be filled in by the driver. 97Otherwise, 98.Dv NULL 99is returned to indicate that the structure could not be allocated. 100The most common cause for this is that the value of 101.Fa mac_version 102is not supported by the kernel. 103.Sh SEE ALSO 104.Xr attach 9E , 105.Xr mac 9E , 106.Xr mac_register 9F , 107.Xr mac_register 9S 108