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
       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.	 Semantically-correct  URLs  are  the  responsibility  of  the
       caller.	 This  behaviour may be	verified for correctness in later ver-
       sions of	the software.

FreeBSD	Ports 14.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+14.3.quarterly>

home | help