'\" te
.\" Copyright (c) 2015, Oracle and/or its affiliates. All rights
.\"        reserved.
.TH adi 2 "22 Sep 2015" "SunOS 5.11" "System Calls"
.SH NAME
adi, adi_set_enabled, adi_get_enabled, adi_blksz, adi_version_max, adi_version_nbits \- Application Data Integrity operations
.SH SYNOPSIS
.LP
.nf
#include <adi.h>



int adi_set_enabled(int arg);



int adi_get_enabled(void);



int adi_blksz(void);



int adi_version_max(void);



int adi_version_nbits(void);
.fi

.SH DESCRIPTION
.sp
.LP
Applications can use the functions described in this section to disable, enable, or query the per-thread state of Application Data Integrity (ADI), and to determine the system constants used to provide the ADI feature. See the \fBadi\fR(3C) man page for additional information on the ADI feature.
.sp
.LP
The \fBadi_set_enabled()\fR function sets the state of ADI for the calling thread. The value of \fIarg\fR can be either \fBADI_DISABLE\fR or \fBADI_ENABLE\fR, to disable or enable ADI respectively.
.sp
.LP
The \fBadi_get_enabled()\fR function returns the current state of ADI for the calling thread.
.sp
.LP
The \fBadi_blksz()\fR function returns the \fBgranularity\fR of ADI versioning supported by the platform. \fBgranularity\fR can be used to determine the optimal alignment for the address and size arguments, when calling the \fBadi_clr_version\fR(3C), \fBadi_set_version\fR(3C), or \fBadi_memset\fR(3C) functions.
.sp
.LP
The \fBadi_version_max()\fR function returns the maximum value an application may use for an ADI version tag. This value can be used to determine the maximum value for the \fIversion\fR argument when calling the \fBadi_set_version\fR(3C) or \fBadi_memset\fR(3C) functions.
.sp
.LP
The \fBadi_version_nbits()\fR function returns the number of bits used in a 64-bit virtual address to represent an ADI version tag. To create a versioned address, set the upper \fBnbits\fR in an address to the version. To normalize a versioned address, clear the upper \fBnbits\fR and sign-extend the highest non-versioned bit as shown in the "Examples" section.
.SH RETURN VALUES
.sp
.LP
The \fBadi_set_enabled()\fR function returns the previous state of ADI for the calling thread. On error, this function returns \fB-1\fR and sets \fBerrno\fR.
.sp
.LP
The \fBadi_get_enabled()\fR function returns the current state of ADI for the calling thread. On error, this function returns \fB-1\fR and sets \fBerrno\fR.
.sp
.LP
The \fBadi_blksz()\fR function returns the granularity of ADI versioning supported by the platform in bytes. On error, this function returns \fB-1\fR and sets \fBerrno\fR.
.sp
.LP
The \fBadi_version_max()\fR function returns the maximum value an application may use for an ADI version tag. On error, this function returns \fB-1\fR and sets \fBerrno\fR.
.sp
.LP
The \fBadi_version_nbits()\fR function returns the number of bits used in a 64-bit virtual address to represent an ADI version tag. On error, this function returns \fB-1\fR and sets \fBerrno\fR.
.SH ERRORS
.sp
.LP
All adi(2) family functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBENOTSUP\fR\fR
.ad
.RS 11n
.rt  
.RS +4
.TP
.ie t \(bu
.el o
ADI is not supported by the platform.
.RE
.RS +4
.TP
.ie t \(bu
.el o
ADI is not supported for 32-bit processes.
.RE
.RE

.sp
.LP
The \fBadi_set_enabled()\fR function will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
The argument is invalid.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRNormalizing a Versioned Address
.sp
.LP
The following example shows how you can normalize a versioned address by clearing the upper \fBnbits\fR and sign-extending the highest non-versioned bit:

.sp
.in +2
.nf
#include <sys/types.h>

#include <adi.h>



void adi_function(caddr_t addr, int version)

{

       int nbits = adi_version_nbits();

       int shift = 64 - nbits;

       caddr_t versioned_addr;

       caddr_t normal_addr;



       /*

        * Create a versioned address.

        */

       versioned_addr = (caddr_t) ((version << shift) |

           ((((unsigned long)addr) << nbits) >> nbits));



       /*

        * Extract the version from a versioned address.

        */

       version = ((unsigned long)versioned_addr) >> shift;



       /*

        * Remove the version and normalize an address.

        */

       normal_addr = (caddr_t) (((((long)versioned_addr) << nbits) >> nbits));

}
.fi
.in -2
.sp

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityVolatile
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBstandards\fR(5), \fBadi\fR(3C)