NE_SESSION_CREATE(3)

📦
version 0.37.1 · 12 versions
, in arch rolling

🦋 NE_SESSION_CREATE(3) 🦋

okay bestie, welcome to the neon API reference — this is the neon manual, third section, and today's main character is NE_SESSION_CREATE. she sets things up. she's the beginning of the story. let's go 💅

✨ NAME ✨

ne_session_create, ne_close_connection, ne_session_destroy — the trio that sets up HTTP sessions for you, closes the connection when you're done, and then cleans up the whole thing. three besties, one job 🫶

🌸 SYNOPSIS 🌸

#include <ne_session.h>

ne_session *ne_session_create(const char *scheme, const char *host,
                              unsigned int port);

void ne_close_connection(ne_session *session);

void ne_session_destroy(ne_session *session);

okay so like, look at those signatures. gorgeous. <ne_session.h> is the header you need, and yeah, that's literally it 💖

💜 DESCRIPTION 💜

An ne_session object represents an HTTP session — think of it as a logical grouping of a whole sequence of HTTP requests you're making to a certain server. the way that everything in one session can share stuff? obsessed. any requests made using the session can use a persistent connection, share cached authentication credentials, and share any other common attributes. it's giving shared group chat energy 🎀

A new HTTP session gets created with the ne_session_create function. the host and port parameters specify the origin server you're talking to, along with the scheme (usually "http"). and listen — before the first use of ne_session_create in a process, ne_sock_init(3) must have been called, so any global initialization needed by any libraries used by neon actually happens. do not skip this, i'm serious 😭

Wanna enable SSL/TLS for the session? pass the string "https" as the scheme, and then either register a certificate verification function (see ne_ssl_set_verify(3)) or trust the appropriate certificate (see ne_ssl_trust_cert(3), ne_ssl_trust_default_ca(3)). pick one, babes, but pick one ✨

The host parameter must follow the "host" grammar in Section 3.2.2 of RFC 3986[1] — which can be an IP-literal or a registered (DNS) hostname. valid examples of each, since i know you're gonna ask:

  • "198.51.100.42" — an IPv4 literal address
  • "[2001:db8::42]" — an IPv6 literal, which MUST be enclosed in square brackets (yes literally must, all caps, no cap)
  • "www.example.com" — a DNS hostname

The RFC 6874[2] syntax for scoped IPv6 link-local literal addresses is also permitted — for example "[fe80::1%25eth0]". fancy 💅

The scheme parameter is used to determine the URI for resources identified during request handling. other than the special handling of the string "https", no other interpretation or checking of the scheme is performed. like, none. zero vibe check. for example, if an HTTP-to-FTP proxy is configured, a scheme of "ftp" could be used to access resources. slay 🦋

Wanna use a proxy server for the session? it must be configured (see ne_session_proxy(3)) before any requests are created from the session object. before, bestie. the order matters 🙈

Further per-session options can be changed using the ne_set_session_flag(3) interface — go off 👑

If you know the session won't be used for a significant period of time, ne_close_connection can be called to close the connection, if one remains open. use of this function is entirely optional — no pressure — but it must not be called if there's a request active using the session. like, hard no 🔥

Once a session has been completed, ne_session_destroy must be called to destroy the resources associated with the session. any subsequent use of the session pointer produces undefined behaviour (💀 not the undefined behaviour). and the session object must not be destroyed until after all associated request objects have been destroyed. last one out turns off the lights, periodt.

🧚 NOTES 🧚

If a hostname is passed to ne_session_create, it will be resolved when the first request using the session is dispatched — so a DNS resolution failure can only be detected at that time (using the NE_LOOKUP error code). see ne_request_dispatch(3) for details, iykyk 🌈

⭐ RETURN VALUES ⭐

ne_session_create will return a pointer to a new session object — and it never returns NULL. iconic behaviour honestly, no NULL checks needed, we love a reliable king 👑

🍓 EXAMPLES 🍓

Create and destroy a session:

ne_session *sess;
sess = ne_session_create("http", "host.example.com", 80);
/* ... use sess ... */
ne_session_destroy(sess);

look at her. create, use, destroy. the full lifecycle, the main character arc 💖

🌸 HISTORY 🌸

The scheme passed to ne_session_create is lower-cased internally from neon 0.37.0 onward — so passing "HtTpS" and "https" are equivalent. glow-up fr fr ✨ in earlier releases, the scheme is case-sensitive. so like, mind your version 😭

🎀 SEE ALSO 🎀

go read them, they're all linked in the group chat 🫶

Copyright © 2001-2026 Joe Orton

🔗 REFERENCES 🔗

  1. Section 3.2.2 of RFC 3986 — https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2
  2. RFC 6874 — https://www.rfc-editor.org/rfc/rfc6874

and that's the whole page bestie!! brought to you by neon, dated 03/20/2026, filed under NE_SESSION_CREATE(3) 💜✨ now go call ne_sock_init(3) first, i'm watching you 🌸

📦 where this page comes from