cpp-httplib/docs-src/pages/en/cookbook/s17-bind-any-port.md

title, order, status

title	order	status
S17. Bind to Any Available Port	36	draft

Standing up a test server often hits port conflicts. With bind_to_any_port(), you let the OS pick a free port and then read back which one it gave you.

Basic usage

httplib::Server svr;

svr.Get("/", [](const auto &req, auto &res) {
  res.set_content("hello", "text/plain");
});

int port = svr.bind_to_any_port("0.0.0.0");
std::cout << "listening on port " << port << std::endl;

svr.listen_after_bind();

bind_to_any_port() is equivalent to passing 0 as the port — the OS assigns a free one. The return value is the port actually used.

After that, call listen_after_bind() to start accepting. You can't combine bind and listen into a single call here, so you work in two steps.

Useful in tests

This pattern is great for tests that spin up a server and hit it.

httplib::Server svr;
svr.Get("/ping", [](const auto &, auto &res) { res.set_content("pong", "text/plain"); });

int port = svr.bind_to_any_port("127.0.0.1");
std::thread t([&] { svr.listen_after_bind(); });

// run the test while the server is up on another thread
httplib::Client cli("127.0.0.1", port);
auto res = cli.Get("/ping");
assert(res && res->body == "pong");

svr.stop();
t.join();

Because the port is assigned at runtime, parallel test runs don't collide.

Note: bind_to_any_port() returns -1 on failure (permission errors, no available ports, etc.). Always check the return value.

To stop the server, see S19. Shut Down Gracefully.