mirror of
https://gitlab.freedesktop.org/libbsd/libbsd.git
synced 2025-01-09 03:08:38 +01:00
308 lines
8.5 KiB
Groff
308 lines
8.5 KiB
Groff
.\" libbsd man page
|
|
.\"
|
|
.\" Copyright © 2017-2022 Guillem 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 August 3, 2022
|
|
.Dt libbsd 7
|
|
.Os
|
|
.Sh NAME
|
|
.Nm libbsd
|
|
.Nd utility functions from BSD systems
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm libbsd
|
|
library provides a set of 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 pkgconf 1
|
|
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,
|
|
which is a discouraged way, being 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 pkgconf 1
|
|
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
|
|
.Nm libbsd-ctor
|
|
static library that can be used to inject automatic constructors into a
|
|
program so that the
|
|
.Xr setproctitle_init 3
|
|
function gets invoked automatically at startup time.
|
|
This can be done with the
|
|
.Xr pkgconf 1
|
|
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 grp.h
|
|
.It In inttypes.h
|
|
.It In libutil.h
|
|
.It In md5.h
|
|
.It In netinet/ip_icmp.h
|
|
.It In nlist.h
|
|
.It In pwd.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/param.h
|
|
.It In sys/poll.h
|
|
.It In sys/queue.h
|
|
.It In sys/time.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 VARIANTS
|
|
Some functions have different prototypes depending on the BSD where they
|
|
originated from, and these various implementations provided are selectable
|
|
at build-time.
|
|
.Pp
|
|
This is the list of functions that provide multiple implementations:
|
|
.Pp
|
|
.Bl -tag -width 4m -compact
|
|
.It Fn strnvis 3
|
|
.It Fn strnunvis 3
|
|
.Nx
|
|
added
|
|
.Xr strnvis 3
|
|
and
|
|
.Xr strnunvis 3
|
|
but unfortunately made it incompatible with the existing one in
|
|
.Ox
|
|
and Freedesktop's libbsd (the former having existed for over ten years).
|
|
Despite this incompatibility being reported during development (see
|
|
http://gnats.netbsd.org/44977) they still shipped it.
|
|
Even more unfortunately
|
|
.Fx
|
|
and later MacOS picked up this incompatible implementation.
|
|
.Pp
|
|
Provide both implementations and default for now to the historical one to
|
|
avoid breakage, but we will switch to the
|
|
.Nx
|
|
one in a later release, which is internally consistent with the other
|
|
.Xr vis 3
|
|
functions and is now more widespread.
|
|
Define
|
|
.Dv LIBBSD_NETBSD_VIS
|
|
to switch to the
|
|
.Nx
|
|
one now.
|
|
Define
|
|
.Dv LIBBSD_OPENBSD_VIS
|
|
to keep using the
|
|
.Ox
|
|
one.
|
|
.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 3
|
|
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
|
|
.Xr getline 3
|
|
instead, which is available in many systems and required by
|
|
.St -p1003.1-2008 .
|
|
.It Fn fgetwln 3
|
|
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
|
|
.Xr fgetwc 3
|
|
instead, which is available in many systems and required by
|
|
.St -isoC-99
|
|
and
|
|
.St -p1003.1-2001 .
|
|
.It Fn funopen 3
|
|
Unportable, requires assistance from the stdio layer or some hook framework.
|
|
On GNU systems the
|
|
.Xr fopencookie 3
|
|
function can be used.
|
|
Otherwise the code needs to be prepared for neither of these functions being
|
|
available.
|
|
.El
|
|
.Sh SUPERSEDED
|
|
Some functions have been superseded by implementations in other system
|
|
libraries, and might disappear on the next SONAME bump, assuming those
|
|
other implementation have widespread deployment, or the implementations
|
|
are present in all major
|
|
.Nm libc
|
|
for example.
|
|
.Pp
|
|
.Bl -tag -width 4m -compact
|
|
.It Fn MD5Init 3
|
|
.It Fn MD5Update 3
|
|
.It Fn MD5Pad 3
|
|
.It Fn MD5Final 3
|
|
.It Fn MD5Transform 3
|
|
.It Fn MD5End 3
|
|
.It Fn MD5File 3
|
|
.It Fn MD5FileChunk 3
|
|
.It Fn MD5Data 3
|
|
The set of MD5 digest functions are now proxies for the implementations
|
|
provided by the
|
|
.Nm libmd
|
|
companion library, so it is advised to switch to use that directly instead.
|
|
.It Fn explicit_bzero 3
|
|
This function is provided by
|
|
.Nm glibc
|
|
2.25, and
|
|
.Nm musl
|
|
1.1.20.
|
|
.It Fn reallocarray 3
|
|
This function is provided by
|
|
.Nm glibc
|
|
2.26, and
|
|
.Nm musl
|
|
1.2.2.
|
|
.It Xr arc4random 3
|
|
.It Xr arc4random_buf 3
|
|
.It Xr arc4random_uniform 3
|
|
These functions are provided by
|
|
.Nm glibc
|
|
2.36.
|
|
Note that it does not provide the
|
|
.Xr arc4random_stir 3
|
|
and
|
|
.Xr arc4random_addrandom 3
|
|
functions.
|
|
.El
|
|
.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 pwcache 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 strtoi 3bsd ,
|
|
.Xr strtonum 3bsd ,
|
|
.Xr strtou 3bsd ,
|
|
.Xr timeradd 3bsd ,
|
|
.Xr timeval 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.
|