---
name: "ne_session_create"
section: "3"
platform: "linux"
package: "neon"
version: "0.37.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/ne_session_create"
---

# ne\_session\_create(3)

set up HTTP sessions

## NAME

ne\_session\_create, ne\_close\_connection, ne\_session\_destroy - set up HTTP sessions

## 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***);**

## DESCRIPTION

An **ne\_session** object represents an HTTP session - a logical grouping of a sequence of HTTP requests made to a certain server. Any requests made using the session can use a persistent connection, share cached authentication credentials and any other common attributes.

A new HTTP session is created using the **ne\_session\_create** function; the *host* and *port* parameters specify the origin server to use, along with the *scheme* (usually "http"). Before the first use of **ne\_session\_create** in a process, [**ne\_sock\_init**(3)](/ne_sock_init/3.md) must have been called to perform any global initialization needed by any libraries used by neon.

To enable SSL/TLS for the session, pass the string "https" as the *scheme*, and either register a certificate verification function (see [**ne\_ssl\_set\_verify**(3)](/ne_ssl_set_verify/3.md)) or trust the appropriate certificate (see [**ne\_ssl\_trust\_cert**(3)](/ne_ssl_trust_cert/3.md), [**ne\_ssl\_trust\_default\_ca**(3)](/ne_ssl_trust_default_ca/3.md)).

The *host* parameter must follow the "host" grammar in **Section 3.2.2 of RFC 3986**\[1\], which can be an IP-literal or registered (DNS) hostname. Valid examples of each: "198.51.100.42" (IPv4 literal address), "\[2001:db8::42\]" (IPv6 literal, which *MUST* be enclosed in square brackets), or "www.example.com" (DNS hostname). The **RFC 6874**\[2\] syntax for scoped IPv6 link-local literal addresses is also permitted, for example "\[fe80::1%25eth0\]".

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

To use a proxy server for the session, it must be configured (see [**ne\_session\_proxy**(3)](/ne_session_proxy/3.md)) before any requests are created from session object.

Further per-session options may be changed using the [**ne\_set\_session\_flag**(3)](/ne_set_session_flag/3.md) interface.

If it is known that the session will not 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, but it must not be called if there is a request active using the session.

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. The session object must not be destroyed until after all associated request objects have been destroyed.

## NOTES

If a hostname is passed to **ne\_session\_create**, it will be resolved when the first request using the session is dispatched; a DNS resolution failure can only be detected at that time (using the NE\_LOOKUP error code); see [**ne\_request\_dispatch**(3)](/ne_request_dispatch/3.md) for details.

## RETURN VALUES

**ne\_session\_create** will return a pointer to a new session object (and never NULL).

## EXAMPLES

Create and destroy a session:

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

## 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. In earlier releases, the scheme is case-sensitive.

## SEE ALSO

[**ne\_ssl\_set\_verify**(3)](/ne_ssl_set_verify/3.md), [**ne\_ssl\_trust\_cert**(3)](/ne_ssl_trust_cert/3.md), [**ne\_sock\_init**(3)](/ne_sock_init/3.md), [**ne\_set\_session\_flag**(3)](/ne_set_session_flag/3.md), [**ne\_session\_proxy**(3)](/ne_session_proxy/3.md)

## COPYRIGHT

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