[thirdparty/openssl.git] / doc / man3 / SSL_set_fd.pod

=pod

=head1 NAME

SSL_set_fd, SSL_set_rfd, SSL_set_wfd - connect the SSL object with a file descriptor

=head1 SYNOPSIS

 #include <openssl/ssl.h>

 int SSL_set_fd(SSL *ssl, int fd);
 int SSL_set_rfd(SSL *ssl, int fd);
 int SSL_set_wfd(SSL *ssl, int fd);

=head1 DESCRIPTION

SSL_set_fd() sets the file descriptor B<fd> as the input/output facility
for the TLS/SSL (encrypted) side of B<ssl>. B<fd> will typically be the
socket file descriptor of a network connection.

When performing the operation, a B<socket BIO> is automatically created to
interface between the B<ssl> and B<fd>. The BIO and hence the SSL engine
inherit the behaviour of B<fd>. If B<fd> is nonblocking, the B<ssl> will
also have nonblocking behaviour.

When used on a QUIC connection SSL object, a B<datagram BIO> is automatically
created instead of a B<socket BIO>. These functions fail if called
on a QUIC stream SSL object.

If there was already a BIO connected to B<ssl>, BIO_free() will be called
(for both the reading and writing side, if different).

SSL_set_rfd() and SSL_set_wfd() perform the respective action, but only
for the read channel or the write channel, which can be set independently.

=head1 RETURN VALUES

The following return values can occur:

=over 4

=item Z<>0

The operation failed. Check the error stack to find out why.

=item Z<>1

The operation succeeded.

=back

=head1 NOTES

On Windows, a socket handle is a 64-bit data type (UINT_PTR), which leads to a
compiler warning (conversion from 'SOCKET' to 'int', possible loss of data) when
passing the socket handle to SSL_set_*fd(). For the time being, this warning can
safely be ignored, because although the Microsoft documentation claims that the
upper limit is INVALID_SOCKET-1 (2^64 - 2), in practice the current socket()
implementation returns an index into the kernel handle table, the size of which
is limited to 2^24.


=head1 SEE ALSO

L<SSL_get_fd(3)>, L<SSL_set_bio(3)>,
L<SSL_connect(3)>, L<SSL_accept(3)>,
L<SSL_shutdown(3)>, L<ssl(7)> , L<bio(7)>

=head1 COPYRIGHT

Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.

=cut
Commit	Line	Data
cc99526d RL	1	=pod
	2
	3	=head1 NAME
	4
aafbe1cc	5	SSL_set_fd, SSL_set_rfd, SSL_set_wfd - connect the SSL object with a file descriptor
cc99526d RL	6
	7	=head1 SYNOPSIS
	8
	9	#include <openssl/ssl.h>
	10
	11	int SSL_set_fd(SSL *ssl, int fd);
	12	int SSL_set_rfd(SSL *ssl, int fd);
	13	int SSL_set_wfd(SSL *ssl, int fd);
	14
	15	=head1 DESCRIPTION
	16
	17	SSL_set_fd() sets the file descriptor B<fd> as the input/output facility
1e4e5492	18	for the TLS/SSL (encrypted) side of B<ssl>. B<fd> will typically be the
cc99526d RL	19	socket file descriptor of a network connection.
	20
	21	When performing the operation, a B<socket BIO> is automatically created to
	22	interface between the B<ssl> and B<fd>. The BIO and hence the SSL engine
490c8711 GN	23	inherit the behaviour of B<fd>. If B<fd> is nonblocking, the B<ssl> will
490c8711 GN	24	also have nonblocking behaviour.
cc99526d	25
d6e7ebba HL	26	When used on a QUIC connection SSL object, a B<datagram BIO> is automatically
	27	created instead of a B<socket BIO>. These functions fail if called
	28	on a QUIC stream SSL object.
5e6015af	29
cc99526d RL	30	If there was already a BIO connected to B<ssl>, BIO_free() will be called
	31	(for both the reading and writing side, if different).
	32
1e4e5492 UM	33	SSL_set_rfd() and SSL_set_wfd() perform the respective action, but only
1e4e5492 UM	34	for the read channel or the write channel, which can be set independently.
cc99526d RL	35
	36	=head1 RETURN VALUES
	37
	38	The following return values can occur:
	39
	40	=over 4
	41
c8919dde	42	=item Z<>0
cc99526d RL	43
	44	The operation failed. Check the error stack to find out why.
	45
c8919dde	46	=item Z<>1
cc99526d RL	47
	48	The operation succeeded.
	49
	50	=back
	51
f8dd5869 DMSP	52	=head1 NOTES
	53
	54	On Windows, a socket handle is a 64-bit data type (UINT_PTR), which leads to a
	55	compiler warning (conversion from 'SOCKET' to 'int', possible loss of data) when
	56	passing the socket handle to SSL_set_*fd(). For the time being, this warning can
	57	safely be ignored, because although the Microsoft documentation claims that the
	58	upper limit is INVALID_SOCKET-1 (2^64 - 2), in practice the current socket()
	59	implementation returns an index into the kernel handle table, the size of which
	60	is limited to 2^24.
	61
	62
cc99526d RL	63	=head1 SEE ALSO
cc99526d RL	64
9b86974e RS	65	L<SSL_get_fd(3)>, L<SSL_set_bio(3)>,
9b86974e RS	66	L<SSL_connect(3)>, L<SSL_accept(3)>,
b97fdb57	67	L<SSL_shutdown(3)>, L<ssl(7)> , L<bio(7)>
cc99526d	68
e2f92610 RS	69	=head1 COPYRIGHT
e2f92610 RS	70
da1c088f	71	Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
e2f92610	72
4746f25a	73	Licensed under the Apache License 2.0 (the "License"). You may not use
e2f92610 RS	74	this file except in compliance with the License. You can obtain a copy
	75	in the file LICENSE in the source distribution or at
	76	L<https://www.openssl.org/source/license.html>.
	77
	78	=cut