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_CONNECT(3) DragonFly Library Functions Manual TLS_CONNECT(3)
NAME
tls_connect, tls_connect_fds, tls_connect_servername, tls_connect_socket,
tls_connect_cbs -- instruct a TLS client to establish a connection
SYNOPSIS
#include <tls.h>
int
tls_connect(struct tls *ctx, const char *host, const char *port);
int
tls_connect_fds(struct tls *ctx, int fd_read, int fd_write,
const char *servername);
int
tls_connect_servername(struct tls *ctx, const char *host,
const char *port, const char *servername);
int
tls_connect_socket(struct tls *ctx, int s, const char *servername);
int
tls_connect_cbs(struct tls *ctx,
ssize_t (*tls_read_cb)(struct tls *ctx, void *buf, size_t buflen, void *cb_arg),
ssize_t (*tls_write_cb)(struct tls *ctx, const void *buf, size_t buflen, void *cb_arg),
void *cb_arg, const char *servername);
DESCRIPTION
After creating a TLS client context with tls_client(3) and configuring it
with tls_configure(3), a client connection is initiated by calling
tls_connect(). This function will create a new socket, connect to the
specified host and port, and then establish a secure connection. The
port may be numeric or a service name. If it is NULL, then a host of the
format "hostname:port" is permitted. The name to use for verification is
inferred from the host value.
The tls_connect_servername() function has the same behaviour, however the
name to use for verification is explicitly provided, for the case where
the TLS server name differs from the DNS name.
An already existing socket can be upgraded to a secure connection by
calling tls_connect_socket().
Alternatively, a secure connection can be established over a pair of
existing file descriptors by calling tls_connect_fds().
Calling tls_connect_cbs() allows read and write callback functions to
handle data transfers. The specified cb_arg parameter is passed back to
the functions, and can contain a pointer to any caller-specified data.
RETURN VALUES
These functions return 0 on success or -1 on error.
SEE ALSO
tls_accept_socket(3), tls_client(3), tls_close(3),
tls_config_ocsp_require_stapling(3), tls_configure(3), tls_handshake(3),
tls_init(3)
HISTORY
tls_connect() and tls_connect_socket() appeared in OpenBSD 5.6 and got
their final names in OpenBSD 5.7.
tls_connect_fds() and tls_connect_servername() appeared in OpenBSD 5.7
and tls_connect_cbs() in OpenBSD 6.1.
AUTHORS
Joel Sing <jsing@openbsd.org>
Reyk Floeter <reyk@openbsd.org>
tls_connect_cbs() was written by Tobias Pape <tobias@netshed.de>.
DragonFly 5.5 July 9, 2018 DragonFly 5.5