man/Tss2_TctiLdr_Initialize.3.in

.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH Tss2_TctiLdr_Initialize 3 "MARCH 2019" "TPM2 Software Stack"
.SH NAME
Tss2_TctiLdr_Initialize, Tss2_TctiLdr_Initialize_Ex \- Instantiate and
initialize a TCTI context.
.SH SYNOPSIS
.B #include <tss2/tss2_tctildr.h>
.sp
.sp
.BI "TSS2_RC Tss2_TctiLdr_Initialize (const char " "*nameConf" ", TSS2_TCTI_CONTEXT " "**context" ");"
.sp
.BI "TSS2_RC Tss2_TctiLdr_Initialize_Ex (const char " "*name" ", const char " "*conf" ", TSS2_TCTI_CONTEXT " "**context" ");"
.sp
.SH DESCRIPTION
The
.BR Tss2_TctiLdr_Initialize ()
and
.BR Tss2_TctiLdr_Initialize_Ex ()
functions initialize a TCTI context used to communicate with the TPM2 or
some intermediate component in the TCG TPM2 software stack.
.sp
.BR Tss2_TctiLdr_Initialize ()
takes a single string that encodes both the name of the TCTI library the
caller wishes to instantiate and its desired configuration in the
.I nameConf
parameter.
.I nameConf
is a string comprised of two substrings:
.I name
and
.I conf
parameters respectively.
These substrings are combined with
.I name
first, separated by a single ':' / colon character: 'name:conf'. Consult
the section titled TCTI CONFIG for information about the encoding of these
strings.
The
.I context
parameter is used to return a reference to the TCTI context created by
the function.
.sp
.BR Tss2_TctiLdr_Initialize_Ex ()
behaves identically to the
.BR Tss2_TctiLdr_Initialize ()
function with the exception that the TCTI name and configuration are passed
as separate strings. The encoding of these strings is described in section
TCTI_CONFIG.
.SH TCTI CONFIG
If the
.I name
string is NULL or the emptry string then the initialization functions will
select a default TCTI appropriate for the platform. On Linux this means
first trying to load a library named
.I libtss2-tcti-default.so.
This is a placeholder for distros to provide a distro specific default. It
is recommended that this be a symlink to another installed TCTI library.
If attempts to load this shared object fails the implementation will
attempt known TCTIs in the following order:
.IP \[bu] 2
libtss2-tcti-tabrmd.so.0
.IP \[bu]
libtss2-tcti-device.so.0
.IP \[bu]
libtss2-tcti-mssim.so.0
.RE
.sp
When the
.I name
string is neither NULL nor the empty string the implementation will attempt
to
.I dlopen
a library with the given name. If this fails then the implementation assumes
it has been passed a shortened name and will attempt to load libraries by
name with the following permutations:
.IP \[bu] 2
<name>
.IP \[bu]
libtss2-tcti-<name>.so.0
.IP \[bu]
libtss2-tcti-<name>.so
.RE
.sp
The
.I config
string is not interpreted by the TctiLdr init functions and is passed
unaltered to the initialization function for the selected TCTI. The
format for this string is TCTI specific.
.sp
The
.BR Tss2_TctiLdr_Initialize
function is passed the
.I name
and
.I conf
strings as a single parameter. In this case the
.I name
and
.I conf
strings are concatinated with a single ':' / colon character separating them.
.sp
For a more thorough discussion of the TCTILDR API see the \*(lqTCG TSS 2.0 TPM Command
Transmission Interface (TCTI) API Specification\*(rq.
.SH RETURN VALUE
A successful call to this function will return
.B TSS2_RC_SUCCESS.
An unsuccessful call will produce a response code described in section
.B ERRORS.
.SH ERRORS
.B TSS2_TCTI_RC_MEMORY
is returned if memory allocation fails
.sp
.B TSS2_TCTI_RC_NOT_SUPPORTED
is returned when the loader is unable to locate a TCTI library with the
provided
.I name
.sp
.B TSS2_TCTI_RC_IO_ERROR
is returned if a failure occurs in the underlying library loading mechanism
.sp
.B TSS2_TCTI_RC_BAD_REFERENCE
is returned if the
.I tctiContext
parameter is NULL
.sp
.SH EXAMPLE
Example code.
.sp
.nf
#include <inttypes.h>
#include <stdlib.h>
#include <stdio.h>
#include <tss2/tss2_tctildr.h>

TSS2_TCTI_CONTEXT *ctx = NULL;
TSS2_RC rc = Tss2_TctiLdr_Initialize (NULL, &ctx);
if (rc != TSS2_RC_SUCCESS) {
    fprintf (stderr, "Initialization of default TCTI context failed with "
             "response code: 0x%" PRIx32 "\n", rc);
    exit (EXIT_FAILURE);
}
exit (EXIT_SUCCESS);
.fi