mirror of
https://gitlab.freedesktop.org/libbsd/libbsd.git
synced 2025-11-02 05:46:25 +01:00
man: Add new libbsd(7) library overview man page
This commit is contained in:
Guillem Jover
206
man/libbsd.7
Normal file
206
man/libbsd.7
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user