DragonFly On-Line Manual Pages
TLS(2) DragonFly System Calls Manual TLS(2)
NAME
set_tls_area, get_tls_area -- kernel TLS (thread local storage) support
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/tls.h>
int
set_tls_area(int which, struct tls_info *info, size_t infosize);
int
get_tls_area(int which, struct tls_info *info, size_t infosize);
DESCRIPTION
The set_tls_area() system call creates an entry for the TLS facility
which representing thread local storage as specified by the info
structure. A descriptor representing the facility is returned, or -1 if
an error occurred. The facility may be cleared by specifying a NULL
pointer and an infosize of 0. The get_tls_area() system call retrieves
the requested TLS facility. A descriptor representing the facility is
returned, or -1 if an error occurred. If you simply want the descriptor
you may specify a NULL pointer and an infosize of 0.
The returned descriptor and the TLS mechanism is machine-dependent. On
IA32 three global segment descriptors are supported (0, 1, and 2) and
the %gs load value is returned.
The tls_info structure passed to set_tls_area() should first be zerod (to
remain compatible with future extensions) and then initialized.
struct tls_info {
void *base; /* base address of TLS area */
int size; /* size of TLS area in bytes */
};
The actual implementation of the area is machine-dependent. If the
kernel is unable to accommodate the supplied size it may create a larger
area. If the kernel is unable to accommodate the supplied base address
an error will be returned.
RETURN VALUES
A return value of 0 is returned on success, -1 on error.
EXAMPLES
/*
* Pseudo example showing how the TLS system calls work on IA32.
*/
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
#include <errno.h>
#include <sys/tls.h>
int X;
static int getdata(int offset);
int
main(int ac, char **av)
{
int i;
int gs;
struct tls_info info;
info.base = &X;
info.size = sizeof(X);
if ((gs = set_tls_area(0, &info, sizeof(info))) < 0) {
perror("setarea");
exit(1);
}
printf("gs = %04x\n", gs);
__asm __volatile("mov %0,%%gs" : : "g" (gs) );
if (get_tls_area(0, &info, sizeof(info)) < 0) {
perror("getarea");
exit(1);
}
printf("%p/%d\n", info.base, info.size);
X = 1;
printf("should be 1: %d\n", getdata(0));
X = 2;
printf("should be 2: %d\n", getdata(0));
printf("this should fault:\n");
fflush(stdout);
getdata(4);
return(0);
}
static int
getdata(int offset)
{
int rv;
__asm __volatile("movl %%gs:(%0),%%eax; movl %%eax,%1" : "+r" (offset) : "m"
(rv) : "ax");
return (rv);
}
ERRORS
[ERANGE] The specified facility index, which, is not supported.
[EINVAL] An invalid parameter has been specified.
[ENOENT] (get_tls_area) The specified facility has not been
initialized with sys_set_tls_area().
SEE ALSO
umtx(2)
HISTORY
The set_tls_area(), and get_tls_area() function calls first appeared in
DragonFly 1.1.
DragonFly 5.5 February 21, 2005 DragonFly 5.5
TLS_INIT(3) DragonFly Library Functions Manual TLS_INIT(3)
NAME
tls_init, tls_config_new, tls_config_free, tls_config_error -- initialize
TLS client and server API
SYNOPSIS
#include <tls.h>
int
tls_init(void);
struct tls_config *
tls_config_new(void);
void
tls_config_free(struct tls_config *config);
const char *
tls_config_error(struct tls_config *config);
DESCRIPTION
The tls family of functions establishes a secure communications channel
using the TLS socket protocol. Both clients and servers are supported.
The tls_init() function initializes global data structures. It is no
longer necessary to call this function directly, since it is invoked
internally when needed. It may be called more than once, and may be
called concurrently.
Before a connection is created, a configuration must be created. The
tls_config_new() function allocates, initializes, and returns a new
default configuration object that can be used for future connections.
Several functions exist to change the options of the configuration; see
tls_config_set_protocols(3), tls_load_file(3),
tls_config_ocsp_require_stapling(3), and tls_config_verify(3).
The tls_config_error() function may be used to retrieve a string contain-
ing more information about the most recent error relating to a configura-
tion.
A TLS connection object is created by tls_client(3) or tls_server(3) and
configured with tls_configure(3).
A client connection is initiated after configuration by calling
tls_connect(3). A server can accept a new client connection by calling
tls_accept_socket(3) on an already established socket connection.
Two functions are provided for input and output, tls_read(3) and
tls_write(3). Both automatically perform the tls_handshake(3) when
needed.
The properties of established TLS connections can be inspected with the
functions described in tls_conn_version(3) and
tls_ocsp_process_response(3).
After use, a TLS connection should be closed with tls_close(3) and then
freed by calling tls_free(3).
When no more contexts are to be configured, the configuration object
should be freed by calling tls_config_free(). It is safe to call
tls_config_free() as soon as the final call to tls_configure() has been
made. If config is NULL, no action occurs.
RETURN VALUES
tls_init() returns 0 on success or -1 on error.
tls_config_new() returns NULL on error or an out of memory condition.
tls_config_error() returns NULL if no error occurred with config at all,
or if memory allocation failed while trying to assemble the string
describing the most recent error related to config.
SEE ALSO
tls_accept_socket(3), tls_client(3), tls_config_ocsp_require_stapling(3),
tls_config_set_protocols(3), tls_config_verify(3), tls_conn_version(3),
tls_connect(3), tls_load_file(3), tls_ocsp_process_response(3),
tls_read(3)
HISTORY
The tls API first appeared in OpenBSD 5.6 as a response to the unneces-
sary challenges other APIs present in order to use them safely.
All functions were renamed from ressl_*() to tls_*() for OpenBSD 5.7.
tls_config_error() appeared in OpenBSD 6.0.
AUTHORS
Joel Sing <jsing@openbsd.org>
Ted Unangst <tedu@openbsd.org>
Many others contributed to various parts of the library; see the individ-
ual manual pages for more information.
CAVEATS
The function tls_config_error() returns an internal pointer. It must not
be freed by the application, or a double free error will occur. The
pointer will become invalid when the next error occurs with config. Con-
sequently, if the application may need the message at a later time, it
has to copy the string before calling the next libtls function involving
config, or a segmentation fault or read access to unintended data is the
likely result.
DragonFly 5.5 July 9, 2018 DragonFly 5.5