Name

uri_scheme — copy a URI's scheme into a buffer

Library

URI parsing library (liburi, -luri)

Synopsis

#include <liburi.h>

size_t uri_scheme( URI *restrict uri, char * buffer, size_t size);

Description

The uri_scheme function copies the scheme from a URI into a supplied buffer.

Parameters

uri

The source URI to copy the scheme from.

buffer

The buffer to store the URI's scheme in. buffer may be NULL to simply obtain the return value.

The string stored in buffer will always be NULL-terminated, even if the buffer is not large enough to hold the entire string, provided buffer is not-NULL and size is non-zero.

size

The size of buffer, in bytes.

Return value

If successful, uri_scheme returns the total number of bytes required to store the URI's scheme, including the NULL terminator (that is, one greater than the length of the string measured in bytes). This return will occur whether a buffer is supplied or not, and regardless of its size.

If the URI has no scheme, uri_scheme will return 0, however it will still copy an empty string to buffer provided buffer is non-NULL and size is non-zero.

If an error occurs, uri_scheme returns (size_t) -1, and sets errno accordingly.

An application can invoke uri_scheme, passing NULL as buffer and 0 as size in order to obtain the size of buffer required for a subsequent call.

Alternatively, if buffer was non-NULL, an application can compare the return value with the supplied size in order to to determine whether the copied string was truncated: if the return value is less than or equal to size, truncation did not occur.

Example

#define BUFFER_SIZE 8
	  
URI *uri;
char buffer[BUFFER_SIZE];
size_t r;

uri = uri_create_str("http://example.com/", NULL);
r = uri_scheme(uri, buffer, BUFFER_SIZE);

/* assuming no errors have occurred, buffer will contain 'http' and
 * r will be 5.
 */
printf("buffer='%s', r=%lu\n", buffer, (unsigned long) r);
	

See also

liburi(3).