Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
KHTTP_URLABS(3) 	     Library Functions Manual		 KHTTP_URLABS(3)

NAME
     khttp_urlabs, khttp_vurlabs -- URL formatting for kcgi

LIBRARY
     libkcgi

SYNOPSIS
     #include <sys/types.h>
     #include <stdarg.h>
     #include <stdint.h>
     #include <kcgi.h>

     char *
     khttp_urlabs(enum kscheme scheme, const char *host, uint16_t port,
	 const char *path, ...);

     char *
     khttp_vurlabs(enum kscheme scheme, const char *host, uint16_t port,
	 const char *path, va_list ap);

DESCRIPTION
     Format  an  absolute  (full) URL.	The host is in some standards called the
     "authority".

	   scheme://host:port/path?key=val
	   scheme://host:port/path
	   scheme:path

     Passing a NULL or empty host will omit the "//", host, port component.

     If the host is non-empty and not NULL and the path is  also  non-empty  and
     not NULL, the path is prepended with a mandatory slash.

     If  the port is zero, it is omitted.  The port is only used if host is non-
     empty and not NULL.

     The variable arguments are arranged in pairs terminated by a  single  NULL.
     The  first  of  each pair is the query string key, the second is the value.
     Both are char *.  A NULL query string value is rendered as an empty string.

     Only the query string pairs are URL-encoded, so the caller must  make  sure
     that the characters in host and path are valid.

     The deprecated form of these functions, kutil_urlabs(), should no longer be
     used.

RETURN VALUES
     Return  newly-allocated  strings that must be freed with free(3) or NULL if
     allocation fails.

EXAMPLES
     To print a full URL:

	   khttp_urlabs(KSCHEME_HTTPS, foo.com, 80, b, c, d, NULL);

     This assigns https://foo.com:80/b?c=d.

     Setting the port to zero eliminates the port:

	   khttp_urlabs(KSCHEME_HTTPS, foo.com, 0, b, c, d, NULL);

     This assigns https://foo.com/b?c=d.

     An empty path component ends with the domain (or query string).

	   khttp_urlabs(KSCHEME_HTTPS, foo.com, 0, , c, d, NULL);

     This assigns https://foo.com?c=d.

     To use a host-less scheme, specify a NULL or empty host:

	   khttp_urlabs(KSCHEME_MAILTO, NULL, 0, k@b.com, NULL);

     This assigns mailto:k@b.com.

AUTHORS
     Written by Kristaps Dzonsons <kristaps@bsd.lv>.

CAVEATS
     These functions can currently be used to create semantically  invalid  URLs
     such as https:?foo=bar by omitting components required for the scheme.  Se-
     mantically-correct  URLs are the responsibility of the caller.  This behav-
     iour may be verified for correctness in later versions of the software.

FreeBSD ports 15.quarterly	   $Mdocdate$			 KHTTP_URLABS(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=khttp_urlabs&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help