man: Add new libbsd(7) library overview man page

COPYING

@@ -3,7 +3,7 @@ Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 Files:
  *
 Copyright:
- Copyright © 2004-2006, 2008-2015 Guillem Jover <guillem@hadrons.org>
+ Copyright © 2004-2006, 2008-2017 Guillem Jover <guillem@hadrons.org>
 License: BSD-3-clause
 
 Files:

man/arc4random.3bsd

@@ -44,7 +44,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/stdlib.h
+.In stdlib.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft uint32_t
 .Fn arc4random "void"
 .Ft void

man/bitstring.3bsd

@@ -45,7 +45,10 @@
 .Nm bit_test
 .Nd bit-string manipulation macros
 .Sh SYNOPSIS
-.In bsd/bitstring.h
+.In bitstring.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft bitstr_t *
 .Fn bit_alloc "int nbits"
 .Ft void

man/byteorder.3bsd

@@ -33,6 +33,9 @@
 .Nd byte order operations
 .Sh SYNOPSIS
 .In sys/endian.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft uint16_t
 .Fn be16dec "const void *"
 .Ft uint32_t

man/closefrom.3bsd

@@ -35,7 +35,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/unistd.h
+.In unistd.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft void
 .Fn closefrom "int lowfd"
 .Sh DESCRIPTION

man/errc.3bsd

@@ -41,6 +41,9 @@
 .Lb libbsd
 .Sh SYNOPSIS
 .In err.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft void
 .Fn errc "int status" "int code" "const char *fmt" "..."
 .Ft void

man/expand_number.3bsd

@@ -35,7 +35,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/libutil.h
+.In libutil.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft int
 .Fo expand_number
 .Fa "const char *buf" "uint64_t *num"

man/explicit_bzero.3bsd

@@ -39,7 +39,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/string.h
+.In string.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft void
 .Fn explicit_bzero "void *buf" "size_t len"
 .Sh DESCRIPTION

man/fgetln.3bsd

@@ -38,7 +38,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/stdio.h
+.In stdio.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft char *
 .Fn fgetln "FILE *stream" "size_t *len"
 .Sh DESCRIPTION

man/fgetwln.3bsd

@@ -39,7 +39,10 @@
 .Lb libbsd
 .Sh SYNOPSIS
 .In stdio.h
-.In bsd/wchar.h
+.In wchar.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft wchar_t *
 .Fn fgetwln "FILE * restrict stream" "size_t * restrict len"
 .Sh DESCRIPTION

man/flopen.3bsd

@@ -36,7 +36,10 @@
 .Lb libbsd
 .Sh SYNOPSIS
 .In sys/fcntl.h
-.In bsd/libutil.h
+.In libutil.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft int
 .Fn flopen "const char *path" "int flags"
 .Ft int

man/fmtcheck.3bsd

@@ -37,7 +37,10 @@ format string
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/stdio.h
+.In stdio.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft const char *
 .Fn fmtcheck "const char *fmt_suspect" "const char *fmt_default"
 .Sh DESCRIPTION

man/fparseln.3bsd

@@ -32,7 +32,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/stdio.h
+.In stdio.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft "char *"
 .Fo "fparseln"
 .Fa "FILE *stream" "size_t *len" "size_t *lineno"

man/fpurge.3bsd

@@ -42,6 +42,9 @@
 .Lb libbsd
 .Sh SYNOPSIS
 .In stdio.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft int
 .Fn fpurge "FILE *stream"
 .Sh DESCRIPTION

man/funopen.3bsd

@@ -42,7 +42,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/stdio.h
+.In stdio.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft FILE *
 .Fn funopen "const void *cookie" "int (*readfn)(void *, char *, int)" "int (*writefn)(void *, const char *, int)" "off_t (*seekfn)(void *, off_t, int)" "int (*closefn)(void *)"
 .Ft FILE *

man/getbsize.3bsd

@@ -38,7 +38,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/stdlib.h
+.In stdlib.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft char *
 .Fn getbsize "int *headerlenp" "long *blocksizep"
 .Sh DESCRIPTION

man/getpeereid.3bsd

@@ -36,7 +36,10 @@
 .Lb libbsd
 .Sh SYNOPSIS
 .In sys/types.h
-.In bsd/unistd.h
+.In unistd.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft int
 .Fn getpeereid "int s" "uid_t *euid" "gid_t *egid"
 .Sh DESCRIPTION

man/getprogname.3bsd

@@ -42,7 +42,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/stdlib.h
+.In stdlib.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft const char *
 .Fn getprogname "void"
 .Ft void

man/heapsort.3bsd

@@ -42,7 +42,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/stdlib.h
+.In stdlib.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft int
 .Fo heapsort
 .Fa "void *base"

man/humanize_number.3bsd

@@ -38,7 +38,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/stdlib.h
+.In stdlib.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft int
 .Fn dehumanize_number "const char *str" "int64_t *result"
 .Ft int

man/libbsd.7

@@ -0,0 +1,206 @@
+.\" 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.

man/mdX.3bsd

@@ -28,7 +28,10 @@
 .Lb libbsd
 .Sh SYNOPSIS
 .Fd #include <sys/types.h>
-.Fd #include <bsd/mdX.h>
+.Fd #include <mdX.h>
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft void
 .Fn MDXInit "MDX_CTX *context"
 .Ft void

man/nlist.3bsd

@@ -38,7 +38,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/nlist.h
+.In nlist.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft int
 .Fn nlist "const char *filename" "struct nlist *nl"
 .Sh DESCRIPTION

man/pidfile.3bsd

@@ -37,7 +37,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/libutil.h
+.In libutil.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft "struct pidfh *"
 .Fn pidfile_open "const char *path" "mode_t mode" "pid_t *pidptr"
 .Ft int

man/queue.3bsd

@@ -113,7 +113,10 @@
 .Nd implementations of singly-linked lists, singly-linked tail queues,
 lists and tail queues
 .Sh SYNOPSIS
-.In bsd/sys/queue.h
+.In sys/queue.h
+(See
+.Xr libbsd 7
+for include usage.)
 .\"
 .Fn SLIST_EMPTY "SLIST_HEAD *head"
 .Fn SLIST_ENTRY "TYPE"

man/radixsort.3bsd

@@ -41,7 +41,10 @@
 .Lb libbsd
 .Sh SYNOPSIS
 .In limits.h
-.In bsd/stdlib.h
+.In stdlib.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft int
 .Fn radixsort "const unsigned char **base" "int nmemb" "const unsigned char *table" "unsigned endbyte"
 .Ft int

man/readpassphrase.3bsd

@@ -28,7 +28,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.Fd #include <bsd/readpassphrase.h>
+.Fd #include <readpassphrase.h>
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft char *
 .Fn readpassphrase "const char *prompt" "char *buf" "size_t bufsiz" "int flags"
 .Sh DESCRIPTION

man/reallocarray.3bsd

@@ -42,7 +42,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/stdlib.h
+.In stdlib.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft void *
 .Fn reallocarray "void *ptr" "size_t nmemb" "size_t size"
 .Sh DESCRIPTION

man/reallocf.3bsd

@@ -42,7 +42,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/stdlib.h
+.In stdlib.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft void *
 .Fn reallocf "void *ptr" "size_t size"
 .Sh DESCRIPTION

man/setmode.3bsd

@@ -41,7 +41,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/unistd.h
+.In unistd.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft void *
 .Fn setmode "const char *mode_str"
 .Ft mode_t

man/setproctitle.3bsd

@@ -31,7 +31,10 @@
 .Lb libbsd
 .Sh SYNOPSIS
 .In sys/types.h
-.In bsd/unistd.h
+.In unistd.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft void
 .Fn setproctitle_init "int argc" "char *argv[]" "char *envp[]"
 .Ft void

man/stringlist.3bsd

@@ -41,7 +41,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/stringlist.h
+.In stringlist.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft StringList *
 .Fn sl_init "void"
 .Ft int

man/strlcpy.3bsd

@@ -25,7 +25,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/string.h
+.In string.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft size_t
 .Fn strlcpy "char *dst" "const char *src" "size_t size"
 .Ft size_t

man/strmode.3bsd

@@ -38,7 +38,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/string.h
+.In string.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft void
 .Fn strmode "mode_t mode" "char *bp"
 .Sh DESCRIPTION

man/strnstr.3bsd

@@ -43,7 +43,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/string.h
+.In string.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft char *
 .Fn strnstr "const char *big" "const char *little" "size_t len"
 .Sh DESCRIPTION

man/strtonum.3bsd

@@ -26,7 +26,10 @@
 .Lb libbsd
 .Sh SYNOPSIS
 .In limits.h
-.In bsd/stdlib.h
+.In stdlib.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft long long
 .Fo strtonum
 .Fa "const char *nptr"

man/tree.3bsd

@@ -76,7 +76,10 @@
 .Nm RB_REMOVE
 .Nd implementations of splay and red-black trees
 .Sh SYNOPSIS
-.In bsd/sys/tree.h
+.In sys/tree.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Fn SPLAY_PROTOTYPE NAME TYPE FIELD CMP
 .Fn SPLAY_GENERATE NAME TYPE FIELD CMP
 .Fn SPLAY_ENTRY TYPE

man/unvis.3bsd

@@ -39,7 +39,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/vis.h
+.In vis.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft int
 .Fn unvis "char *cp" "char c" "int *astate" "int flag"
 .Ft int

man/vis.3bsd

@@ -41,7 +41,10 @@
 .Lb libbsd
 .Sh SYNOPSIS
 .In stdlib.h
-.In bsd/vis.h
+.In vis.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft char *
 .Fn vis "char *dst" "int c" "int flag" "int nextc"
 .Ft int

man/wcslcpy.3bsd

@@ -46,7 +46,10 @@
 .ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
 .Lb libbsd
 .Sh SYNOPSIS
-.In bsd/wchar.h
+.In wchar.h
+(See
+.Xr libbsd 7
+for include usage.)
 .Ft size_t
 .Fn wcslcat "wchar_t *s1" "const wchar_t *s2" "size_t n"
 .Ft size_t