write manpages

5 files changed, 416 insertions, 3 deletions

diff --git a/Makefile b/Makefile
index 5c6fe54..e4ff5b7 100644
--- a/Makefile
+++ b/Makefile
@@ -7,7 +7,7 @@ TARGET_LIB_STATIC = libyuri.a
 PREFIX = /usr
 
 OBJS = yuri.o decode.o encode.o normalize.o strlcpy.o strlcat.o
-MANPAGES = 
+MANPAGES = man/uri.3 man/uri_get.3 man/uri_set.3 man/uri_unset.3
 
 all: $(TARGET_LIB_STATIC) $(TARGET_LIB_DYNAMIC)
 
@@ -27,8 +27,8 @@ install: all
 	ldconfig -n $(PREFIX)/lib
 	mkdir -p $(PREFIX)/include
 	cp yuri.h $(PREFIX)/include
-#	mkdir -p $(PREFIX)/share/man/man3
-#	cp $(MANPAGES) $(PREFIX)/share/man/man3
+	mkdir -p $(PREFIX)/share/man/man3
+	cp $(MANPAGES) $(PREFIX)/share/man/man3
 
 clean:
 	rm -f $(TARGET_LIB_STATIC) $(TARGET_LIB_DYNAMIC) $(OBJS) test
diff --git a/man/uri.3 b/man/uri.3
new file mode 100644
index 0000000..03aa753
--- /dev/null
+++ b/man/uri.3
@@ -0,0 +1,85 @@
+.Dd Jan 18, 2021
+.Dt YURI 3
+.Sh NAME
+.Nm uri_new ,
+.Nm uri_decode ,
+.Nm uri_encode ,
+.Nm uri_normalize ,
+.Nm uri_free
+.Nd URI object manipulation functions
+.Sh SYNOPSIS
+.In yuri.h
+.Ft "struct uri *"
+.Fn uri_new
+.Ft "struct uri *"
+.Fn uri_decode "const char *str"
+.Ft "char *"
+.Fn uri_encode "struct uri *u"
+.Ft int
+.Fn uri_normalize "struct uri *u"
+.Ft void
+.Fn uri_free "struct uri *u"
+.Sh DESCRIPTION
+.Fn uri_new
+initializes a new URI object.
+.Pp
+.Fn uri_decode
+decodes URI pointed to by string
+.Em str
+and returns a corresponding URI object.
+.Pp
+.Fn uri_encode
+encodes URI object pointed to by
+.Em u
+and returns corresponding string.
+.Pp
+.Fn uri_normalize
+normalizes URI object pointed to by
+.Em u
+as per section 6.2 of RFC 3986.
+.Pp
+.Fn uri_free
+frees a URI object.
+.Pp
+For information on manipulating existing URI objects, refer to
+.Xr uri_set 3
+and
+.Xr uri_unset 3 .
+.Sh RETURN VALUES
+.Fn uri_new
+and
+.Fn uri_decode
+return a valid pointer to newly allocated URI object on success, or
+.Nm NULL
+on failure.
+.Pp
+.Fn uri_encode
+return a valid string pointer on success, or
+.Nm NULL
+on failure.
+.Pp
+.Fn uri_normalize
+returns
+.Em 0
+on success, or
+.Em -1
+on failure.
+.Pp
+Upon success, values returned by
+.Fn uri_new
+and
+.Fn uri_decode
+should be passed to
+.Fn uri_free
+after use,
+and values returned by
+.Fn uri_encode
+should be passed to
+.Fn free
+after use.
+.Sh SEE ALSO
+.Xr uri_set 3 ,
+.Xr uri_unset 3 ,
+.Xr uri_get 3
+.Sh AUTHORS
+.An Ali Fardan Aq Mt raiz@stellarbound.space
diff --git a/man/uri_get.3 b/man/uri_get.3
new file mode 100644
index 0000000..94f736e
--- /dev/null
+++ b/man/uri_get.3
@@ -0,0 +1,118 @@
+.Dd Jan 18, 2021
+.Dt YURI 3
+.Sh NAME
+.Nm uri_get_scheme ,
+.Nm uri_get_authority_type ,
+.Nm uri_get_authority_user ,
+.Nm uri_get_authority_host ,
+.Nm uri_get_authority_port ,
+.Nm uri_get_path ,
+.Nm uri_string_path ,
+.Nm uri_get_npath ,
+.Nm uri_get_query ,
+.Nm uri_get_fragment
+.Nd Retrieve values of individual components/subcomponents of URI object
+.Sh SYNOPSIS
+.In yuri.h
+.Ft "const char *"
+.Fn uri_get_scheme "struct uri *u"
+.Ft int
+.Fn uri_get_authority_type "struct uri *u"
+.Ft "const char *"
+.Fn uri_get_authority_user "struct uri *u"
+.Ft "const char *"
+.Fn uri_get_authority_host "struct uri *u"
+.Ft int
+.Fn uri_get_authority_port "struct uri *u"
+.Ft "const char **"
+.Fn uri_get_path "struct uri *u"
+.Ft "char *"
+.Fn uri_string_path "struct uri *u"
+.Ft int
+.Fn uri_get_npath "struct uri *u"
+.Ft "const char *"
+.Fn uri_get_query "struct uri *u"
+.Ft "const char *"
+.Fn uri_get_fragment "struct uri *u"
+.Sh DESCRIPTION
+.Fn uri_get_scheme
+returns the scheme component of URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_get_authority_type
+returns the host type of authority component of URI object pointed to by
+.Em u .
+.Pp
+Possible host types are as follows:
+.Bd -literal -offset indent
+#define YURI_HOST_NAME     1 /* DNS name */
+#define YURI_HOST_IP4      2 /* IPv4 address */
+#define YURI_HOST_IP6      3 /* IPv6 address */
+#define YURI_HOST_IPFUTURE 4 /* Future-proof place holder set
+                                by RFC 3986 for IP versions above v6 */
+.Ed
+.Pp
+.Fn uri_get_authority_user
+returns the user subcomponent of authority component of URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_get_authority_host
+returns the host subcomponent of authority component of URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_get_authority_port
+returns the port of host subcomponent of authority component of URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_get_path
+returns the array of path segments of URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_string_path
+returns string representation of path component of URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_get_npath
+returns the amount of segments contained in the path componenet of URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_get_query
+returns the query componenet of URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_get_fragment
+returns the fragment component of URI object pointed to by
+.Em u .
+.Sh RETURN VALUES
+.Fn uri_get_scheme ,
+.Fn uri_get_authority_user ,
+.Fn uri_get_authority_host ,
+.Fn uri_get_path ,
+.Fn uri_get_query
+and
+.Fn uri_get_fragment
+return a pointer to the underlying value contained within the URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_string_path
+returns pointer to heap-allocated string that should be passed to
+.Xr free 3
+after use, or
+.Nm NULL
+on error.
+.Sh ERRORS
+All above functions never fail except
+.Fn uri_string_path .
+.Sh CAVEATS
+Array returned by
+.Fn uri_get_path
+is not
+.Nm NULL
+terminated. Array length can be obtained using
+.Fn uri_get_npath .
+.Sh SEE ALSO
+.Xr uri 3 ,
+.Xr uri_set 3 ,
+.Xr uri_unset 3
+.Sh AUTHORS
+.An Ali Fardan Aq Mt raiz@stellarbound.space
diff --git a/man/uri_set.3 b/man/uri_set.3
new file mode 100644
index 0000000..0daf51b
--- /dev/null
+++ b/man/uri_set.3
@@ -0,0 +1,143 @@
+.Dd Jan 18, 2021
+.Dt YURI 3
+.Sh NAME
+.Nm uri_set_scheme ,
+.Nm uri_set_authority ,
+.Nm uri_set_authority_type ,
+.Nm uri_set_authority_user ,
+.Nm uri_set_authority_host ,
+.Nm uri_set_authority_port ,
+.Nm uri_append_path ,
+.Nm uri_set_query ,
+.Nm uri_set_fragment
+.Nd URI object manipulation functions
+.Sh SYNOPSIS
+.In yuri.h
+.Ft int
+.Fo uri_set_scheme
+.Fa "struct uri *u"
+.Fa "const char *scheme"
+.Fc
+.Ft int
+.Fo uri_set_authority
+.Fa "struct uri *u"
+.Fa "int type"
+.Fa "const char *user"
+.Fa "const char *host"
+.Fa "int port"
+.Fc
+.Ft int
+.Fo uri_set_authority_type
+.Fa "struct uri *u"
+.Fa "int type"
+.Fc
+.Ft int
+.Fo uri_set_authority_user
+.Fa "struct uri *u"
+.Fa "const char *user"
+.Fc
+.Ft int
+.Fo uri_set_authority_host
+.Fa "struct uri *u"
+.Fa "const char *host"
+.Fc
+.Ft int
+.Fo uri_set_authority_port
+.Fa "struct uri *u"
+.Fa "int port"
+.Fc
+.Ft int
+.Fo uri_append_path
+.Fa "struct uri *u"
+.Fa "const char *elem"
+.Fc
+.Ft int
+.Fo uri_set_query
+.Fa "struct uri *u"
+.Fa "const char *query"
+.Fc
+.Ft int
+.Fo uri_set_fragment
+.Fa "struct uri *u"
+.Fa "const char *fragment"
+.Fc
+.Sh DESCRIPTION
+.Fn uri_set_scheme
+sets the scheme component of URI object pointed to by
+.Em u
+to string pointed to by
+.Em scheme .
+.Pp
+.Fn uri_set_authority
+sets the authority component of URI object pointed to by
+.Em u
+where
+.Em type
+would be the host type,
+.Em user
+would be the user subcomponent,
+.Em host
+would be the host subcomponent, and
+.Em port
+would be the host port.
+.Pp
+Possible values for
+.Em type
+are as follows:
+.Bd -literal -offset indent
+#define YURI_HOST_NAME     1 /* DNS name */
+#define YURI_HOST_IP4      2 /* IPv4 address */
+#define YURI_HOST_IP6      3 /* IPv6 address */
+#define YURI_HOST_IPFUTURE 4 /* Future-proof place holder set
+                                by RFC 3986 for IP versions above v6 */
+.Ed
+.Pp
+.Em user
+and
+.Em port
+can be omitted by setting their values to
+.Nm NULL
+or
+.Em 0
+respectively, however,
+.Em type
+and
+.Em host
+are mandatory.
+.Pp
+.Fn uri_set_authority_type ,
+.Fn uri_set_authority_user ,
+.Fn uri_set_authority_host
+and
+.Fn uri_set_authority_port
+set corresponding authority subcomponenets individually.
+.Pp
+.Fn uri_append_path
+appends path segment pointed to by
+.Em elem
+to the URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_set_query
+sets the query component of URI object pointed to by
+.Em u
+to query string pointed to by
+.Em query .
+.Pp
+.Fn uri_set_fragment
+sets the fragment component for URI object pointed to by
+.Em u
+to fragment string pointed to by
+.Em fragment .
+.Sh RETURN VALUES
+All above functions return
+.Em 0
+on success, or
+.Em -1
+on failure.
+.Sh SEE ALSO
+.Xr uri 3 ,
+.Xr uri_unset 3 ,
+.Xr uri_get 3
+.Sh AUTHORS
+.An Ali Fardan Aq Mt raiz@stellarbound.space
diff --git a/man/uri_unset.3 b/man/uri_unset.3
new file mode 100644
index 0000000..801e8e9
--- /dev/null
+++ b/man/uri_unset.3
@@ -0,0 +1,67 @@
+.Dd Jan 18, 2021
+.Dt YURI 3
+.Sh NAME
+.Nm uri_unset_scheme ,
+.Nm uri_unset_authority ,
+.Nm uri_unset_authority_type ,
+.Nm uri_unset_authority_user ,
+.Nm uri_unset_authority_host ,
+.Nm uri_unset_authority_port ,
+.Nm uri_unset_path ,
+.Nm uri_unset_query ,
+.Nm uri_unset_fragment
+.Nd URI object manipulation functions
+.Sh SYNOPSIS
+.In yuri.h
+.Ft void
+.Fn uri_unset_scheme "struct uri *u"
+.Ft void
+.Fn uri_unset_authority "struct uri *u"
+.Ft void
+.Fn uri_unset_authority_type "struct uri *u"
+.Ft void
+.Fn uri_unset_authority_user "struct uri *u"
+.Ft void
+.Fn uri_unset_authority_host "struct uri *u"
+.Ft void
+.Fn uri_unset_authority_port "struct uri *u"
+.Ft void
+.Fn uri_unset_path "struct uri *u"
+.Ft void
+.Fn uri_unset_query "struct uri *u"
+.Ft void
+.Fn uri_unset_fragment "struct uri *u"
+.Sh DESCRIPTION
+.Fn uri_unset_scheme
+unsets scheme component of URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_unset_authority
+unsets authority component of URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_unset_authority_type ,
+.Fn uri_unset_authority_user ,
+.Fn uri_unset_authority_host
+and
+.Fn uri_unset_authority_port
+unset corresponding individual subcomponents of authority component of URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_unset_path
+unsets path component of URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_unset_query
+unsets query component of URI object pointed to by
+.Em u .
+.Pp
+.Fn uri_unset_fragment
+unsets fragment component of URI object pointed to by
+.Em u .
+.Sh SEE ALSO
+.Xr uri 3 ,
+.Xr uri_set 3 ,
+.Xr uri_get 3
+.Sh AUTHORS
+.An Ali Fardan Aq Mt raiz@stellarbound.space