include/boost/corosio/socket_option.hpp

93.2% Lines (41/44) 100.0% List of functions (20/20)

[ ] prev/next file n p prev/next uncovered line

f(x) Functions (20)

Function Calls Lines Blocks

Line	Hits	Source Code
1		//
2		// Copyright (c) 2026 Steve Gerbino
3		//
4		// Distributed under the Boost Software License, Version 1.0. (See accompanying
5		// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6		//
7		// Official repository: https://github.com/cppalliance/corosio
8		//
9
10		#ifndef BOOST_COROSIO_SOCKET_OPTION_HPP
11		#define BOOST_COROSIO_SOCKET_OPTION_HPP
12
13		#include <boost/corosio/detail/config.hpp>
14		#include <boost/corosio/ipv4_address.hpp>
15		#include <boost/corosio/ipv6_address.hpp>
16
17		#include <cstddef>
18
19		/** @file socket_option.hpp
20
21		Type-erased socket option types that avoid platform-specific
22		headers. The protocol level and option name for each type are
23		resolved at link time via the compiled library.
24
25		For an inline (zero-overhead) alternative that includes platform
26		headers, use `<boost/corosio/native/native_socket_option.hpp>`
27		(`boost::corosio::native_socket_option`).
28
29		Both variants satisfy the same option-type interface and work
30		interchangeably with `tcp_socket::set_option` /
31		`tcp_socket::get_option` and the corresponding acceptor methods.
32
33		@see native_socket_option
34		*/
35
36		namespace boost::corosio::socket_option {
37
38		/** Base class for concrete boolean socket options.
39
40		Stores a boolean as an `int` suitable for `setsockopt`/`getsockopt`.
41		Derived types provide `level()` and `name()` for the specific option.
42		*/
43		class boolean_option
44		{
45		int value_ = 0;
46
47		public:
48		/// Construct with default value (disabled).
49		boolean_option() = default;
50
51		/** Construct with an explicit value.
52
53		@param v `true` to enable the option, `false` to disable.
54		*/
55	1245x	explicit boolean_option(bool v) noexcept : value_(v ? 1 : 0) {}
56
57		/// Assign a new value.
58	4x	boolean_option& operator=(bool v) noexcept
59		{
60	4x	value_ = v ? 1 : 0;
61	4x	return *this;
62		}
63
64		/// Return the option value.
65	44x	bool value() const noexcept
66		{
67	44x	return value_ != 0;
68		}
69
70		/// Return the option value.
71	4x	explicit operator bool() const noexcept
72		{
73	4x	return value_ != 0;
74		}
75
76		/// Return the negated option value.
77	4x	bool operator!() const noexcept
78		{
79	4x	return value_ == 0;
80		}
81
82		/// Return a pointer to the underlying storage.
83	46x	void* data() noexcept
84		{
85	46x	return &value_;
86		}
87
88		/// Return a pointer to the underlying storage.
89	1247x	void const* data() const noexcept
90		{
91	1247x	return &value_;
92		}
93
94		/// Return the size of the underlying storage.
95	1293x	std::size_t size() const noexcept
96		{
97	1293x	return sizeof(value_);
98		}
99
100		/** Normalize after `getsockopt` returns fewer bytes than expected.
101
102		Windows Vista+ may write only 1 byte for boolean options.
103
104		@param s The number of bytes actually written by `getsockopt`.
105		*/
106	46x	void resize(std::size_t s) noexcept
107		{
108	46x	if (s == sizeof(char))
109	✗	value_ = reinterpret_cast<unsigned char>(&value_) ? 1 : 0;
110	46x	}
111		};
112
113		/** Base class for concrete integer socket options.
114
115		Stores an integer suitable for `setsockopt`/`getsockopt`.
116		Derived types provide `level()` and `name()` for the specific option.
117		*/
118		class integer_option
119		{
120		int value_ = 0;
121
122		public:
123		/// Construct with default value (zero).
124		integer_option() = default;
125
126		/** Construct with an explicit value.
127
128		@param v The option value.
129		*/
130	14x	explicit integer_option(int v) noexcept : value_(v) {}
131
132		/// Assign a new value.
133	2x	integer_option& operator=(int v) noexcept
134		{
135	2x	value_ = v;
136	2x	return *this;
137		}
138
139		/// Return the option value.
140	24x	int value() const noexcept
141		{
142	24x	return value_;
143		}
144
145		/// Return a pointer to the underlying storage.
146	22x	void* data() noexcept
147		{
148	22x	return &value_;
149		}
150
151		/// Return a pointer to the underlying storage.
152	14x	void const* data() const noexcept
153		{
154	14x	return &value_;
155		}
156
157		/// Return the size of the underlying storage.
158	36x	std::size_t size() const noexcept
159		{
160	36x	return sizeof(value_);
161		}
162
163		/** Normalize after `getsockopt` returns fewer bytes than expected.
164
165		@param s The number of bytes actually written by `getsockopt`.
166		*/
167	22x	void resize(std::size_t s) noexcept
168		{
169	22x	if (s == sizeof(char))
170	✗	value_ =
171	✗	static_cast<int>(reinterpret_cast<unsigned char>(&value_));
172	22x	}
173		};
174
175		/** Disable Nagle's algorithm (TCP_NODELAY).
176
177		@par Example
178		@code
179		sock.set_option( socket_option::no_delay( true ) );
180		auto nd = sock.get_option<socket_option::no_delay>();
181		if ( nd.value() )
182		// Nagle's algorithm is disabled
183		@endcode
184		*/
185		class BOOST_COROSIO_DECL no_delay : public boolean_option
186		{
187		public:
188		using boolean_option::boolean_option;
189		using boolean_option::operator=;
190
191		/// Return the protocol level.
192		static int level() noexcept;
193
194		/// Return the option name.
195		static int name() noexcept;
196		};
197
198		/** Enable periodic keepalive probes (SO_KEEPALIVE).
199
200		@par Example
201		@code
202		sock.set_option( socket_option::keep_alive( true ) );
203		@endcode
204		*/
205		class BOOST_COROSIO_DECL keep_alive : public boolean_option
206		{
207		public:
208		using boolean_option::boolean_option;
209		using boolean_option::operator=;
210
211		/// Return the protocol level.
212		static int level() noexcept;
213
214		/// Return the option name.
215		static int name() noexcept;
216		};
217
218		/** Restrict an IPv6 socket to IPv6 only (IPV6_V6ONLY).
219
220		When enabled, the socket only accepts IPv6 connections.
221		When disabled, the socket accepts both IPv4 and IPv6
222		connections (dual-stack mode).
223
224		@par Example
225		@code
226		sock.set_option( socket_option::v6_only( true ) );
227		@endcode
228		*/
229		class BOOST_COROSIO_DECL v6_only : public boolean_option
230		{
231		public:
232		using boolean_option::boolean_option;
233		using boolean_option::operator=;
234
235		/// Return the protocol level.
236		static int level() noexcept;
237
238		/// Return the option name.
239		static int name() noexcept;
240		};
241
242		/** Allow local address reuse (SO_REUSEADDR).
243
244		@par Example
245		@code
246		acc.set_option( socket_option::reuse_address( true ) );
247		@endcode
248		*/
249		class BOOST_COROSIO_DECL reuse_address : public boolean_option
250		{
251		public:
252		using boolean_option::boolean_option;
253		using boolean_option::operator=;
254
255		/// Return the protocol level.
256		static int level() noexcept;
257
258		/// Return the option name.
259		static int name() noexcept;
260		};
261
262		/** Allow sending to broadcast addresses (SO_BROADCAST).
263
264		Required for UDP sockets that send to broadcast addresses
265		such as 255.255.255.255. Without this option, `send_to`
266		returns an error.
267
268		@par Example
269		@code
270		udp_socket sock( ioc );
271		sock.open();
272		sock.set_option( socket_option::broadcast( true ) );
273		@endcode
274		*/
275		class BOOST_COROSIO_DECL broadcast : public boolean_option
276		{
277		public:
278		using boolean_option::boolean_option;
279		using boolean_option::operator=;
280
281		/// Return the protocol level.
282		static int level() noexcept;
283
284		/// Return the option name.
285		static int name() noexcept;
286		};
287
288		/** Allow multiple sockets to bind to the same port (SO_REUSEPORT).
289
290		Not available on all platforms. On unsupported platforms,
291		`set_option` will return an error.
292
293		@par Example
294		@code
295		acc.open( tcp::v6() );
296		acc.set_option( socket_option::reuse_port( true ) );
297		acc.bind( endpoint( ipv6_address::any(), 8080 ) );
298		acc.listen();
299		@endcode
300		*/
301		class BOOST_COROSIO_DECL reuse_port : public boolean_option
302		{
303		public:
304		using boolean_option::boolean_option;
305		using boolean_option::operator=;
306
307		/// Return the protocol level.
308		static int level() noexcept;
309
310		/// Return the option name.
311		static int name() noexcept;
312		};
313
314		/** Set the receive buffer size (SO_RCVBUF).
315
316		@par Example
317		@code
318		sock.set_option( socket_option::receive_buffer_size( 65536 ) );
319		auto opt = sock.get_option<socket_option::receive_buffer_size>();
320		int sz = opt.value();
321		@endcode
322		*/
323		class BOOST_COROSIO_DECL receive_buffer_size : public integer_option
324		{
325		public:
326		using integer_option::integer_option;
327		using integer_option::operator=;
328
329		/// Return the protocol level.
330		static int level() noexcept;
331
332		/// Return the option name.
333		static int name() noexcept;
334		};
335
336		/** Set the send buffer size (SO_SNDBUF).
337
338		@par Example
339		@code
340		sock.set_option( socket_option::send_buffer_size( 65536 ) );
341		@endcode
342		*/
343		class BOOST_COROSIO_DECL send_buffer_size : public integer_option
344		{
345		public:
346		using integer_option::integer_option;
347		using integer_option::operator=;
348
349		/// Return the protocol level.
350		static int level() noexcept;
351
352		/// Return the option name.
353		static int name() noexcept;
354		};
355
356		/** The SO_LINGER socket option.
357
358		Controls behavior when closing a socket with unsent data.
359		When enabled, `close()` blocks until pending data is sent
360		or the timeout expires.
361
362		@par Example
363		@code
364		sock.set_option( socket_option::linger( true, 5 ) );
365		auto opt = sock.get_option<socket_option::linger>();
366		if ( opt.enabled() )
367		std::cout << "linger timeout: " << opt.timeout() << "s\n";
368		@endcode
369		*/
370		class BOOST_COROSIO_DECL linger
371		{
372		// Opaque storage for the platform's struct linger.
373		// POSIX: { int, int } = 8 bytes.
374		// Windows: { u_short, u_short } = 4 bytes.
375		static constexpr std::size_t max_storage_ = 8;
376		alignas(4) unsigned char storage_[max_storage_]{};
377
378		public:
379		/// Construct with default values (disabled, zero timeout).
380		linger() noexcept = default;
381
382		/** Construct with explicit values.
383
384		@param enabled `true` to enable linger behavior on close.
385		@param timeout The linger timeout in seconds.
386		*/
387		linger(bool enabled, int timeout) noexcept;
388
389		/// Return whether linger is enabled.
390		bool enabled() const noexcept;
391
392		/// Set whether linger is enabled.
393		void enabled(bool v) noexcept;
394
395		/// Return the linger timeout in seconds.
396		int timeout() const noexcept;
397
398		/// Set the linger timeout in seconds.
399		void timeout(int v) noexcept;
400
401		/// Return the protocol level.
402		static int level() noexcept;
403
404		/// Return the option name.
405		static int name() noexcept;
406
407		/// Return a pointer to the underlying storage.
408	10x	void* data() noexcept
409		{
410	10x	return storage_;
411		}
412
413		/// Return a pointer to the underlying storage.
414	2070x	void const* data() const noexcept
415		{
416	2070x	return storage_;
417		}
418
419		/// Return the size of the underlying storage.
420		std::size_t size() const noexcept;
421
422		/** Normalize after `getsockopt`.
423
424		No-op — `struct linger` is always returned at full size.
425
426		@param s The number of bytes actually written by `getsockopt`.
427		*/
428	10x	void resize(std::size_t) noexcept {}
429		};
430
431		/** Enable loopback of outgoing multicast on IPv4 (IP_MULTICAST_LOOP).
432
433		@par Example
434		@code
435		sock.set_option( socket_option::multicast_loop_v4( true ) );
436		@endcode
437		*/
438		class BOOST_COROSIO_DECL multicast_loop_v4 : public boolean_option
439		{
440		public:
441		using boolean_option::boolean_option;
442		using boolean_option::operator=;
443
444		/// Return the protocol level.
445		static int level() noexcept;
446
447		/// Return the option name.
448		static int name() noexcept;
449		};
450
451		/** Enable loopback of outgoing multicast on IPv6 (IPV6_MULTICAST_LOOP).
452
453		@par Example
454		@code
455		sock.set_option( socket_option::multicast_loop_v6( true ) );
456		@endcode
457		*/
458		class BOOST_COROSIO_DECL multicast_loop_v6 : public boolean_option
459		{
460		public:
461		using boolean_option::boolean_option;
462		using boolean_option::operator=;
463
464		/// Return the protocol level.
465		static int level() noexcept;
466
467		/// Return the option name.
468		static int name() noexcept;
469		};
470
471		/** Set the multicast TTL for IPv4 (IP_MULTICAST_TTL).
472
473		@par Example
474		@code
475		sock.set_option( socket_option::multicast_hops_v4( 4 ) );
476		@endcode
477		*/
478		class BOOST_COROSIO_DECL multicast_hops_v4 : public integer_option
479		{
480		public:
481		using integer_option::integer_option;
482		using integer_option::operator=;
483
484		/// Return the protocol level.
485		static int level() noexcept;
486
487		/// Return the option name.
488		static int name() noexcept;
489		};
490
491		/** Set the multicast hop limit for IPv6 (IPV6_MULTICAST_HOPS).
492
493		@par Example
494		@code
495		sock.set_option( socket_option::multicast_hops_v6( 4 ) );
496		@endcode
497		*/
498		class BOOST_COROSIO_DECL multicast_hops_v6 : public integer_option
499		{
500		public:
501		using integer_option::integer_option;
502		using integer_option::operator=;
503
504		/// Return the protocol level.
505		static int level() noexcept;
506
507		/// Return the option name.
508		static int name() noexcept;
509		};
510
511		/** Set the outgoing interface for IPv6 multicast (IPV6_MULTICAST_IF).
512
513		@par Example
514		@code
515		sock.set_option( socket_option::multicast_interface_v6( 1 ) );
516		@endcode
517		*/
518		class BOOST_COROSIO_DECL multicast_interface_v6 : public integer_option
519		{
520		public:
521		using integer_option::integer_option;
522		using integer_option::operator=;
523
524		/// Return the protocol level.
525		static int level() noexcept;
526
527		/// Return the option name.
528		static int name() noexcept;
529		};
530
531		/** Join an IPv4 multicast group (IP_ADD_MEMBERSHIP).
532
533		@par Example
534		@code
535		sock.set_option( socket_option::join_group_v4(
536		ipv4_address( "239.255.0.1" ) ) );
537		@endcode
538		*/
539		class BOOST_COROSIO_DECL join_group_v4
540		{
541		static constexpr std::size_t max_storage_ = 8;
542		alignas(4) unsigned char storage_[max_storage_]{};
543
544		public:
545		/// Construct with default values.
546		join_group_v4() noexcept = default;
547
548		/** Construct with a group and optional interface address.
549
550		@param group The multicast group address to join.
551		@param iface The local interface to use (default: any).
552		*/
553		join_group_v4(
554		ipv4_address group, ipv4_address iface = ipv4_address()) noexcept;
555
556		/// Return the protocol level.
557		static int level() noexcept;
558
559		/// Return the option name.
560		static int name() noexcept;
561
562		/// Return a pointer to the underlying storage.
563		void* data() noexcept
564		{
565		return storage_;
566		}
567
568		/// Return a pointer to the underlying storage.
569	2x	void const* data() const noexcept
570		{
571	2x	return storage_;
572		}
573
574		/// Return the size of the underlying storage.
575		std::size_t size() const noexcept;
576
577		/// No-op resize.
578		void resize(std::size_t) noexcept {}
579		};
580
581		/** Leave an IPv4 multicast group (IP_DROP_MEMBERSHIP).
582
583		@par Example
584		@code
585		sock.set_option( socket_option::leave_group_v4(
586		ipv4_address( "239.255.0.1" ) ) );
587		@endcode
588		*/
589		class BOOST_COROSIO_DECL leave_group_v4
590		{
591		static constexpr std::size_t max_storage_ = 8;
592		alignas(4) unsigned char storage_[max_storage_]{};
593
594		public:
595		/// Construct with default values.
596		leave_group_v4() noexcept = default;
597
598		/** Construct with a group and optional interface address.
599
600		@param group The multicast group address to leave.
601		@param iface The local interface (default: any).
602		*/
603		leave_group_v4(
604		ipv4_address group, ipv4_address iface = ipv4_address()) noexcept;
605
606		/// Return the protocol level.
607		static int level() noexcept;
608
609		/// Return the option name.
610		static int name() noexcept;
611
612		/// Return a pointer to the underlying storage.
613		void* data() noexcept
614		{
615		return storage_;
616		}
617
618		/// Return a pointer to the underlying storage.
619		void const* data() const noexcept
620		{
621		return storage_;
622		}
623
624		/// Return the size of the underlying storage.
625		std::size_t size() const noexcept;
626
627		/// No-op resize.
628		void resize(std::size_t) noexcept {}
629		};
630
631		/** Join an IPv6 multicast group (IPV6_JOIN_GROUP).
632
633		@par Example
634		@code
635		sock.set_option( socket_option::join_group_v6(
636		ipv6_address( "ff02::1" ), 0 ) );
637		@endcode
638		*/
639		class BOOST_COROSIO_DECL join_group_v6
640		{
641		static constexpr std::size_t max_storage_ = 20;
642		alignas(4) unsigned char storage_[max_storage_]{};
643
644		public:
645		/// Construct with default values.
646		join_group_v6() noexcept = default;
647
648		/** Construct with a group and optional interface index.
649
650		@param group The multicast group address to join.
651		@param if_index The interface index (0 = kernel chooses).
652		*/
653		join_group_v6(ipv6_address group, unsigned int if_index = 0) noexcept;
654
655		/// Return the protocol level.
656		static int level() noexcept;
657
658		/// Return the option name.
659		static int name() noexcept;
660
661		/// Return a pointer to the underlying storage.
662		void* data() noexcept
663		{
664		return storage_;
665		}
666
667		/// Return a pointer to the underlying storage.
668		void const* data() const noexcept
669		{
670		return storage_;
671		}
672
673		/// Return the size of the underlying storage.
674		std::size_t size() const noexcept;
675
676		/// No-op resize.
677		void resize(std::size_t) noexcept {}
678		};
679
680		/** Leave an IPv6 multicast group (IPV6_LEAVE_GROUP).
681
682		@par Example
683		@code
684		sock.set_option( socket_option::leave_group_v6(
685		ipv6_address( "ff02::1" ), 0 ) );
686		@endcode
687		*/
688		class BOOST_COROSIO_DECL leave_group_v6
689		{
690		static constexpr std::size_t max_storage_ = 20;
691		alignas(4) unsigned char storage_[max_storage_]{};
692
693		public:
694		/// Construct with default values.
695		leave_group_v6() noexcept = default;
696
697		/** Construct with a group and optional interface index.
698
699		@param group The multicast group address to leave.
700		@param if_index The interface index (0 = kernel chooses).
701		*/
702		leave_group_v6(ipv6_address group, unsigned int if_index = 0) noexcept;
703
704		/// Return the protocol level.
705		static int level() noexcept;
706
707		/// Return the option name.
708		static int name() noexcept;
709
710		/// Return a pointer to the underlying storage.
711		void* data() noexcept
712		{
713		return storage_;
714		}
715
716		/// Return a pointer to the underlying storage.
717		void const* data() const noexcept
718		{
719		return storage_;
720		}
721
722		/// Return the size of the underlying storage.
723		std::size_t size() const noexcept;
724
725		/// No-op resize.
726		void resize(std::size_t) noexcept {}
727		};
728
729		/** Set the outgoing interface for IPv4 multicast (IP_MULTICAST_IF).
730
731		Unlike the integer-based `multicast_interface_v6`, this option
732		takes an `ipv4_address` identifying the local interface.
733
734		@par Example
735		@code
736		sock.set_option( socket_option::multicast_interface_v4(
737		ipv4_address( "192.168.1.1" ) ) );
738		@endcode
739		*/
740		class BOOST_COROSIO_DECL multicast_interface_v4
741		{
742		static constexpr std::size_t max_storage_ = 4;
743		alignas(4) unsigned char storage_[max_storage_]{};
744
745		public:
746		/// Construct with default values (INADDR_ANY).
747		multicast_interface_v4() noexcept = default;
748
749		/** Construct with an interface address.
750
751		@param iface The local interface address.
752		*/
753		explicit multicast_interface_v4(ipv4_address iface) noexcept;
754
755		/// Return the protocol level.
756		static int level() noexcept;
757
758		/// Return the option name.
759		static int name() noexcept;
760
761		/// Return a pointer to the underlying storage.
762		void* data() noexcept
763		{
764		return storage_;
765		}
766
767		/// Return a pointer to the underlying storage.
768		void const* data() const noexcept
769		{
770		return storage_;
771		}
772
773		/// Return the size of the underlying storage.
774		std::size_t size() const noexcept;
775
776		/// No-op resize.
777		void resize(std::size_t) noexcept {}
778		};
779
780		} // namespace boost::corosio::socket_option
781
782		#endif // BOOST_COROSIO_SOCKET_OPTION_HPP
783