Diff coverage report for

//

//

// Copyright (c) 2026 Steve Gerbino

// Copyright (c) 2026 Steve Gerbino

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/cppalliance/corosio

// Official repository: https://github.com/cppalliance/corosio

//

//

#ifndef BOOST_COROSIO_SOCKET_OPTION_HPP

#ifndef BOOST_COROSIO_SOCKET_OPTION_HPP

#define BOOST_COROSIO_SOCKET_OPTION_HPP

#define BOOST_COROSIO_SOCKET_OPTION_HPP

#include <boost/corosio/detail/config.hpp>

#include <boost/corosio/detail/config.hpp>

#include <cstddef>

#include <cstddef>

/** @file socket_option.hpp

/** @file socket_option.hpp

    Type-erased socket option types that avoid platform-specific

    Type-erased socket option types that avoid platform-specific

    headers. The protocol level and option name for each type are

    headers. The protocol level and option name for each type are

    resolved at link time via the compiled library.

    resolved at link time via the compiled library.

    For an inline (zero-overhead) alternative that includes platform

    For an inline (zero-overhead) alternative that includes platform

    headers, use `<boost/corosio/native/native_socket_option.hpp>`

    headers, use `<boost/corosio/native/native_socket_option.hpp>`

    (`boost::corosio::native_socket_option`).

    (`boost::corosio::native_socket_option`).

    Both variants satisfy the same option-type interface and work

    Both variants satisfy the same option-type interface and work

    interchangeably with `tcp_socket::set_option` /

    interchangeably with `tcp_socket::set_option` /

    `tcp_socket::get_option` and the corresponding acceptor methods.

    `tcp_socket::get_option` and the corresponding acceptor methods.

    @see native_socket_option

    @see native_socket_option

*/

*/

namespace boost::corosio::socket_option {

namespace boost::corosio::socket_option {

/** Base class for concrete boolean socket options.

/** Base class for concrete boolean socket options.

    Stores a boolean as an `int` suitable for `setsockopt`/`getsockopt`.

    Stores a boolean as an `int` suitable for `setsockopt`/`getsockopt`.

    Derived types provide `level()` and `name()` for the specific option.

    Derived types provide `level()` and `name()` for the specific option.

*/

*/

class boolean_option

class boolean_option

{

{

    int value_ = 0;

    int value_ = 0;

public:

public:

    /// Construct with default value (disabled).

    /// Construct with default value (disabled).

    boolean_option() = default;

    boolean_option() = default;

    /** Construct with an explicit value.

    /** Construct with an explicit value.

        @param v `true` to enable the option, `false` to disable.

        @param v `true` to enable the option, `false` to disable.

    */

    */

    /// Assign a new value.

    /// Assign a new value.

    {

    {

    }

    }

    /// Return the option value.

    /// Return the option value.

    /// Return the option value.

    /// Return the option value.

    /// Return the negated option value.

    /// Return the negated option value.

    /// Return a pointer to the underlying storage.

    /// Return a pointer to the underlying storage.

    /// Return a pointer to the underlying storage.

    /// Return a pointer to the underlying storage.

    /// Return the size of the underlying storage.

    /// Return the size of the underlying storage.

    /** Normalize after `getsockopt` returns fewer bytes than expected.

    /** Normalize after `getsockopt` returns fewer bytes than expected.

        Windows Vista+ may write only 1 byte for boolean options.

        Windows Vista+ may write only 1 byte for boolean options.

        @param s The number of bytes actually written by `getsockopt`.

        @param s The number of bytes actually written by `getsockopt`.

    */

    */

    {

    {

};

};

/** Base class for concrete integer socket options.

/** Base class for concrete integer socket options.

    Stores an integer suitable for `setsockopt`/`getsockopt`.

    Stores an integer suitable for `setsockopt`/`getsockopt`.

    Derived types provide `level()` and `name()` for the specific option.

    Derived types provide `level()` and `name()` for the specific option.

*/

*/

class integer_option

class integer_option

{

{

    int value_ = 0;

    int value_ = 0;

public:

public:

    /// Construct with default value (zero).

    /// Construct with default value (zero).

    integer_option() = default;

    integer_option() = default;

    /** Construct with an explicit value.

    /** Construct with an explicit value.

        @param v The option value.

        @param v The option value.

    */

    */

    /// Assign a new value.

    /// Assign a new value.

    {

    {

    }

    }

    /// Return the option value.

    /// Return the option value.

    /// Return a pointer to the underlying storage.

    /// Return a pointer to the underlying storage.

    /// Return a pointer to the underlying storage.

    /// Return a pointer to the underlying storage.

    /// Return the size of the underlying storage.

    /// Return the size of the underlying storage.

    /** Normalize after `getsockopt` returns fewer bytes than expected.

    /** Normalize after `getsockopt` returns fewer bytes than expected.

        @param s The number of bytes actually written by `getsockopt`.

        @param s The number of bytes actually written by `getsockopt`.

    */

    */

    {

    {

};

};

/** Disable Nagle's algorithm (TCP_NODELAY).

/** Disable Nagle's algorithm (TCP_NODELAY).

    @par Example

    @par Example

    @code

    @code

    sock.set_option( socket_option::no_delay( true ) );

    sock.set_option( socket_option::no_delay( true ) );

    auto nd = sock.get_option<socket_option::no_delay>();

    auto nd = sock.get_option<socket_option::no_delay>();

    if ( nd.value() )

    if ( nd.value() )

        // Nagle's algorithm is disabled

        // Nagle's algorithm is disabled

    @endcode

    @endcode

*/

*/

class BOOST_COROSIO_DECL no_delay : public boolean_option

class BOOST_COROSIO_DECL no_delay : public boolean_option

{

{

public:

public:

    using boolean_option::boolean_option;

    using boolean_option::boolean_option;

    using boolean_option::operator=;

    using boolean_option::operator=;

    /// Return the protocol level.

    /// Return the protocol level.

    static int level() noexcept;

    static int level() noexcept;

    /// Return the option name.

    /// Return the option name.

    static int name() noexcept;

    static int name() noexcept;

};

};

/** Enable periodic keepalive probes (SO_KEEPALIVE).

/** Enable periodic keepalive probes (SO_KEEPALIVE).

    @par Example

    @par Example

    @code

    @code

    sock.set_option( socket_option::keep_alive( true ) );

    sock.set_option( socket_option::keep_alive( true ) );

    @endcode

    @endcode

*/

*/

class BOOST_COROSIO_DECL keep_alive : public boolean_option

class BOOST_COROSIO_DECL keep_alive : public boolean_option

{

{

public:

public:

    using boolean_option::boolean_option;

    using boolean_option::boolean_option;

    using boolean_option::operator=;

    using boolean_option::operator=;

    /// Return the protocol level.

    /// Return the protocol level.

    static int level() noexcept;

    static int level() noexcept;

    /// Return the option name.

    /// Return the option name.

    static int name() noexcept;

    static int name() noexcept;

};

};

/** Restrict an IPv6 socket to IPv6 only (IPV6_V6ONLY).

/** Restrict an IPv6 socket to IPv6 only (IPV6_V6ONLY).

    When enabled, the socket only accepts IPv6 connections.

    When enabled, the socket only accepts IPv6 connections.

    When disabled, the socket accepts both IPv4 and IPv6

    When disabled, the socket accepts both IPv4 and IPv6

    connections (dual-stack mode).

    connections (dual-stack mode).

    @par Example

    @par Example

    @code

    @code

    sock.set_option( socket_option::v6_only( true ) );

    sock.set_option( socket_option::v6_only( true ) );

    @endcode

    @endcode

*/

*/

class BOOST_COROSIO_DECL v6_only : public boolean_option

class BOOST_COROSIO_DECL v6_only : public boolean_option

{

{

public:

public:

    using boolean_option::boolean_option;

    using boolean_option::boolean_option;

    using boolean_option::operator=;

    using boolean_option::operator=;

    /// Return the protocol level.

    /// Return the protocol level.

    static int level() noexcept;

    static int level() noexcept;

    /// Return the option name.

    /// Return the option name.

    static int name() noexcept;

    static int name() noexcept;

};

};

/** Allow local address reuse (SO_REUSEADDR).

/** Allow local address reuse (SO_REUSEADDR).

    @par Example

    @par Example

    @code

    @code

    acc.set_option( socket_option::reuse_address( true ) );

    acc.set_option( socket_option::reuse_address( true ) );

    @endcode

    @endcode

*/

*/

class BOOST_COROSIO_DECL reuse_address : public boolean_option

class BOOST_COROSIO_DECL reuse_address : public boolean_option

{

{

public:

public:

    using boolean_option::boolean_option;

    using boolean_option::boolean_option;

    using boolean_option::operator=;

    using boolean_option::operator=;

    /// Return the protocol level.

    /// Return the protocol level.

    static int level() noexcept;

    static int level() noexcept;

    /// Return the option name.

    /// Return the option name.

    static int name() noexcept;

    static int name() noexcept;

};

};

/** Allow multiple sockets to bind to the same port (SO_REUSEPORT).

/** Allow multiple sockets to bind to the same port (SO_REUSEPORT).

    Not available on all platforms. On unsupported platforms,

    Not available on all platforms. On unsupported platforms,

    `set_option` will return an error.

    `set_option` will return an error.

    @par Example

    @par Example

    @code

    @code

    acc.open( tcp::v6() );

    acc.open( tcp::v6() );

    acc.set_option( socket_option::reuse_port( true ) );

    acc.set_option( socket_option::reuse_port( true ) );

    acc.bind( endpoint( ipv6_address::any(), 8080 ) );

    acc.bind( endpoint( ipv6_address::any(), 8080 ) );

    acc.listen();

    acc.listen();

    @endcode

    @endcode

*/

*/

class BOOST_COROSIO_DECL reuse_port : public boolean_option

class BOOST_COROSIO_DECL reuse_port : public boolean_option

{

{

public:

public:

    using boolean_option::boolean_option;

    using boolean_option::boolean_option;

    using boolean_option::operator=;

    using boolean_option::operator=;

    /// Return the protocol level.

    /// Return the protocol level.

    static int level() noexcept;

    static int level() noexcept;

    /// Return the option name.

    /// Return the option name.

    static int name() noexcept;

    static int name() noexcept;

};

};

/** Set the receive buffer size (SO_RCVBUF).

/** Set the receive buffer size (SO_RCVBUF).

    @par Example

    @par Example

    @code

    @code

    sock.set_option( socket_option::receive_buffer_size( 65536 ) );

    sock.set_option( socket_option::receive_buffer_size( 65536 ) );

    auto opt = sock.get_option<socket_option::receive_buffer_size>();

    auto opt = sock.get_option<socket_option::receive_buffer_size>();

    int sz = opt.value();

    int sz = opt.value();

    @endcode

    @endcode

*/

*/

class BOOST_COROSIO_DECL receive_buffer_size : public integer_option

class BOOST_COROSIO_DECL receive_buffer_size : public integer_option

{

{

public:

public:

    using integer_option::integer_option;

    using integer_option::integer_option;

    using integer_option::operator=;

    using integer_option::operator=;

    /// Return the protocol level.

    /// Return the protocol level.

    static int level() noexcept;

    static int level() noexcept;

    /// Return the option name.

    /// Return the option name.

    static int name() noexcept;

    static int name() noexcept;

};

};

/** Set the send buffer size (SO_SNDBUF).

/** Set the send buffer size (SO_SNDBUF).

    @par Example

    @par Example

    @code

    @code

    sock.set_option( socket_option::send_buffer_size( 65536 ) );

    sock.set_option( socket_option::send_buffer_size( 65536 ) );

    @endcode

    @endcode

*/

*/

class BOOST_COROSIO_DECL send_buffer_size : public integer_option

class BOOST_COROSIO_DECL send_buffer_size : public integer_option

{

{

public:

public:

    using integer_option::integer_option;

    using integer_option::integer_option;

    using integer_option::operator=;

    using integer_option::operator=;

    /// Return the protocol level.

    /// Return the protocol level.

    static int level() noexcept;

    static int level() noexcept;

    /// Return the option name.

    /// Return the option name.

    static int name() noexcept;

    static int name() noexcept;

};

};

/** The SO_LINGER socket option.

/** The SO_LINGER socket option.

    Controls behavior when closing a socket with unsent data.

    Controls behavior when closing a socket with unsent data.

    When enabled, `close()` blocks until pending data is sent

    When enabled, `close()` blocks until pending data is sent

    or the timeout expires.

    or the timeout expires.

    @par Example

    @par Example

    @code

    @code

    sock.set_option( socket_option::linger( true, 5 ) );

    sock.set_option( socket_option::linger( true, 5 ) );

    auto opt = sock.get_option<socket_option::linger>();

    auto opt = sock.get_option<socket_option::linger>();

    if ( opt.enabled() )

    if ( opt.enabled() )

        std::cout << "linger timeout: " << opt.timeout() << "s\n";

        std::cout << "linger timeout: " << opt.timeout() << "s\n";

    @endcode

    @endcode

*/

*/

class BOOST_COROSIO_DECL linger

class BOOST_COROSIO_DECL linger

{

{

    // Opaque storage for the platform's struct linger.

    // Opaque storage for the platform's struct linger.

    // POSIX: { int, int } = 8 bytes.

    // POSIX: { int, int } = 8 bytes.

    // Windows: { u_short, u_short } = 4 bytes.

    // Windows: { u_short, u_short } = 4 bytes.

    static constexpr std::size_t max_storage_ = 8;

    static constexpr std::size_t max_storage_ = 8;

    alignas( 4 ) unsigned char storage_[max_storage_]{};

    alignas( 4 ) unsigned char storage_[max_storage_]{};

public:

public:

    /// Construct with default values (disabled, zero timeout).

    /// Construct with default values (disabled, zero timeout).

    linger() noexcept = default;

    linger() noexcept = default;

    /** Construct with explicit values.

    /** Construct with explicit values.

        @param enabled `true` to enable linger behavior on close.

        @param enabled `true` to enable linger behavior on close.

        @param timeout The linger timeout in seconds.

        @param timeout The linger timeout in seconds.

    */

    */

    linger( bool enabled, int timeout ) noexcept;

    linger( bool enabled, int timeout ) noexcept;

    /// Return whether linger is enabled.

    /// Return whether linger is enabled.

    bool enabled() const noexcept;

    bool enabled() const noexcept;

    /// Set whether linger is enabled.

    /// Set whether linger is enabled.

    void enabled( bool v ) noexcept;

    void enabled( bool v ) noexcept;

    /// Return the linger timeout in seconds.

    /// Return the linger timeout in seconds.

    int timeout() const noexcept;

    int timeout() const noexcept;

    /// Set the linger timeout in seconds.

    /// Set the linger timeout in seconds.

    void timeout( int v ) noexcept;

    void timeout( int v ) noexcept;

    /// Return the protocol level.

    /// Return the protocol level.

    static int level() noexcept;

    static int level() noexcept;

    /// Return the option name.

    /// Return the option name.

    static int name() noexcept;

    static int name() noexcept;

    /// Return a pointer to the underlying storage.

    /// Return a pointer to the underlying storage.

    /// Return a pointer to the underlying storage.

    /// Return a pointer to the underlying storage.

    /// Return the size of the underlying storage.

    /// Return the size of the underlying storage.

    std::size_t size() const noexcept;

    std::size_t size() const noexcept;

    /** Normalize after `getsockopt`.

    /** Normalize after `getsockopt`.

        No-op — `struct linger` is always returned at full size.

        No-op — `struct linger` is always returned at full size.

        @param s The number of bytes actually written by `getsockopt`.

        @param s The number of bytes actually written by `getsockopt`.

    */

    */

};

};

} // namespace boost::corosio::socket_option

} // namespace boost::corosio::socket_option

#endif // BOOST_COROSIO_SOCKET_OPTION_HPP

#endif // BOOST_COROSIO_SOCKET_OPTION_HPP