--- /dev/null
+.\" libbsd man page
+.\"
+.\" Copyright © 2017 Gullem Jover <guillem@hadrons.org>
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\" derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
+.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd May 31 2017
+.Dt LIBBSD 7
+.Os
+.Sh NAME
+.Nm libbsd
+.Nd utility functions from BSD systems
+.Sh DESCRIPTION
+The
+.Nm libbsd
+library provides a set if compatibility macros and functions commonly found
+on BSD-based systems.
+Its purpose is to make those available on non-BSD based systems to ease
+portability.
+.Pp
+The library can be used in an overlay mode, which is the preferred way, so
+that the code is portable and requires no modification to the original BSD
+code.
+This can be done easily with the
+.Xr pkg-config 3
+library named
+.Pa libbsd-overlay .
+Or by adding the system-specific include directory with the
+.Pa bsd/
+suffix to the list of system include paths.
+With
+.Nm gcc
+this could be
+.Ar -isystem ${includedir}/bsd .
+In addition the
+.Dv LIBBSD_OVERLAY
+pre-processor variable needs to be defined.
+The includes in this case should be the usual system ones, such as
+.In unistd.h .
+.Pp
+The other way to use the library is to use the namespaced headers,
+this is less portable as it makes using
+.Nm libbsd
+mandatory and it will not work on BSD-based systems, and requires
+modifying original BSD code.
+This can be done with the
+.Xr pkg-config 3
+library named
+.Pa libbsd .
+The includes in this case should be namespaced with
+.Pa bsd/ ,
+such as
+.In bsd/unistd.h .
+.Pp
+The package also provides a
+.Pa bsd-ctor
+static library that can be used to inject automatic constructors into a
+program so that the
+.Fn setproctitle
+function gets invoked automatically at startup time.
+This can be done with the
+.Xr pkg-config 3
+library named
+.Pa libbsd-ctor .
+.Sh HEADERS
+The following are the headers provided by
+.Nm libbsd ,
+that extend the standard system headers.
+They can work in normal or overlay modes, for the former they need to
+be prefixed with
+.Pa bsd/ .
+.Pp
+.Bl -tag -width 4m -compact
+.It In bitstring.h
+.It In err.h
+.It In getopt.h
+.It In libutil.h
+.It In md5.h
+.It In netinet/ip_icmp.h
+.It In nlist.h
+.It In readpassphrase.h
+.It In stdio.h
+.It In stdlib.h
+.It In string.h
+.It In stringlist.h
+.It In sys/bitstring.h
+.It In sys/cdefs.h
+.It In sys/endian.h
+.It In sys/poll.h
+.It In sys/queue.h
+.It In sys/tree.h
+.It In timeconv.h
+.It In unistd.h
+.It In vis.h
+.It In wchar.h
+.El
+.Pp
+The following is a
+.Pa libbsd
+specific convenience header, that includes some of the extended headers.
+It only works in non-overlay mode.
+.Pp
+.Bl -tag -width 4m -compact
+.It In bsd/bsd.h
+.El
+.Sh DEPRECATED
+Some functions have been deprecated, they will emit warnings at compile time
+and possibly while being linked at run-time.
+This might be due to the functions not being portable at all to other
+systems, making the package not buildable there; not portable in a correct
+or non-buggy way; or because there are better more portable replacements now.
+.Pp
+This is the list of currently deprecated macros and functions:
+.Bl -tag -width 4m
+.It Fn fgetln
+Unportable, requires assistance from the stdio layer.
+An implementation has to choose between leaking buffers or being reentrant
+for a limited amount of streams (this implementation chose the latter with
+a limit of 32).
+Use
+.Fn getline 3
+instead, which is available in many systems and required by
+.St -p1003.1-2008 .
+.It Fn funopen
+Unportable, requires assistance from the stdio layer or some hook framework.
+On GNU systems the
+.Fn fopencookie
+function can be used.
+Otherwise the code needs to be prepared for neither of these functions being
+available.
+.El
+.Pp
+In addition, the MD5 set of digest funtions are now provided by the
+.Nm libmd
+companion library, so it is advised to use that instead, as the ones
+provided in
+.Nm libbsd
+might disappear on the next SONAME bump.
+.Sh SEE ALSO
+.Xr arc4random 3bsd ,
+.Xr bitstring 3bsd ,
+.Xr byteorder 3bsd ,
+.Xr closefrom 3bsd ,
+.Xr errc 3bsd ,
+.Xr expand_number 3bsd ,
+.Xr explicit_bzero 3bsd ,
+.Xr fgetln 3bsd ,
+.Xr fgetwln 3bsd ,
+.Xr flopen 3bsd ,
+.Xr fmtcheck 3bsd ,
+.Xr fparseln 3bsd ,
+.Xr fpurge 3bsd ,
+.Xr funopen 3bsd ,
+.Xr getbsize 3bsd ,
+.Xr getpeereid 3bsd ,
+.Xr getprogname 3bsd ,
+.Xr heapsort 3bsd ,
+.Xr humanize_number 3bsd ,
+.Xr md5 3bsd ,
+.Xr nlist 3bsd ,
+.Xr pidfile 3bsd ,
+.Xr queue 3bsd ,
+.Xr radixsort 3bsd ,
+.Xr readpassphrase 3bsd ,
+.Xr reallocarray 3bsd ,
+.Xr reallocf 3bsd ,
+.Xr setmode 3bsd ,
+.Xr setproctitle 3bsd ,
+.Xr stringlist 3bsd ,
+.Xr strlcpy 3bsd ,
+.Xr strmode 3bsd ,
+.Xr strnstr 3bsd ,
+.Xr strtonum 3bsd ,
+.Xr tree 3bsd ,
+.Xr unvis 3bsd ,
+.Xr vis 3bsd ,
+.Xr wcslcpy 3bsd .
+.Sh HISTORY
+The
+.Nm libbsd
+project started in the Debian GNU/kFreeBSD port as a way to ease porting
+code from FreeBSD to the GNU-based system.
+Pretty early on it was generalized and a project created on FreeDesktop.org
+for other distributions and projects to use.
+.Pp
+It is now distributed as part of most non-BSD distributions.