doc: initial effort to enable doxygen

Framework from libuEv.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg committed 2021-10-03 19:08:40 +02:00
1 parent 03598fc01e
commit 6537b11e34
33 files changed
+3781 -275

No files matched your search

+13
View File
@@ -3,6 +3,19 @@ SUBDIRS = src test
doc_DATA = README.md LICENSE ChangeLog.md doc_DATA = README.md LICENSE ChangeLog.md
EXTRA_DIST = README.md LICENSE ChangeLog.md EXTRA_DIST = README.md LICENSE ChangeLog.md
if ENABLE_DOXYGEN
SUBDIRS += doc
.PHONY: doc
doc:
$(MAKE) -C @top_builddir@/doc $@
## The distribution should include man pages, which are generated
dist-hook: doc
else
doc:
@echo "Doxygen documentation (html + man) disabled, skipping ..."
endif
## Check if tagged in git ## Check if tagged in git
release-hook: release-hook:
@if [ ! `git tag -l v$(PACKAGE_VERSION) | grep $(PACKAGE_VERSION)` ]; then \ @if [ ! `git tag -l v$(PACKAGE_VERSION) | grep $(PACKAGE_VERSION)` ]; then \
+18 -1
View File
@@ -5,7 +5,7 @@ AM_SILENT_RULES([yes])
AC_CONFIG_SRCDIR(src/lite.h) AC_CONFIG_SRCDIR(src/lite.h)
AC_CONFIG_HEADERS(config.h) AC_CONFIG_HEADERS(config.h)
AC_CONFIG_FILES([Makefile src/Makefile src/libite.pc test/Makefile]) AC_CONFIG_FILES([Makefile doc/Makefile doc/Doxyfile src/Makefile src/libite.pc test/Makefile])
AC_CONFIG_MACRO_DIR([m4]) AC_CONFIG_MACRO_DIR([m4])
AC_PROG_CC AC_PROG_CC
@@ -13,4 +13,21 @@ AC_PROG_INSTALL
m4_ifdef([AM_PROG_AR], [AM_PROG_AR]) m4_ifdef([AM_PROG_AR], [AM_PROG_AR])
LT_INIT LT_INIT
# Check for Doxygen and enable its features.
# For details, see m4/ax_prog_doxygen.m4 and
# http://www.bioinf.uni-freiburg.de/~mmann/HowTo/automake.html#doxygenSupport
DX_DOXYGEN_FEATURE(ON)
DX_DOT_FEATURE(OFF)
DX_CHI_FEATURE(OFF)
DX_RTF_FEATURE(OFF)
DX_XML_FEATURE(OFF)
DX_PDF_FEATURE(OFF)
DX_PS_FEATURE(OFF)
DX_CHM_FEATURE(OFF)
DX_HTML_FEATURE(ON)
DX_MAN_FEATURE(OFF)
DX_INIT_DOXYGEN(${PACKAGE_NAME}, [${top_builddir}/doc/Doxyfile], [${top_builddir}/doc])
AM_CONDITIONAL(ENABLE_DOXYGEN,[test "x${DX_FLAG_doc}" = x1])
AM_CONDITIONAL(ENABLE_HTML,[test "x${DX_FLAG_html}" = x1])
AC_OUTPUT AC_OUTPUT
+3
View File
@@ -0,0 +1,3 @@
html/*
libite.tag
Doxyfile
+2579
View File
File diff suppressed because it is too large. Load diff
+21
View File
@@ -0,0 +1,21 @@
EXTRA_DIST = Doxyfile.in
DISTCLEANFILES = libite.tag
if ENABLE_HTML
pkghtmldir = $(docdir)/html
pkghtml_DATA = html/*
#
# Doxygen rules from m4/ax_prog_doxygen.m4
#
@DX_RULES@
$(pkghtml_DATA): doxygen-doc
all-local: doc
clean-local:
-rm -rf html libite.tag
doc: doxygen-doc
endif
+585
View File
@@ -0,0 +1,585 @@
# ===========================================================================
# http://www.gnu.org/software/autoconf-archive/ax_prog_doxygen.html
# ===========================================================================
#
# SYNOPSIS
#
# DX_INIT_DOXYGEN(PROJECT-NAME, [DOXYFILE-PATH], [OUTPUT-DIR], ...)
# DX_DOXYGEN_FEATURE(ON|OFF)
# DX_DOT_FEATURE(ON|OFF)
# DX_HTML_FEATURE(ON|OFF)
# DX_CHM_FEATURE(ON|OFF)
# DX_CHI_FEATURE(ON|OFF)
# DX_MAN_FEATURE(ON|OFF)
# DX_RTF_FEATURE(ON|OFF)
# DX_XML_FEATURE(ON|OFF)
# DX_PDF_FEATURE(ON|OFF)
# DX_PS_FEATURE(ON|OFF)
#
# DESCRIPTION
#
# The DX_*_FEATURE macros control the default setting for the given
# Doxygen feature. Supported features are 'DOXYGEN' itself, 'DOT' for
# generating graphics, 'HTML' for plain HTML, 'CHM' for compressed HTML
# help (for MS users), 'CHI' for generating a seperate .chi file by the
# .chm file, and 'MAN', 'RTF', 'XML', 'PDF' and 'PS' for the appropriate
# output formats. The environment variable DOXYGEN_PAPER_SIZE may be
# specified to override the default 'a4wide' paper size.
#
# By default, HTML, PDF and PS documentation is generated as this seems to
# be the most popular and portable combination. MAN pages created by
# Doxygen are usually problematic, though by picking an appropriate subset
# and doing some massaging they might be better than nothing. CHM and RTF
# are specific for MS (note that you can't generate both HTML and CHM at
# the same time). The XML is rather useless unless you apply specialized
# post-processing to it.
#
# The macros mainly control the default state of the feature. The use can
# override the default by specifying --enable or --disable. The macros
# ensure that contradictory flags are not given (e.g.,
# --enable-doxygen-html and --enable-doxygen-chm,
# --enable-doxygen-anything with --disable-doxygen, etc.) Finally, each
# feature will be automatically disabled (with a warning) if the required
# programs are missing.
#
# Once all the feature defaults have been specified, call DX_INIT_DOXYGEN
# with the following parameters: a one-word name for the project for use
# as a filename base etc., an optional configuration file name (the
# default is '$(srcdir)/Doxyfile', the same as Doxygen's default), and an
# optional output directory name (the default is 'doxygen-doc'). To run
# doxygen multiple times for different configuration files and output
# directories provide more parameters: the second, forth, sixth, etc
# parameter are configuration file names and the third, fifth, seventh,
# etc parameter are output directories. No checking is done to catch
# duplicates.
#
# Automake Support
#
# The DX_RULES substitution can be used to add all needed rules to the
# Makefile. Note that this is a substitution without being a variable:
# only the @DX_RULES@ syntax will work.
#
# The provided targets are:
#
# doxygen-doc: Generate all doxygen documentation.
#
# doxygen-run: Run doxygen, which will generate some of the
# documentation (HTML, CHM, CHI, MAN, RTF, XML)
# but will not do the post processing required
# for the rest of it (PS, PDF).
#
# doxygen-ps: Generate doxygen PostScript documentation.
#
# doxygen-pdf: Generate doxygen PDF documentation.
#
# Note that by default these are not integrated into the automake targets.
# If doxygen is used to generate man pages, you can achieve this
# integration by setting man3_MANS to the list of man pages generated and
# then adding the dependency:
#
# $(man3_MANS): doxygen-doc
#
# This will cause make to run doxygen and generate all the documentation.
#
# The following variable is intended for use in Makefile.am:
#
# DX_CLEANFILES = everything to clean.
#
# Then add this variable to MOSTLYCLEANFILES.
#
# LICENSE
#
# Copyright (c) 2009 Oren Ben-Kiki <oren@ben-kiki.org>
# Copyright (c) 2015 Olaf Mandel <olaf@mandel.name>
#
# Copying and distribution of this file, with or without modification, are
# permitted in any medium without royalty provided the copyright notice
# and this notice are preserved. This file is offered as-is, without any
# warranty.
#serial 20
## ----------##
## Defaults. ##
## ----------##
DX_ENV=""
AC_DEFUN([DX_FEATURE_doc], ON)
AC_DEFUN([DX_FEATURE_dot], OFF)
AC_DEFUN([DX_FEATURE_man], OFF)
AC_DEFUN([DX_FEATURE_html], ON)
AC_DEFUN([DX_FEATURE_chm], OFF)
AC_DEFUN([DX_FEATURE_chi], OFF)
AC_DEFUN([DX_FEATURE_rtf], OFF)
AC_DEFUN([DX_FEATURE_xml], OFF)
AC_DEFUN([DX_FEATURE_pdf], ON)
AC_DEFUN([DX_FEATURE_ps], ON)
## --------------- ##
## Private macros. ##
## --------------- ##
# DX_ENV_APPEND(VARIABLE, VALUE)
# ------------------------------
# Append VARIABLE="VALUE" to DX_ENV for invoking doxygen and add it
# as a substitution (but not a Makefile variable). The substitution
# is skipped if the variable name is VERSION.
AC_DEFUN([DX_ENV_APPEND],
[AC_SUBST([DX_ENV], ["$DX_ENV $1='$2'"])dnl
m4_if([$1], [VERSION], [], [AC_SUBST([$1], [$2])dnl
AM_SUBST_NOTMAKE([$1])])dnl
])
# DX_DIRNAME_EXPR
# ---------------
# Expand into a shell expression prints the directory part of a path.
AC_DEFUN([DX_DIRNAME_EXPR],
[[expr ".$1" : '\(\.\)[^/]*$' \| "x$1" : 'x\(.*\)/[^/]*$']])
# DX_IF_FEATURE(FEATURE, IF-ON, IF-OFF)
# -------------------------------------
# Expands according to the M4 (static) status of the feature.
AC_DEFUN([DX_IF_FEATURE], [ifelse(DX_FEATURE_$1, ON, [$2], [$3])])
# DX_REQUIRE_PROG(VARIABLE, PROGRAM)
# ----------------------------------
# Require the specified program to be found for the DX_CURRENT_FEATURE to work.
AC_DEFUN([DX_REQUIRE_PROG], [
AC_PATH_TOOL([$1], [$2])
if test "$DX_FLAG_[]DX_CURRENT_FEATURE$$1" = 1; then
AC_MSG_WARN([$2 not found - will not DX_CURRENT_DESCRIPTION])
AC_SUBST(DX_FLAG_[]DX_CURRENT_FEATURE, 0)
fi
])
# DX_TEST_FEATURE(FEATURE)
# ------------------------
# Expand to a shell expression testing whether the feature is active.
AC_DEFUN([DX_TEST_FEATURE], [test "$DX_FLAG_$1" = 1])
# DX_CHECK_DEPEND(REQUIRED_FEATURE, REQUIRED_STATE)
# -------------------------------------------------
# Verify that a required features has the right state before trying to turn on
# the DX_CURRENT_FEATURE.
AC_DEFUN([DX_CHECK_DEPEND], [
test "$DX_FLAG_$1" = "$2" \
|| AC_MSG_ERROR([doxygen-DX_CURRENT_FEATURE ifelse([$2], 1,
requires, contradicts) doxygen-DX_CURRENT_FEATURE])
])
# DX_CLEAR_DEPEND(FEATURE, REQUIRED_FEATURE, REQUIRED_STATE)
# ----------------------------------------------------------
# Turn off the DX_CURRENT_FEATURE if the required feature is off.
AC_DEFUN([DX_CLEAR_DEPEND], [
test "$DX_FLAG_$1" = "$2" || AC_SUBST(DX_FLAG_[]DX_CURRENT_FEATURE, 0)
])
# DX_FEATURE_ARG(FEATURE, DESCRIPTION,
# CHECK_DEPEND, CLEAR_DEPEND,
# REQUIRE, DO-IF-ON, DO-IF-OFF)
# --------------------------------------------
# Parse the command-line option controlling a feature. CHECK_DEPEND is called
# if the user explicitly turns the feature on (and invokes DX_CHECK_DEPEND),
# otherwise CLEAR_DEPEND is called to turn off the default state if a required
# feature is disabled (using DX_CLEAR_DEPEND). REQUIRE performs additional
# requirement tests (DX_REQUIRE_PROG). Finally, an automake flag is set and
# DO-IF-ON or DO-IF-OFF are called according to the final state of the feature.
AC_DEFUN([DX_ARG_ABLE], [
AC_DEFUN([DX_CURRENT_FEATURE], [$1])
AC_DEFUN([DX_CURRENT_DESCRIPTION], [$2])
AC_ARG_ENABLE(doxygen-$1,
[AS_HELP_STRING(DX_IF_FEATURE([$1], [--disable-doxygen-$1],
[--enable-doxygen-$1]),
DX_IF_FEATURE([$1], [don't $2], [$2]))],
[
case "$enableval" in
#(
y|Y|yes|Yes|YES)
AC_SUBST([DX_FLAG_$1], 1)
$3
;; #(
n|N|no|No|NO)
AC_SUBST([DX_FLAG_$1], 0)
;; #(
*)
AC_MSG_ERROR([invalid value '$enableval' given to doxygen-$1])
;;
esac
], [
AC_SUBST([DX_FLAG_$1], [DX_IF_FEATURE([$1], 1, 0)])
$4
])
if DX_TEST_FEATURE([$1]); then
$5
:
fi
if DX_TEST_FEATURE([$1]); then
$6
:
else
$7
:
fi
])
## -------------- ##
## Public macros. ##
## -------------- ##
# DX_XXX_FEATURE(DEFAULT_STATE)
# -----------------------------
AC_DEFUN([DX_DOXYGEN_FEATURE], [AC_DEFUN([DX_FEATURE_doc], [$1])])
AC_DEFUN([DX_DOT_FEATURE], [AC_DEFUN([DX_FEATURE_dot], [$1])])
AC_DEFUN([DX_MAN_FEATURE], [AC_DEFUN([DX_FEATURE_man], [$1])])
AC_DEFUN([DX_HTML_FEATURE], [AC_DEFUN([DX_FEATURE_html], [$1])])
AC_DEFUN([DX_CHM_FEATURE], [AC_DEFUN([DX_FEATURE_chm], [$1])])
AC_DEFUN([DX_CHI_FEATURE], [AC_DEFUN([DX_FEATURE_chi], [$1])])
AC_DEFUN([DX_RTF_FEATURE], [AC_DEFUN([DX_FEATURE_rtf], [$1])])
AC_DEFUN([DX_XML_FEATURE], [AC_DEFUN([DX_FEATURE_xml], [$1])])
AC_DEFUN([DX_XML_FEATURE], [AC_DEFUN([DX_FEATURE_xml], [$1])])
AC_DEFUN([DX_PDF_FEATURE], [AC_DEFUN([DX_FEATURE_pdf], [$1])])
AC_DEFUN([DX_PS_FEATURE], [AC_DEFUN([DX_FEATURE_ps], [$1])])
# DX_INIT_DOXYGEN(PROJECT, [CONFIG-FILE], [OUTPUT-DOC-DIR], ...)
# --------------------------------------------------------------
# PROJECT also serves as the base name for the documentation files.
# The default CONFIG-FILE is "$(srcdir)/Doxyfile" and OUTPUT-DOC-DIR is
# "doxygen-doc".
# More arguments are interpreted as interleaved CONFIG-FILE and
# OUTPUT-DOC-DIR values.
AC_DEFUN([DX_INIT_DOXYGEN], [
# Files:
AC_SUBST([DX_PROJECT], [$1])
AC_SUBST([DX_CONFIG], ['ifelse([$2], [], [$(srcdir)/Doxyfile], [$2])'])
AC_SUBST([DX_DOCDIR], ['ifelse([$3], [], [doxygen-doc], [$3])'])
m4_if(m4_eval(3 < m4_count($@)), 1, [m4_for([DX_i], 4, m4_count($@), 2,
[AC_SUBST([DX_CONFIG]m4_eval(DX_i[/2]),
'm4_default_nblank_quoted(m4_argn(DX_i, $@),
[$(srcdir)/Doxyfile])')])])dnl
m4_if(m4_eval(3 < m4_count($@)), 1, [m4_for([DX_i], 5, m4_count($@,), 2,
[AC_SUBST([DX_DOCDIR]m4_eval([(]DX_i[-1)/2]),
'm4_default_nblank_quoted(m4_argn(DX_i, $@),
[doxygen-doc])')])])dnl
m4_define([DX_loop], m4_dquote(m4_if(m4_eval(3 < m4_count($@)), 1,
[m4_for([DX_i], 4, m4_count($@), 2, [, m4_eval(DX_i[/2])])],
[])))dnl
# Environment variables used inside doxygen.cfg:
DX_ENV_APPEND(SRCDIR, $srcdir)
DX_ENV_APPEND(PROJECT, $DX_PROJECT)
DX_ENV_APPEND(VERSION, $PACKAGE_VERSION)
# Doxygen itself:
DX_ARG_ABLE(doc, [generate any doxygen documentation],
[],
[],
[DX_REQUIRE_PROG([DX_DOXYGEN], doxygen)
DX_REQUIRE_PROG([DX_PERL], perl)],
[DX_ENV_APPEND(PERL_PATH, $DX_PERL)])
# Dot for graphics:
DX_ARG_ABLE(dot, [generate graphics for doxygen documentation],
[DX_CHECK_DEPEND(doc, 1)],
[DX_CLEAR_DEPEND(doc, 1)],
[DX_REQUIRE_PROG([DX_DOT], dot)],
[DX_ENV_APPEND(HAVE_DOT, YES)
DX_ENV_APPEND(DOT_PATH, [`DX_DIRNAME_EXPR($DX_DOT)`])],
[DX_ENV_APPEND(HAVE_DOT, NO)])
# Man pages generation:
DX_ARG_ABLE(man, [generate doxygen manual pages],
[DX_CHECK_DEPEND(doc, 1)],
[DX_CLEAR_DEPEND(doc, 1)],
[],
[DX_ENV_APPEND(GENERATE_MAN, YES)],
[DX_ENV_APPEND(GENERATE_MAN, NO)])
# RTF file generation:
DX_ARG_ABLE(rtf, [generate doxygen RTF documentation],
[DX_CHECK_DEPEND(doc, 1)],
[DX_CLEAR_DEPEND(doc, 1)],
[],
[DX_ENV_APPEND(GENERATE_RTF, YES)],
[DX_ENV_APPEND(GENERATE_RTF, NO)])
# XML file generation:
DX_ARG_ABLE(xml, [generate doxygen XML documentation],
[DX_CHECK_DEPEND(doc, 1)],
[DX_CLEAR_DEPEND(doc, 1)],
[],
[DX_ENV_APPEND(GENERATE_XML, YES)],
[DX_ENV_APPEND(GENERATE_XML, NO)])
# (Compressed) HTML help generation:
DX_ARG_ABLE(chm, [generate doxygen compressed HTML help documentation],
[DX_CHECK_DEPEND(doc, 1)],
[DX_CLEAR_DEPEND(doc, 1)],
[DX_REQUIRE_PROG([DX_HHC], hhc)],
[DX_ENV_APPEND(HHC_PATH, $DX_HHC)
DX_ENV_APPEND(GENERATE_HTML, YES)
DX_ENV_APPEND(GENERATE_HTMLHELP, YES)],
[DX_ENV_APPEND(GENERATE_HTMLHELP, NO)])
# Seperate CHI file generation.
DX_ARG_ABLE(chi, [generate doxygen seperate compressed HTML help index file],
[DX_CHECK_DEPEND(chm, 1)],
[DX_CLEAR_DEPEND(chm, 1)],
[],
[DX_ENV_APPEND(GENERATE_CHI, YES)],
[DX_ENV_APPEND(GENERATE_CHI, NO)])
# Plain HTML pages generation:
DX_ARG_ABLE(html, [generate doxygen plain HTML documentation],
[DX_CHECK_DEPEND(doc, 1) DX_CHECK_DEPEND(chm, 0)],
[DX_CLEAR_DEPEND(doc, 1) DX_CLEAR_DEPEND(chm, 0)],
[],
[DX_ENV_APPEND(GENERATE_HTML, YES)],
[DX_TEST_FEATURE(chm) || DX_ENV_APPEND(GENERATE_HTML, NO)])
# PostScript file generation:
DX_ARG_ABLE(ps, [generate doxygen PostScript documentation],
[DX_CHECK_DEPEND(doc, 1)],
[DX_CLEAR_DEPEND(doc, 1)],
[DX_REQUIRE_PROG([DX_LATEX], latex)
DX_REQUIRE_PROG([DX_MAKEINDEX], makeindex)
DX_REQUIRE_PROG([DX_DVIPS], dvips)
DX_REQUIRE_PROG([DX_EGREP], egrep)])
# PDF file generation:
DX_ARG_ABLE(pdf, [generate doxygen PDF documentation],
[DX_CHECK_DEPEND(doc, 1)],
[DX_CLEAR_DEPEND(doc, 1)],
[DX_REQUIRE_PROG([DX_PDFLATEX], pdflatex)
DX_REQUIRE_PROG([DX_MAKEINDEX], makeindex)
DX_REQUIRE_PROG([DX_EGREP], egrep)])
# LaTeX generation for PS and/or PDF:
if DX_TEST_FEATURE(ps) || DX_TEST_FEATURE(pdf); then
DX_ENV_APPEND(GENERATE_LATEX, YES)
else
DX_ENV_APPEND(GENERATE_LATEX, NO)
fi
# Paper size for PS and/or PDF:
AC_ARG_VAR(DOXYGEN_PAPER_SIZE,
[a4wide (default), a4, letter, legal or executive])
case "$DOXYGEN_PAPER_SIZE" in
#(
"")
AC_SUBST(DOXYGEN_PAPER_SIZE, "")
;; #(
a4wide|a4|letter|legal|executive)
DX_ENV_APPEND(PAPER_SIZE, $DOXYGEN_PAPER_SIZE)
;; #(
*)
AC_MSG_ERROR([unknown DOXYGEN_PAPER_SIZE='$DOXYGEN_PAPER_SIZE'])
;;
esac
# Rules:
AS_IF([[test $DX_FLAG_html -eq 1]],
[[DX_SNIPPET_html="## ------------------------------- ##
## Rules specific for HTML output. ##
## ------------------------------- ##
DX_CLEAN_HTML = \$(DX_DOCDIR)/html]dnl
m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
\$(DX_DOCDIR]DX_i[)/html]])[
"]],
[[DX_SNIPPET_html=""]])
AS_IF([[test $DX_FLAG_chi -eq 1]],
[[DX_SNIPPET_chi="
DX_CLEAN_CHI = \$(DX_DOCDIR)/\$(PACKAGE).chi]dnl
m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
\$(DX_DOCDIR]DX_i[)/\$(PACKAGE).chi]])["]],
[[DX_SNIPPET_chi=""]])
AS_IF([[test $DX_FLAG_chm -eq 1]],
[[DX_SNIPPET_chm="## ------------------------------ ##
## Rules specific for CHM output. ##
## ------------------------------ ##
DX_CLEAN_CHM = \$(DX_DOCDIR)/chm]dnl
m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
\$(DX_DOCDIR]DX_i[)/chm]])[\
${DX_SNIPPET_chi}
"]],
[[DX_SNIPPET_chm=""]])
AS_IF([[test $DX_FLAG_man -eq 1]],
[[DX_SNIPPET_man="## ------------------------------ ##
## Rules specific for MAN output. ##
## ------------------------------ ##
DX_CLEAN_MAN = \$(DX_DOCDIR)/man]dnl
m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
\$(DX_DOCDIR]DX_i[)/man]])[
"]],
[[DX_SNIPPET_man=""]])
AS_IF([[test $DX_FLAG_rtf -eq 1]],
[[DX_SNIPPET_rtf="## ------------------------------ ##
## Rules specific for RTF output. ##
## ------------------------------ ##
DX_CLEAN_RTF = \$(DX_DOCDIR)/rtf]dnl
m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
\$(DX_DOCDIR]DX_i[)/rtf]])[
"]],
[[DX_SNIPPET_rtf=""]])
AS_IF([[test $DX_FLAG_xml -eq 1]],
[[DX_SNIPPET_xml="## ------------------------------ ##
## Rules specific for XML output. ##
## ------------------------------ ##
DX_CLEAN_XML = \$(DX_DOCDIR)/xml]dnl
m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
\$(DX_DOCDIR]DX_i[)/xml]])[
"]],
[[DX_SNIPPET_xml=""]])
AS_IF([[test $DX_FLAG_ps -eq 1]],
[[DX_SNIPPET_ps="## ----------------------------- ##
## Rules specific for PS output. ##
## ----------------------------- ##
DX_CLEAN_PS = \$(DX_DOCDIR)/\$(PACKAGE).ps]dnl
m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
\$(DX_DOCDIR]DX_i[)/\$(PACKAGE).ps]])[
DX_PS_GOAL = doxygen-ps
doxygen-ps: \$(DX_CLEAN_PS)
]m4_foreach([DX_i], [DX_loop],
[[\$(DX_DOCDIR]DX_i[)/\$(PACKAGE).ps: \$(DX_DOCDIR]DX_i[)/\$(PACKAGE).tag
\$(DX_V_LATEX)cd \$(DX_DOCDIR]DX_i[)/latex; \\
rm -f *.aux *.toc *.idx *.ind *.ilg *.log *.out; \\
\$(DX_LATEX) refman.tex; \\
\$(DX_MAKEINDEX) refman.idx; \\
\$(DX_LATEX) refman.tex; \\
countdown=5; \\
while \$(DX_EGREP) 'Rerun (LaTeX|to get cross-references right)' \\
refman.log > /dev/null 2>&1 \\
&& test \$\$countdown -gt 0; do \\
\$(DX_LATEX) refman.tex; \\
countdown=\`expr \$\$countdown - 1\`; \\
done; \\
\$(DX_DVIPS) -o ../\$(PACKAGE).ps refman.dvi
]])["]],
[[DX_SNIPPET_ps=""]])
AS_IF([[test $DX_FLAG_pdf -eq 1]],
[[DX_SNIPPET_pdf="## ------------------------------ ##
## Rules specific for PDF output. ##
## ------------------------------ ##
DX_CLEAN_PDF = \$(DX_DOCDIR)/\$(PACKAGE).pdf]dnl
m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
\$(DX_DOCDIR]DX_i[)/\$(PACKAGE).pdf]])[
DX_PDF_GOAL = doxygen-pdf
doxygen-pdf: \$(DX_CLEAN_PDF)
]m4_foreach([DX_i], [DX_loop],
[[\$(DX_DOCDIR]DX_i[)/\$(PACKAGE).pdf: \$(DX_DOCDIR]DX_i[)/\$(PACKAGE).tag
\$(DX_V_LATEX)cd \$(DX_DOCDIR]DX_i[)/latex; \\
rm -f *.aux *.toc *.idx *.ind *.ilg *.log *.out; \\
\$(DX_PDFLATEX) refman.tex; \\
\$(DX_MAKEINDEX) refman.idx; \\
\$(DX_PDFLATEX) refman.tex; \\
countdown=5; \\
while \$(DX_EGREP) 'Rerun (LaTeX|to get cross-references right)' \\
refman.log > /dev/null 2>&1 \\
&& test \$\$countdown -gt 0; do \\
\$(DX_PDFLATEX) refman.tex; \\
countdown=\`expr \$\$countdown - 1\`; \\
done; \\
mv refman.pdf ../\$(PACKAGE).pdf
]])["]],
[[DX_SNIPPET_pdf=""]])
AS_IF([[test $DX_FLAG_ps -eq 1 -o $DX_FLAG_pdf -eq 1]],
[[DX_SNIPPET_latex="## ------------------------------------------------- ##
## Rules specific for LaTeX (shared for PS and PDF). ##
## ------------------------------------------------- ##
DX_V_LATEX = \$(_DX_v_LATEX_\$(V))
_DX_v_LATEX_ = \$(_DX_v_LATEX_\$(AM_DEFAULT_VERBOSITY))
_DX_v_LATEX_0 = @echo \" LATEX \" \$][@;
DX_CLEAN_LATEX = \$(DX_DOCDIR)/latex]dnl
m4_foreach([DX_i], [m4_shift(DX_loop)], [[\\
\$(DX_DOCDIR]DX_i[)/latex]])[
"]],
[[DX_SNIPPET_latex=""]])
AS_IF([[test $DX_FLAG_doc -eq 1]],
[[DX_SNIPPET_doc="## --------------------------------- ##
## Format-independent Doxygen rules. ##
## --------------------------------- ##
${DX_SNIPPET_html}\
${DX_SNIPPET_chm}\
${DX_SNIPPET_man}\
${DX_SNIPPET_rtf}\
${DX_SNIPPET_xml}\
${DX_SNIPPET_ps}\
${DX_SNIPPET_pdf}\
${DX_SNIPPET_latex}\
DX_V_DXGEN = \$(_DX_v_DXGEN_\$(V))
_DX_v_DXGEN_ = \$(_DX_v_DXGEN_\$(AM_DEFAULT_VERBOSITY))
_DX_v_DXGEN_0 = @echo \" DXGEN \" \$<;
.PHONY: doxygen-run doxygen-doc \$(DX_PS_GOAL) \$(DX_PDF_GOAL)
.INTERMEDIATE: doxygen-run \$(DX_PS_GOAL) \$(DX_PDF_GOAL)
doxygen-run:]m4_foreach([DX_i], [DX_loop],
[[ \$(DX_DOCDIR]DX_i[)/\$(PACKAGE).tag]])[
doxygen-doc: doxygen-run \$(DX_PS_GOAL) \$(DX_PDF_GOAL)
]m4_foreach([DX_i], [DX_loop],
[[\$(DX_DOCDIR]DX_i[)/\$(PACKAGE).tag: \$(DX_CONFIG]DX_i[) \$(pkginclude_HEADERS)
\$(DX_V_DXGEN)\$(DX_ENV) DOCDIR=\$(DX_DOCDIR]DX_i[) \$(DX_DOXYGEN) \$(DX_CONFIG]DX_i[)
\$(A""M_V_at)echo Timestamp >\$][@
]])dnl
[DX_CLEANFILES = \\]
m4_foreach([DX_i], [DX_loop],
[[ \$(DX_DOCDIR]DX_i[)/doxygen_sqlite3.db \\
\$(DX_DOCDIR]DX_i[)/\$(PACKAGE).tag \\
]])dnl
[ -r \\
\$(DX_CLEAN_HTML) \\
\$(DX_CLEAN_CHM) \\
\$(DX_CLEAN_CHI) \\
\$(DX_CLEAN_MAN) \\
\$(DX_CLEAN_RTF) \\
\$(DX_CLEAN_XML) \\
\$(DX_CLEAN_PS) \\
\$(DX_CLEAN_PDF) \\
\$(DX_CLEAN_LATEX)"]],
[[DX_SNIPPET_doc=""]])
AC_SUBST([DX_RULES],
["${DX_SNIPPET_doc}"])dnl
AM_SUBST_NOTMAKE([DX_RULES])
#For debugging:
#echo DX_FLAG_doc=$DX_FLAG_doc
#echo DX_FLAG_dot=$DX_FLAG_dot
#echo DX_FLAG_man=$DX_FLAG_man
#echo DX_FLAG_html=$DX_FLAG_html
#echo DX_FLAG_chm=$DX_FLAG_chm
#echo DX_FLAG_chi=$DX_FLAG_chi
#echo DX_FLAG_rtf=$DX_FLAG_rtf
#echo DX_FLAG_xml=$DX_FLAG_xml
#echo DX_FLAG_pdf=$DX_FLAG_pdf
#echo DX_FLAG_ps=$DX_FLAG_ps
#echo DX_ENV=$DX_ENV
])
+11 -5
View File
@@ -15,19 +15,25 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file chomp.c
* @author Joachim Wiberg
* @date 2014-2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <string.h> #include <string.h>
/** /**
* chomp - Perl like chomp function, chop off last char(s) if newline. * Perl like chomp function, chop off last char(s) if newline.
* @str: String to chomp * @param str String to chomp
* *
* This function is like Perl chomp, but it's set to chop of all * This function is like Perl chomp, but it's set to chop of all
* trailing newlines. Useful in combination with fgets(). * trailing newlines. Useful in combination with fgets().
* *
* Returns: * @returns @a str, or @c NULL with @a errno set, if @a str is not a valid pointer.
* If @str is a valid pointer this function returns @str, otherwise * @exception EINVAL if the input argument is not a valid pointer.
* @errno is set to %EINVAL and this function returns %NULL.
*/ */
char *chomp(char *str) char *chomp(char *str)
{ {
+21
View File
@@ -15,11 +15,32 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file conio.c
* @author Joachim Wiberg
* @date 2009-2021
* @copyright ISC License
*/
#include <poll.h> #include <poll.h>
#include <stdio.h> #include <stdio.h>
#include <termios.h> #include <termios.h>
#include <unistd.h> #include <unistd.h>
/**
* Probe terminal size
* @param row pointer to integer to store number of rows
* @param col pointer to integer to store number of columns
*
* This function checks if stdin and stdout isatty() and then sets the
* TTY in raw mode to silently ask the size using ANSI escape sequences.
* This is achieved by trying to go to corner 999,999 followed by
* querying the cursor position. Afterwards the TTY is returned to the
* state if was before, e.g. cooked. The number of rows and columns is
* returned in the input arguments to this function.
*
* If stdio is @a not a TTY, then a default 24x80 is returned.
*/
void initscr(int *row, int *col) void initscr(int *row, int *col)
{ {
if (!row || !col) if (!row || !col)
+34 -30
View File
@@ -21,6 +21,13 @@
* THE SOFTWARE. * THE SOFTWARE.
*/ */
/**
* @file copyfile.c
* @author Claudio Matsuoka
* @date 2008
* @copyright MIT License
*/
#include <errno.h> #include <errno.h>
#include <fcntl.h> #include <fcntl.h>
#include <stdlib.h> #include <stdlib.h>
@@ -94,28 +101,30 @@ static void set_mtime(int in, int out)
} }
/** /**
* copyfile - Copy a file to another. * Copy a file to another.
* @src: Full path name to source file. * @param src Full path name to source file.
* @dst: Full path name to target file. * @param dst Full path name to target file.
* @len: Number of bytes to copy, zero (0) for entire file. * @param len Number of bytes to copy, zero (0) for entire file.
* @opt: An option mask of %LITE_FOPT_COPYFILE_SYM, %LITE_FOPT_KEEP_MTIME * @param opt An option mask of ::LITE_FOPT_COPYFILE_SYM, ::LITE_FOPT_KEEP_MTIME
* *
* This is a C implementation of the command line cp(1) utility. It is one * This is a C implementation of the command line cp(1) utility. It is one
* of the classic missing links in the UNIX C library. This version is from * of the classic missing links in the UNIX C library. This version is from
* the finit project, http://helllabs.org/finit/, which is a reimplementation * the finit project, http://helllabs.org/finit/, which is a reimplementation
* of fastinit for the Asus EeePC. * of fastinit for the Asus EeePC.
* *
* The @opt field replaces the @sym argument in previous releases and * The @a opt field replaces the @a sym argument in previous releases
* works as follows. To maintain backwards compatibility with @sym * and works as follows. To maintain backwards compatibility with @a
* the %LITE_FOPT_COPYFILE_SYM maintains a value of 1: * sym the ::LITE_FOPT_COPYFILE_SYM has a value of @c 1. Supported
* option flags are:
* *
* %LITE_FOPT_COPYFILE_SYM: Recreate symlink or follow to copy target * - ::LITE_FOPT_COPYFILE_SYM Recreate symlink or follow to copy target
* %LITE_FOPT_KEEP_MTIME: Preserve modification time * - ::LITE_FOPT_KEEP_MTIME Preserve modification time
* *
* Returns: * @returns The number of bytes copied, or zero, which may be an error
* The number of bytes copied, zero may be error (check errno!), but it * (check @a errno, see Exceptions below), but it may also indicate that
* may also indicate that @src was empty. If @src is a directory @errno * @a src was empty. See exceptions, below.
* will be set to %EISDIR since copyfile() is not recursive. *
* @exception EISDIR if @a src is a directory, since copyfile() is not recursive.
*/ */
ssize_t copyfile(const char *src, const char *dst, int len, int opt) ssize_t copyfile(const char *src, const char *dst, int len, int opt)
{ {
@@ -203,20 +212,19 @@ exit:
} }
/** /**
* movefile - Move a file to another location * Move a file to another location
* @src: Source file. * @param src Source file.
* @dst: Target file, or location. * @param dst Target file, or location.
* *
* This is a C implementation of the command line mv(1) utility. * This is a C implementation of the command line mv(1) utility.
* Usually the rename() API is sufficient, but not when moving across * Usually the rename() API is sufficient, but not when moving across
* file system boundaries. * file system boundaries.
* *
* The @src argument must include the full path to the source file, * The @p src argument must include the full path to the source file,
* whereas the @dst argument may only be a directory, in which case the * whereas the @p dst argument may only be a directory, in which case
* same file name from @src is used. * the same file name from @p src is used.
* *
* Returns: * @returns POSIX OK(0), or non-zero with @a errno set.
* POSIX OK(0), or non-zero with errno set.
*/ */
int movefile(const char *src, const char *dst) int movefile(const char *src, const char *dst)
{ {
@@ -246,15 +254,11 @@ int movefile(const char *src, const char *dst)
} }
/** /**
* fcopyfile - Copy between FILE *fp. * Copy between FILE *fp.
* @src: Source FILE. * @param src Source FILE.
* @dst: Destination FILE. * @param dst Destination FILE.
* *
* Function takes signals into account and will restart the syscalls as * @returns POSIX OK(0), or non-zero with @a errno set on error.
* long as error is %EINTR.
*
* Returns:
* POSIX OK(0), or non-zero with errno set on error.
*/ */
int fcopyfile(FILE *src, FILE *dst) int fcopyfile(FILE *src, FILE *dst)
{ {
+24 -20
View File
@@ -15,6 +15,13 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file dir.c
* @author Joachim Wiberg
* @date 2008-2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <dirent.h> #include <dirent.h>
#include <stdlib.h> #include <stdlib.h>
@@ -48,32 +55,29 @@ static int matcher(const struct dirent *entry)
} }
/** /**
* dir - List all files of a certain type in the given directory. * List all files of a certain type in the given directory.
* @dir: Base directory for dir operation. * @param dir Base directory for dir operation.
* @type: File type suffix, e.g. ".cfg". * @param type File type suffix, e.g. ".cfg".
* @filter: Optional file name filter. * @param filter Optional file name filter.
* @list: Pointer to an array of file names. * @param list Pointer to an array of file names.
* @strip: Flag, if set dir() strips the file type. * @param strip Flag, if set dir() strips the file type.
* *
* This function returns a @list of files, matching the @type suffix, * This function returns a @a list of files, matching the @a type
* in the given directory @dir. * suffix, in the given directory @a dir.
* *
* The @list argument is a pointer to where to store the dynamically * The @a list argument is a pointer to where to store the dynamically
* allocated list of file names. This list should be free'd by first * allocated list of file names. This list should be free'd by first
* calling free() on each file name and then on the list itself. * calling free() on each file name and then on the list itself.
* *
* If @filter is not %NULL it will be called for each file found. If * If @a filter is not @c NULL it will be called for each file found.
* @filter returns non-zero the @file argument will be included in the * If @a filter returns non-zero the @a file argument is included in the
* resulting @list. If @filter returns zero for given @file it will * resulting @a list. If @a filter returns zero for given @a file it is
* be discarded. * discarded. If the @a strip flag is set the resulting @a list of
* files has their file type stripped, including the dot. So a match
* "config0.cfg" would be returned as "config0".
* *
* If the @strip flag is set the resulting @list of files has their * @returns The number of files in @a list, zero if no matching files of
* file type stripped, including the dot. So a match "config0.cfg" * @a type, or non-zero on error with @a errno set.
* would be returned as "config0".
*
* Returns:
* Number of files in @list, zero if no matching files of @type, or
* non-zero on error with @errno set.
*/ */
int dir(const char *dir, const char *type, int (*filter) (const char *file), char ***list, int strip) int dir(const char *dir, const char *type, int (*filter) (const char *file), char ***list, int strip)
{ {
+11 -5
View File
@@ -15,6 +15,13 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file erasef.c
* @author Joachim Wiberg
* @date 2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <stdio.h> #include <stdio.h>
#include <stdarg.h> #include <stdarg.h>
@@ -24,16 +31,15 @@
#include "lite.h" #include "lite.h"
/** /**
* erasef - Like erase() but with formatted string support * Like erase() but with formatted string support.
* @fmt: Formatted string to be composed into a pathname * @param fmt Formatted string to be composed into a pathname
* *
* This is a wrapper for the erase() function in lite.h, lessening the * This is a wrapper for the erase() function in lite.h, lessening the
* burden of having to compose the filename from parts in a seprate * burden of having to compose the filename from parts in a seprate
* buffer. * buffer.
* *
* Returns: * @returns Upon successful completion erasef() returns POSIX OK(0),
* Upon successful completion erasef() returns POSIX OK(0), otherwise, * otherwise, -1 is returned and @a errno is set to indicate the error.
* -1 is returned and errno is set to indicate the error.
*/ */
int erasef(const char *fmt, ...) int erasef(const char *fmt, ...)
{ {
+10 -4
View File
@@ -21,15 +21,21 @@
* THE SOFTWARE. * THE SOFTWARE.
*/ */
/**
* @file fexist.c
* @author Claudio Matsuoka
* @date 2008
* @copyright MIT License
*/
#include <errno.h> #include <errno.h>
#include <unistd.h> #include <unistd.h>
/** /**
* fexist - Check if a file exists in the file system. * Check if a file exists in the file system.
* @file: File to look for, with full path. * @param file File to look for, with full path.
* *
* Returns: * @returns @c TRUE(1) if the @a file exists, otherwise @c FALSE(0).
* %TRUE(1) if the file exists, otherwise %FALSE(0).
*/ */
int fexist(const char *file) int fexist(const char *file)
{ {
+10 -4
View File
@@ -21,15 +21,21 @@
* THE SOFTWARE. * THE SOFTWARE.
*/ */
/**
* @file fisdir.c
* @author Claudio Matsuoka
* @date 2008
* @copyright MIT License
*/
#include <sys/stat.h> #include <sys/stat.h>
#include <unistd.h> #include <unistd.h>
/** /**
* fisdir - Check if a path exists and is a directory. * Check if a path exists and is a directory.
* @path: Path to file or directory * @param path Path to file or directory
* *
* Returns: * @returns @c TRUE(1) if @p path exists and is a directory, otherwise @c FALSE(0).
* %TRUE(1) if @path exists and is a directory, otherwise %FALSE(0).
*/ */
int fisdir(const char *path) int fisdir(const char *path)
{ {
+13 -6
View File
@@ -15,22 +15,29 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file fopenf.c
* @author Joachim Wiberg
* @date 2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <stdio.h> #include <stdio.h>
#include <stdarg.h> #include <stdarg.h>
#include <stdlib.h> #include <stdlib.h>
/** /**
* fopenf - Open a file based on the formatted string and optional arguments * Open a file based on the formatted string and optional arguments
* @mode: Last argument in optional list, if omitted EINVAL * @param mode An fopen() mode string, e.g. "w+"
* @fmt: Formatted string to be composed into a pathname * @param fmt Formatted string to be composed into a pathname
* *
* This function is an extension to the fopen() family, lessening the burden * This function is an extension to the fopen() family, lessening the burden
* of first having to compose the filename from parts in a seprate buffer. * of first having to compose the filename from parts in a seprate buffer.
* *
* Returns: * @returns Upon successful completion, fopenf() returns a FILE pointer.
* Upon successful completion fopenf() a FILE pointer. Otherwise, NULL * Otherwise, @c NULL is returned and @a errno is set to indicate the
* is returned and errno is set to indicate the error. * error.
*/ */
FILE *fopenf(const char *mode, const char *fmt, ...) FILE *fopenf(const char *mode, const char *fmt, ...)
{ {
+26 -4
View File
@@ -24,6 +24,13 @@
* THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/ */
/**
* @file fparseln.c
* @author Christos Zoulas
* @date 1997
* @copyright 2-clause BSD License
*/
#include <assert.h> #include <assert.h>
#include <errno.h> #include <errno.h>
#include <stdio.h> #include <stdio.h>
@@ -63,10 +70,25 @@ isescaped(const char *sp, const char *p, int esc)
} }
/* fparseln(): /**
* Read a line from a file parsing continuations ending in \ * Read a line from a file parsing continuations and trailing newlines
* and eliminating trailing newlines, or comments starting with * @param fp FILE pointer to read from
* the comment char. * @param size The resulting length of the string, unused if @c NULL
* @param lineno Incremented with number of lines read, unused if @c NULL
* @param str Characters to look for, escape character, continuation, and comment
* @param flags ::FPARSELN_UNESCCOMM, ::FPARSELN_UNESCCONT, ::FPARSELN_UNESCESC, ::FPARSELN_UNESCREST, ::FPARSELN_UNESCALL
*
* This function reads a line from a file, parsing continuations ending
* in '\' and eliminating trailing newlines, or comments starting with
* the comment char '#'.
*
* If @a size is not @c NULL, the resulting length of the returned string
* is stored in @a size.
*
* If @a lineno is not @c NULL, it is incremented for each actual line
* read from @a fp.
*
* @returns the line read from @a fp, or @c NULL on EOF or error.
*/ */
char * char *
fparseln(FILE *fp, size_t *size, size_t *lineno, const char str[3], int flags) fparseln(FILE *fp, size_t *size, size_t *lineno, const char str[3], int flags)
+11 -4
View File
@@ -15,20 +15,27 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file fremove.c
* @author Joachim Wiberg
* @date 2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <stdio.h> #include <stdio.h>
#include <stdarg.h> #include <stdarg.h>
#include <stdlib.h> #include <stdlib.h>
/** /**
* fremove - Remove a file based on the formatted string and optional arguments * Remove a file based on the formatted string and optional arguments
* @fmt: Formatted string to be composed into a pathname * @param fmt Formatted string to be composed into a pathname
* *
* This function is an extension to remove(), lessening the burden of * This function is an extension to remove(), lessening the burden of
* first having to compose the filename from parts in a seprate buffer. * first having to compose the filename from parts in a seprate buffer.
* *
* Returns: * @returns same as remove(3), with an extra @a errno, @c ENOBUFS if
* Return value for remove(3). * alloca() fails to get a temporary buffer for composing the file name.
*/ */
int fremove(const char *fmt, ...) int fremove(const char *fmt, ...)
{ {
+18 -11
View File
@@ -21,25 +21,32 @@
* THE SOFTWARE. * THE SOFTWARE.
*/ */
/**
* @file fsendfile.c
* @author Tobias Waldekranz
* @date 2013
* @copyright MIT License
*/
#include <errno.h> #include <errno.h>
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
/** /**
* fsendfile - copy data between file streams * Copy data between file streams.
* @src: Source stream * @param src Source stream
* @dst: Destination stream * @param dst Destination stream
* @len: Number of bytes to copy * @param len Number of bytes to copy
* *
* @dst may be %NULL, in which case @len bytes are read and discarded * The @p dst argument may be @c NULL, in which case @a len bytes are
* from @src. This can be useful for streams where seeking is not * read and discarded from @a src. This can be useful for streams where
* permitted. Additionally, @len may be the special value zero (0), in * seeking is not permitted. Additionally, @a len may be the special
* which case fsendfile() will copy until %EOF is seen on @src. * value zero (0), in which case fsendfile() copies until @c EOF is seen
* on @a src.
* *
* Returns: * @returns The number of bytes copied. If an error is detected -1 is
* The number of bytes copied. If an error is detected -1 is returned * returned and @a errno will be set accordingly.
* and @errno will be set accordingly.
*/ */
ssize_t fsendfile(FILE *src, FILE *dst, size_t len) ssize_t fsendfile(FILE *src, FILE *dst, size_t len)
{ {
+14 -7
View File
@@ -22,6 +22,14 @@
* THE SOFTWARE. * THE SOFTWARE.
*/ */
/**
* @file ifconfig.c
* @author Claudio Matsuoka
* @author Joachim Wiberg
* @date 2008-2021
* @copyright MIT License
*/
#include <arpa/inet.h> #include <arpa/inet.h>
#include <errno.h> #include <errno.h>
#include <net/if.h> #include <net/if.h>
@@ -34,14 +42,13 @@
extern size_t strlcpy(char *dst, const char *src, size_t siz); extern size_t strlcpy(char *dst, const char *src, size_t siz);
/** /**
* ifconfig - Basic ifconfig like operations on an interface * Basic ifconfig like operations on an interface
* @ifname: Name of interface to operate on * @param ifname Name of interface to operate on
* @addr: If @up then set this optional IPv4 address * @param addr If @p up then set this optional IPv4 address
* @mask: If @up and @addr, and @addr is not INADDR_ANY, then set netmask * @param mask If @p up and @p addr, and @p addr is not @c INADDR_ANY, then set netmask
* @up: Control %IFF_UP flag on interface * @param up Control @c IFF_UP flag on interface
* *
* Returns: * @returns POSIX OK(0) on success, or non-zero on error.
* POSIX OK(0) on success, or non-zero on error.
*/ */
int ifconfig(const char *ifname, const char *addr, const char *mask, int up) int ifconfig(const char *ifname, const char *addr, const char *mask, int up)
{ {
+38 -35
View File
@@ -15,26 +15,33 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file lfile.c
* @author Joachim Wiberg
* @date 2015-2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <stdio.h> /* FILE */ #include <stdio.h> /* FILE */
#include <stdlib.h> /* atoi() */ #include <stdlib.h> /* atoi() */
#include <string.h> /* strlen(), strncmp(), strtok_r() */ #include <string.h> /* strlen(), strncmp(), strtok_r() */
#include <sys/param.h> /* MAX() */ #include <sys/param.h> /* MAX() */
/** @private for internal use only */
typedef struct lfile { typedef struct lfile {
FILE *fp; FILE *fp; /**< FILE pointer to current stream */
char buf[256]; char buf[256]; /**< Internal buffer, limted to 256 bytes per line */
char *save; char *save; /**< Internal save pointer */
const char *sep; const char *sep; /**< Record separator, from lfopen() */
} lfile_t; } lfile_t;
/** /**
* lfopen - Open file and return parsing context * Open file and return parsing context.
* @file: File to parse * @param file File to parse
* @sep: Separator(s) to use in lftok() * @param sep Separator(s) to use in lftok()
* *
* Returns: * @returns Pointer to an @a lfile_t parser context, or @c NULL on error.
* Pointer to a &lftile_t parser context, or %NULL on error.
*/ */
lfile_t *lfopen(const char *file, const char *sep) lfile_t *lfopen(const char *file, const char *sep)
{ {
@@ -62,8 +69,8 @@ lfile_t *lfopen(const char *file, const char *sep)
} }
/** /**
* lfclose - Close a parser context * Close a parser context.
* @lf: Pointer to &lfile_t context from lfopen() * @param lf: Pointer to @a lfile_t parser context from lfopen()
*/ */
void lfclose(lfile_t *lf) void lfclose(lfile_t *lf)
{ {
@@ -76,12 +83,11 @@ void lfclose(lfile_t *lf)
} }
/** /**
* lftok - Get next token in file * Get next token in file
* @lf: Pointer to &lfile_t context from lfopen() * @param lf: Pointer to @a lfile_t parser context from lfopen()
* *
* Returns: * @returns Next token, read from file previously opened with lfopen(),
* Next token, read from file previously opened with lfopen(), * or @c NULL if EOF.
* or %NULL if EOF.
*/ */
char *lftok(lfile_t *lf) char *lftok(lfile_t *lf)
{ {
@@ -110,18 +116,17 @@ char *lftok(lfile_t *lf)
} }
/** /**
* lfgetkey - Find key in file * Find key in file
* @lf: Pointer to &lfile_t context from lfopen() * @param lf Pointer to @a lfile_t parser context from lfopen()
* @key: Key to look for * @param key Key to look for
* *
* Locate @key from the current position in the file parser context * Locate @a key from the current position in the file parser context
* returned from lfopen(). Please note, the search for @key does not * returned from lfopen(). Please note, the search for @a key does not
* start from the beginning of the file, it searches from the current * start from the beginning of the file, it searches from the current
* position. To restart search from the beginning use rewind() on the * position. To restart search from the beginning use rewind() on the
* lf->fp. * lf->fp.
* *
* Returns: * @returns The value to @a key, or @c NULL if not found.
* The value to @key, or %NULL if not found.
*/ */
char *lfgetkey(lfile_t *lf, const char *key) char *lfgetkey(lfile_t *lf, const char *key)
{ {
@@ -139,15 +144,14 @@ char *lfgetkey(lfile_t *lf, const char *key)
} }
/** /**
* lfgetint - Same as lfgetkey() but returns an integer * Same as lfgetkey() but returns an integer.
* @lf: Pointer to &lfile_t context from lfopen() * @param lf Pointer to @a lfile_t parser context from lfopen()
* @key: Key to look for * @param key Key to look for
* *
* This function is the same as lfgetkey() but returns the positive * This function is the same as lfgetkey() but returns the positive
* integer value for the matching @key, if found. * integer value for the matching @a key, if found.
* *
* Returns: * @returns The positive integer value for @a key, or -1 if not found.
* The positive integer value for @key, or -1 if not found.
*/ */
int lfgetint(lfile_t *lf, const char *key) int lfgetint(lfile_t *lf, const char *key)
{ {
@@ -160,16 +164,15 @@ int lfgetint(lfile_t *lf, const char *key)
} }
/** /**
* fgetint - Find the integer value for key in a file * Find the integer value for key in a file.
* @file: File to search for @key * @param file File to search for @a key
* @sep: Separator for tokens in @file * @param sep Separator for tokens in @a file
* @key: Key to look for in @file * @param key Key to look for in @a file
* *
* This is a convenience wrapper for lfopen(), lfgetint(), and * This is a convenience wrapper for lfopen(), lfgetint(), and
* lfclose(). * lfclose().
* *
* Returns: * @returns The positive integer value for @a key, or -1 if not found.
* The positive integer value for @key, or -1 if not found.
*/ */
int fgetint(const char *file, const char *sep, const char *key) int fgetint(const char *file, const char *sep, const char *key)
{ {
+58 -18
View File
@@ -22,6 +22,17 @@
* THE SOFTWARE. * THE SOFTWARE.
*/ */
/**
* Collection of frog DNA
* @file lite.h
* @author Claudio Matsuoka (2008-2010)
* @author Joachim Wiberg (2008-2021)
* @copyright MIT License
*
* The latest version of this manual and the libite (-lite) software
* library are available at https://github.com/troglobit/libite/
*/
#ifdef __cplusplus #ifdef __cplusplus
extern "C" extern "C"
{ {
@@ -43,21 +54,21 @@ extern "C"
/* /*
* fparseln() specific operation flags. * fparseln() specific operation flags.
*/ */
#define FPARSELN_UNESCESC 0x01 #define FPARSELN_UNESCESC 0x01 /**< Remove escape preceding an escaped comment. */
#define FPARSELN_UNESCCONT 0x02 #define FPARSELN_UNESCCONT 0x02 /**< Remove escape preceding an escaped continuation. */
#define FPARSELN_UNESCCOMM 0x04 #define FPARSELN_UNESCCOMM 0x04 /**< Remove escape preceding an escaped escape. */
#define FPARSELN_UNESCREST 0x08 #define FPARSELN_UNESCREST 0x08 /**< Remove escape preceding any other character. */
#define FPARSELN_UNESCALL 0x0f #define FPARSELN_UNESCALL 0x0f /**< All of the above. */
/* /*
* copyfile() and rsync() option flags * copyfile() and rsync() option flags
*/ */
#define LITE_FOPT_RSYNC_DELETE 0x01 #define LITE_FOPT_RSYNC_DELETE 0x01 /**< Prune files from destination that are not in source */
#define LITE_FOPT_COPYFILE_SYM 0x01 #define LITE_FOPT_COPYFILE_SYM 0x01 /**< Recreate symlink or follow to copy target */
#define LITE_FOPT_KEEP_MTIME 0x02 #define LITE_FOPT_KEEP_MTIME 0x02 /**< Preserve modification time */
typedef struct lfile lfile_t; typedef struct lfile lfile_t; /**< Opqaue context struct for lfile APIs */
typedef struct sdbuf sdbuf_t; typedef struct sdbuf sdbuf_t; /**< Opqaue context struct for telnet APIs */
char *chomp (char *str); char *chomp (char *str);
@@ -120,6 +131,12 @@ int whichp (const char *cmd);
#ifndef touch #ifndef touch
#include <sys/stat.h> /* utimensat() */ #include <sys/stat.h> /* utimensat() */
#include <sys/time.h> /* utimensat() on *BSD */ #include <sys/time.h> /* utimensat() on *BSD */
/**
* Create a file, ignoring errors for already existing files
* @param path Path to file to create.
*
* @returns POSIX OK(0), or non-zero on error.
*/
static inline int touch(const char *path) static inline int touch(const char *path)
{ {
if (utimensat(AT_FDCWD, path, NULL, 0)) { if (utimensat(AT_FDCWD, path, NULL, 0)) {
@@ -131,6 +148,12 @@ static inline int touch(const char *path)
} }
#endif #endif
#ifndef makedir #ifndef makedir
/**
* Create a directory, ignoring errors for already existing files
* @param path Path to directory to create.
*
* @returns POSIX OK(0), or non-zero on error.
*/
static inline int makedir(const char *path, mode_t mode) static inline int makedir(const char *path, mode_t mode)
{ {
if (mkdir(path, mode) && errno != EEXIST) if (mkdir(path, mode) && errno != EEXIST)
@@ -139,6 +162,12 @@ static inline int makedir(const char *path, mode_t mode)
} }
#endif #endif
#ifndef makefifo #ifndef makefifo
/**
* Create a FIFO, ignoring errors for already existing files
* @param path Path to FIFO to create.
*
* @returns POSIX OK(0), or non-zero on error.
*/
static inline int makefifo(const char *path, mode_t mode) static inline int makefifo(const char *path, mode_t mode)
{ {
if (mkfifo(path, mode) && errno != EEXIST) if (mkfifo(path, mode) && errno != EEXIST)
@@ -147,6 +176,12 @@ static inline int makefifo(const char *path, mode_t mode)
} }
#endif #endif
#ifndef erase #ifndef erase
/**
* Remove a file, ignoring errors for missing files
* @param path Path to file to remove.
*
* @returns POSIX OK(0), or non-zero on error.
*/
static inline int erase(const char *path) static inline int erase(const char *path)
{ {
if (remove(path) && errno != ENOENT) if (remove(path) && errno != ENOENT)
@@ -168,27 +203,32 @@ static inline int erase(const char *path)
/* Unline isset(), setbit() et al, these work with integers/shorts/longwords/etc. */ /* Unline isset(), setbit() et al, these work with integers/shorts/longwords/etc. */
#ifndef ISCLR #ifndef ISCLR
#define ISCLR(word,bit) ((word & (1 << (bit)) ? 0 : 1)) #define ISCLR(word,bit) ((word & (1 << (bit)) ? 0 : 1)) /**< Is bit cleared in word? */
#endif #endif
#ifndef ISSET #ifndef ISSET
#define ISSET(word,bit) ((word & (1 << (bit)) ? 1 : 0)) #define ISSET(word,bit) ((word & (1 << (bit)) ? 1 : 0)) /**< Is bit set in word? */
#endif #endif
#ifndef ISOTHER #ifndef ISOTHER
#define ISOTHER(word,bit) ((word & ~(1 << (bit)) ? 1 : 0)) /* Is any other bit set? */ #define ISOTHER(word,bit) ((word & ~(1 << (bit)) ? 1 : 0)) /**< Is any other bit set? */
#endif #endif
#ifndef SETBIT #ifndef SETBIT
#define SETBIT(word,bit) (word |= (1 << (bit))) #define SETBIT(word,bit) (word |= (1 << (bit))) /**< Set bit in word. */
#endif #endif
#ifndef CLRBIT #ifndef CLRBIT
#define CLRBIT(word,bit) (word &= ~(1 << (bit))) #define CLRBIT(word,bit) (word &= ~(1 << (bit))) /**< Clear bit in word. */
#endif #endif
/* From The Practice of Programming, by Kernighan and Pike */ /* From The Practice of Programming, by Kernighan and Pike */
#ifndef NELEMS #ifndef NELEMS
#define NELEMS(array) (sizeof(array) / sizeof(array[0])) #define NELEMS(array) (sizeof(array) / sizeof(array[0])) /**< Number of elements in array. */
#endif #endif
/* Does directory end with a slash? */ /**
* Does directory end with a slash?
* @param dir Path string to check.
*
* @returns @c TRUE(1) or @c FALSE(0)
*/
static inline int fisslashdir(const char *dir) static inline int fisslashdir(const char *dir)
{ {
if (!dir) if (!dir)
@@ -202,7 +242,7 @@ static inline int fisslashdir(const char *dir)
/* Compat */ /* Compat */
#define copy_filep(src, dst) fcopyfile(src, dst) #define copy_filep(src, dst) fcopyfile(src, dst)
#define pidfile_read_pid(file) pifile_read(file) #define pidfile_read_pid(file) pidfile_read(file)
#define signal_pidfile(file, signo) pidfile_signal(file, signo) #define signal_pidfile(file, signo) pidfile_signal(file, signo)
#endif /* LITE_H_ */ #endif /* LITE_H_ */
+28 -23
View File
@@ -15,6 +15,13 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file makepath.c
* @author Joachim Wiberg
* @date 2013-2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <libgen.h> #include <libgen.h>
#include <stdarg.h> #include <stdarg.h>
@@ -24,12 +31,11 @@
#include "lite.h" #include "lite.h"
/** /**
* mkpath - Like makepath() but takes a mode_t argument * makepath() but takes a mode_t argument.
* @dir: Directory to created, relative or absolute * @param dir Directory to created, relative or absolute
* @mode: A &mode_t mode to create @dir with * @param mode A &mode_t mode to create @a dir with
* *
* Returns: * @returns POSIX OK(0) on success, otherwise -1 with @a errno set.
* POSIX OK(0) on success, otherwise -1 with @errno set.
*/ */
int mkpath(const char *dir, mode_t mode) int mkpath(const char *dir, mode_t mode)
{ {
@@ -49,15 +55,13 @@ int mkpath(const char *dir, mode_t mode)
} }
/** /**
* fmkpath - Formatted version of mkpath() * Formatted version of mkpath().
* @mode: A &mode_t mode to create directories with * @param mode A mode_t mode to create directories with
* @fmt: Formatted string to be composed into a pathname * @param fmt Formatted string to be composed into a pathname
* *
* Note: * @note Notice the swapped arguments, compared to mkpath()!
* Notice the swapped arguments, compared to mkpath()!
* *
* Returns: * @returns POSIX OK(0) on success, otherwise -1 with @a errno set.
* POSIX OK(0) on success, otherwise -1 with @errno set.
*/ */
int fmkpath(mode_t mode, const char *fmt, ...) int fmkpath(mode_t mode, const char *fmt, ...)
{ {
@@ -83,19 +87,20 @@ int fmkpath(mode_t mode, const char *fmt, ...)
} }
/** /**
* makepath - Create all components of the specified directory. * Create all components of the specified directory.
* @dir: Directory to create. * @param dir Directory to create.
* *
* Comment: * @note It is strongly recommended to use mkpath() over this function
* It is recommended to use mkpath() over this function since it has * since it has the @a mode argument while this function default to
* the @mode argument while this function instead default ot 0777, * 0777, which in most cases is insecure.
* which in most cases is insecure.
* *
* Returns: * @returns POSIX OK (0) on success, otherwise -1 and @a errno set
* POSIX OK (0) on success, otherwise -1 and errno set appropriately. * appropriately.
* This function returns EINVAL on bad argument, or ENOMEM when it *
* fails allocating temporary memory. For other error codes see the * @exception EINVAL on bad argument, or
* mkdir() syscall description. * @exception ENOMEM when it fails allocating temporary memory.
*
* For other error codes see the mkdir(2) syscall description.
*/ */
int makepath(const char *dir) int makepath(const char *dir)
{ {
+19 -2
View File
@@ -31,6 +31,13 @@
* POSSIBILITY OF SUCH DAMAGE. * POSSIBILITY OF SUCH DAMAGE.
*/ */
/**
* @file pidfile.c
* @author NetBSD Foundation Inc.
* @date 1999
* @copyright 2-clause BSD License
*/
#include <sys/stat.h> /* utimensat() */ #include <sys/stat.h> /* utimensat() */
#include <sys/time.h> /* utimensat() on *BSD */ #include <sys/time.h> /* utimensat() on *BSD */
#include <sys/types.h> #include <sys/types.h>
@@ -50,8 +57,18 @@ const char *__pidfile_path = _PATH_VARRUN; /* Note: includes trailing slash '/'
const char *__pidfile_name = NULL; const char *__pidfile_name = NULL;
extern char *__progname; extern char *__progname;
int /**
pidfile(const char *basename) * Create or update mtime of process PID file.
* @param basename Program name, or @c NULL, may start with '/'
*
* This function is intended to be used by UNIX daemons to save the PID of the main process
* responsible for handling signals. If @p basename is @c NULL the implicit @a __progname
* variable from the C-library is used. The @p basename may also start with '/', in which
* case it is interpreted as the absolute path to the PID file.
*
* @returns POSIX OK(0) on success, otherwise non-zero on error.
*/
int pidfile(const char *basename)
{ {
int save_errno; int save_errno;
int atexit_already; int atexit_already;
+31 -22
View File
@@ -15,6 +15,13 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file pidfilefn.c
* @author Joachim Wiberg
* @date 2009-2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
@@ -24,16 +31,20 @@
extern char *chomp(char *str); extern char *chomp(char *str);
/** /**
* pidfile_read - Reads a PID value from a pidfile. * Reads a PID value from a pidfile.
* @pidfile: File containing PID, usually in /var/run/<PROC>.pid * @param pidfile File containing PID, usually in @c /var/run/PROCNAME.pid
* *
* This function takes a @pidfile and returns the PID found therein. * This function takes a @p pidfile and returns the PID found therein.
* *
* Returns: * @returns On invalid @p pidfile, -1 with @a errno set. If the @p
* On invalid @pidfile -1 and errno set to %EINVAL, when @pidfile does not exist -1 * pidfile is empty, or when its contents cannot be translated, this
* and errno set to %ENOENT. When the pidfile is empty or when its contents cannot * function returns zero (0), on success this function returns a PID
* be translated this function returns zero (0), on success this function returns * value greater than one.
* a PID value greater than one. PID 1 is reserved for the system init process. *
* @note PID 1 is reserved for the system init process.
*
* @exception EINVAL on invalid @p pidfile, or
* @exception ENOENT when @p pidfile does not exist.
*/ */
pid_t pidfile_read(const char *pidfile) pid_t pidfile_read(const char *pidfile)
{ {
@@ -66,15 +77,14 @@ pid_t pidfile_read(const char *pidfile)
} }
/** /**
* pidfile_poll - Poll for the existence of a pidfile and return PID * Poll for the existence of a pidfile and return PID.
* @pidfile: Path to pidfile to poll for * @param pidfile Path to pidfile to poll for
* *
* This function polls for the pidfile at @pidfile for at most 5 seconds * This function polls for the pidfile at @p pidfile for at most 5
* before timing out. If the file is created within that time span the * seconds before timing out. If the file is created within that time
* file is read and its PID contents returned. * span the file is read and its PID contents returned.
* *
* Returns: * @returns The PID read from @p pidfile, or zero on timeout.
* The PID read from @pidfile, or zero on timeout.
*/ */
pid_t pidfile_poll(const char *pidfile) pid_t pidfile_poll(const char *pidfile)
{ {
@@ -92,15 +102,14 @@ pid_t pidfile_poll(const char *pidfile)
} }
/** /**
* pidfile_signal - Send signal to a PID and cleanup pidfile afterwards * Send signal to a PID and cleanup pidfile afterwards.
* @pidfile: File containing PID, usually in /var/run/<PROC>.pid * @param pidfile File containing PID, usually in @c /var/run/PROCNAME.pid
* @signal: Signal to send to PID found in @pidfile. * @param signal Signal to send to PID found in @p pidfile.
* *
* If @signal is any of %SIGTERM, %SIGKILL, or if kill() returns -1 the * If @p signal is any of @c SIGTERM or @c SIGKILL, or if kill(2)
* @pidfile is removed. * returns -1, the @p pidfile is removed.
* *
* Returns: * @returns POSIX OK(0) on success, non-zero otherwise.
* POSIX OK(0) on success, non-zero otherwise.
*/ */
int pidfile_signal(const char *pidfile, int signal) int pidfile_signal(const char *pidfile, int signal)
{ {
+18 -7
View File
@@ -15,6 +15,13 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file progress.c
* @author Joachim Wiberg
* @date 2012-2021
* @copyright ISC License
*/
#include <limits.h> /* INT_MAX */ #include <limits.h> /* INT_MAX */
#include <stdio.h> #include <stdio.h>
#include <string.h> #include <string.h>
@@ -40,21 +47,21 @@ static char spinner(char *style)
} }
/** /**
* progress - Advanced ASCII progress bar with spinner * Advanced ASCII progress bar with spinner
* @percent: Start first call with this set to 0, end with 100 * @param percent Start first call with this set to 0, end with 100
* @max_width: Max width of progress bar, in total characters. * @param max_width Max width of progress bar, in total characters.
* *
* This function draws an advanced ASCII progressbar at the current * This function draws an advanced ASCII progressbar at the current
* line. It always start from the first column. * line. It always start from the first column.
* *
* The progress bar will hide the cursor if started with @percent 0 and * The progress bar will hide the cursor if started with @p percent 0
* show it again at the end, when called with @percent 100. * and show it again at the end, when called with @p percent 100.
* *
* While being called with the same percentage the spinner will spin, * While being called with the same percentage the spinner will spin,
* to show the user the process hasn't frozen. * to show the user the process hasn't frozen.
* *
* If the output TTY cannot interpret control characters, like \r, it is * If the output TTY cannot interpret control characters, like `\r`, it
* advised to instead used the progress_simple() function. * is advised to instead used the progress_simple() function.
*/ */
void progress(int percent, int max_width) void progress(int percent, int max_width)
{ {
@@ -85,6 +92,10 @@ void progress(int percent, int max_width)
} }
} }
/**
* Alternative progress bar on systems where progress() doesn't work
* @param percent Start first call with this set to 0, end with 100
*/
void progress_simple(int percent) void progress_simple(int percent)
{ {
static int last = 1; static int last = 1;
+16 -2
View File
@@ -15,6 +15,13 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file reallocarray.c
* @author Otto Moerbeek
* @date 2008
* @copyright ISC License
*/
#include <sys/types.h> #include <sys/types.h>
#include <errno.h> #include <errno.h>
#include <stdint.h> #include <stdint.h>
@@ -26,8 +33,15 @@
*/ */
#define MUL_NO_OVERFLOW ((size_t)1 << (sizeof(size_t) * 4)) #define MUL_NO_OVERFLOW ((size_t)1 << (sizeof(size_t) * 4))
void * /**
reallocarray(void *optr, size_t nmemb, size_t size) * Similar to realloc() but for an array of items, like calloc()
* @param optr Pointer to old (current) array
* @param nmemb Number of elements
* @param size Size of each element, in bytes
*
* @returns A pointer to the new array, or @c NULL on error.
*/
void *reallocarray(void *optr, size_t nmemb, size_t size)
{ {
if ((nmemb >= MUL_NO_OVERFLOW || size >= MUL_NO_OVERFLOW) && if ((nmemb >= MUL_NO_OVERFLOW || size >= MUL_NO_OVERFLOW) &&
nmemb > 0 && SIZE_MAX / nmemb < size) { nmemb > 0 && SIZE_MAX / nmemb < size) {
+24 -17
View File
@@ -15,6 +15,13 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file rsync.c
* @author Joachim Wiberg
* @date 2011-2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <fcntl.h> /* AT_* macros */ #include <fcntl.h> /* AT_* macros */
#include <stdlib.h> /* NULL, free() */ #include <stdlib.h> /* NULL, free() */
@@ -34,31 +41,31 @@ static int set_mtime(char *fn, struct stat *st);
/** /**
* rsync - Synchronize contents and optionally remove non-existing backups * Synchronize contents and optionally remove non-existing backups
* @src: Source directory * @param src Source directory
* @dst: Destination directory * @param dst Destination directory
* @opt: An option mask of %LITE_FOPT_RSYNC_DELETE, %LITE_FOPT_KEEP_MTIME * @param opt An option mask of ::LITE_FOPT_RSYNC_DELETE, ::LITE_FOPT_KEEP_MTIME
* @filter: Optional filtering function for source directory. * @param filter Optional filtering function for source directory.
* *
* This is a miniature implementation of the famous rsync for local use only. * This is a miniature implementation of the famous rsync for local use
* In fact, it is not even a true rsync since it copies all files from @src * only. In fact, it is not even a true rsync since it copies all files
* to @dst. The @delete option is useful for creating backups, when set all * from @p src to @p dst. The ::LITE_FOPT_RSYNC_DELETE @p opt flag is
* files removed from src since last backup are pruned from the destination * useful for creating backups, when set all files removed from src
* (backup) directory. * since last backup are pruned from the destination (backup) directory.
* *
* The @opt parameter to rsync() is an option mask for the most common * The @p opt parameter to rsync() is an option mask for the most common
* rsync(1) options. Previously this argument was called @delete and * rsync(1) options. Previously this argument was called @p delete and
* to maintain backwards compatibility the value 1 is reserved: * to maintain backwards compatibility the value 1 is reserved:
* *
* %LITE_FOPT_RSYNC_DELETE: Prune files from @dst that no longer exist in @src. * %LITE_FOPT_RSYNC_DELETE: Prune files from @p dst that no longer exist in @p src.
* %LITE_FOPT_KEEP_MTIME: Preserve modification time * %LITE_FOPT_KEEP_MTIME: Preserve modification time
* *
* The filter callback, @filter, if provided, is used to determine what * The filter callback, @p filter, if provided, is used to determine
* files to include from the source directory when backing up. If a * what files to include from the source directory when backing up. If
* file is to be skipped the callback should simply return zero. * a file is to be skipped the callback should simply return zero.
* *
* Returns: * Returns:
* POSIX OK(0), or non-zero with @errno set on error. * POSIX OK(0), or non-zero with @a errno set on error.
*/ */
int rsync(char *src, char *dst, int opt, int (*filter)(const char *file)) int rsync(char *src, char *dst, int opt, int (*filter)(const char *file))
{ {
+20
View File
@@ -15,12 +15,32 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file systemf.c
* @author Joachim Wiberg
* @date 2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <stdarg.h> #include <stdarg.h>
#include <stdio.h> #include <stdio.h>
#include <stdlib.h> #include <stdlib.h>
#include <sys/wait.h> #include <sys/wait.h>
/**
* Like system(), but takes a formatted string as argument.
* @param fmt printf style format list to command to run
*
* This system() wrapper greatly simplifies operations that usually
* consist of composing a command from parts into a dynamic buffer
* before calling it. The return value from system() is also parsed,
* checking for proper exit and signals.
*
* @returns If the command exits normally, the return code of the command
* is returned. Otherwise, if the command is signalled, the return code
* is -1 and @a errno is set to @c EINTR.
*/
int systemf(const char *fmt, ...) int systemf(const char *fmt, ...)
{ {
va_list ap; va_list ap;
+41 -22
View File
@@ -15,6 +15,13 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file telnet.c
* @author Joachim Wiberg
* @date 2010-2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <poll.h> #include <poll.h>
#include <unistd.h> #include <unistd.h>
@@ -33,12 +40,19 @@
# define TELL(fmt, args...) # define TELL(fmt, args...)
#endif #endif
/** @private for internal use only */
struct sdbuf { struct sdbuf {
int sd; int sd;
char *buf; char *buf;
} sdbuf; };
/* Open telnet connection to @addr:@port and connect. */ /**
* Open telnet connection to addr:port and connect.
* @param addr Integer encoded IPv4 address in network byte order
* @param port Internet port number in network byte order
*
* @returns An @ref sdbuf_t socket buffer context.
*/
sdbuf_t *telnet_open(int addr, short port) sdbuf_t *telnet_open(int addr, short port)
{ {
struct sockaddr_in *sin; struct sockaddr_in *sin;
@@ -93,6 +107,12 @@ sdbuf_t *telnet_open(int addr, short port)
return ctx; return ctx;
} }
/**
* Close a telnet session previously opened with telnet_open()
* @param ctx An @ref sdbuf_t socket buffer context
*
* @returns Always returns POSIX OK(0).
*/
int telnet_close(sdbuf_t *ctx) int telnet_close(sdbuf_t *ctx)
{ {
free(ctx->buf); free(ctx->buf);
@@ -137,20 +157,19 @@ static int wait_substr(sdbuf_t *ctx, char *str)
} }
/** /**
* telnet_expect - Poor man's telnet expect * Poor man's telnet expect
* @ctx: Telnet session context from telnet_open() * @param ctx Telnet session context from telnet_open()
* @script: %NULL terminated list of expect and response strings * @param script @c NULL terminated list of expect and response strings
* @output: Optional output from session * @param output Optional output from session
* *
* Issues @script sequence on telnet session specified in @ctx, with * Issues @p script sequence on telnet session specified in @p ctx, with
* optional @output from session. * optional @p output from session.
* *
* The @script consists of strings of expect and response pairs. For * The @p script consists of strings of expect and response pairs. For
* example, expect "ogin: " followed by response "root\n", expect * example, expect "ogin: " followed by response "root\n", expect
* "assword: "with response "secret\n", concluded by %NULL. * "assword: "with response "secret\n", concluded by @c NULL.
* *
* Returns: * @returns POSIX OK(0) or non-zero on error.
* POSIX OK(0) or non-zero on error.
*/ */
int telnet_expect(sdbuf_t *ctx, char *script[], FILE *output) int telnet_expect(sdbuf_t *ctx, char *script[], FILE *output)
{ {
@@ -258,20 +277,20 @@ int telnet_expect(sdbuf_t *ctx, char *script[], FILE *output)
} }
/** /**
* telnet_session - Very simple expect-like implementation for telnet. * Very simple expect-like implementation for telnet.
* @addr: Must be in network byte order, use htonl(). * @param addr Integer encoded IPv4 address, in network byte order, use htonl().
* @port: IP port to connect to, use htons(). * @param port Internet port to connect to, in network byte order, use htons().
* @script: Expect like script of paired 'expect', 'response' strings. * @param script Expect like script of paired 'expect', 'response' strings.
* @output: A &FILE pointer to a tmpfile() for output from the last command. * @param output A FILE pointer to a tempfile() for output from the last command.
* *
* This is a very simple expect-like implementation for querying and * This is a very simple expect-like implementation for querying and
* operating daemons remotely over telnet. * operating daemons remotely over telnet.
* *
* The @script is a query-response type of list of strings leading up to * The @p script is a query-response type of list of strings leading up
* a final command, which output is then written to the given @output file. * to a final command, which output is then written to the given @p
* output file.
* *
* Returns: * @returns POSIX OK(0), or non-zero with @a errno set on error.
* POSIX OK(0), or non-zero with errno set on error.
*/ */
int telnet_session(int addr, short port, char *script[], FILE *output) int telnet_session(int addr, short port, char *script[], FILE *output)
{ {
+16 -7
View File
@@ -15,6 +15,13 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file tempfile.c
* @author Joachim Wiberg
* @date 2015-2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <paths.h> #include <paths.h>
#include <fcntl.h> /* O_TMPFILE requires -D_GNU_SOURCE */ #include <fcntl.h> /* O_TMPFILE requires -D_GNU_SOURCE */
@@ -22,17 +29,19 @@
#include <sys/stat.h> /* umask() */ #include <sys/stat.h> /* umask() */
/** /**
* tempfile - A secure tmpfile() replacement * A secure tmpfile() replacement
* *
* This is the secure replacement for tmpfile() that does not exist in * This is the secure replacement for tmpfile() that does not exist in
* GLIBC. The function uses the Linux specific %O_TMPFILE and %O_EXCL * GLIBC. It uses the Linux specific @c O_TMPFILE and @c O_EXCL to hide
* for security. When the %FILE is fclose()'ed the file contents is * the filename. When the @c FILE is fclose()'ed, the file contents is
* lost. The file is hidden in the %_PATH_TMP directory on the system. * lost. The file is hidden in the @c _PATH_TMP ("/tmp") directory in
* the system.
* *
* This function requires Linux 3.11, or later, due to %O_TMPFILE. * This function requires Linux 3.11, or later, due to @c O_TMPFILE.
* Not all file systems support hidden inodes, in which case this
* function defaults to call tmpfile() as a fallback.
* *
* Returns: * @returns An open @c FILE pointer, or @c NULL on error.
* An open %FILE pointer, or %NULL on error.
*/ */
FILE *tempfile(void) FILE *tempfile(void)
{ {
+11 -5
View File
@@ -15,6 +15,13 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file touchf.c
* @author Joachim Wiberg
* @date 2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <stdio.h> #include <stdio.h>
#include <stdarg.h> #include <stdarg.h>
@@ -24,16 +31,15 @@
#include "lite.h" #include "lite.h"
/** /**
* touchf - Like touch() but with formatted string support * Like touch() but with formatted string support
* @fmt: Formatted string to be composed into a pathname * @param fmt Formatted string to be composed into a pathname
* *
* This is a wrapper for the touch() function in lite.h, lessening the * This is a wrapper for the touch() function in lite.h, lessening the
* burden of having to compose the filename from parts in a seprate * burden of having to compose the filename from parts in a seprate
* buffer. * buffer.
* *
* Returns: * @returns Upon successful completion touchf() returns POSIX OK(0),
* Upon successful completion touchf() returns POSIX OK(0), otherwise, * otherwise, -1 is returned and @a errno is set to indicate error.
* -1 is returned and errno is set to indicate the error.
*/ */
int touchf(const char *fmt, ...) int touchf(const char *fmt, ...)
{ {
+12 -6
View File
@@ -15,6 +15,13 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file truncatef.c
* @author Joachim Wiberg
* @date 2021
* @copyright ISC License
*/
#include <errno.h> #include <errno.h>
#include <stdio.h> #include <stdio.h>
#include <stdarg.h> #include <stdarg.h>
@@ -22,16 +29,15 @@
#include <unistd.h> #include <unistd.h>
/** /**
* truncatef - Truncate a file based on the formatted string * Truncate a file based on the formatted string
* @length: Size in bytes to truncate file to, zero to empty it * @param length Size in bytes to truncate file to, zero to empty it
* @fmt: Formatted string to be composed into a pathname * @param fmt Formatted string to be composed into a pathname
* *
* This is an extension to the truncate() family, lessening the burden * This is an extension to the truncate() family, lessening the burden
* of having to compose the filename from parts in a seprate buffer. * of having to compose the filename from parts in a seprate buffer.
* *
* Returns: * @returns Upon successful completion truncate() returns POSIX OK(0),
* Upon successful completion truncate() returns POSIX OK(0), otherwise, * otherwise, -1 is returned and @a errno is set to indicate error.
* -1 is returned and errno is set to indicate the error.
*/ */
int truncatef(off_t length, const char *fmt, ...) int truncatef(off_t length, const char *fmt, ...)
{ {
+17 -4
View File
@@ -15,6 +15,13 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file which.c
* @author Joachim Wiberg
* @date 2017-2021
* @copyright ISC License
*/
#include <ctype.h> #include <ctype.h>
#include <errno.h> #include <errno.h>
#include <stdio.h> /* snprintf() */ #include <stdio.h> /* snprintf() */
@@ -38,8 +45,11 @@ static char *strip_args(char *path)
return path; return path;
} }
/* /**
* Like which(1), returns a malloc'ed path to cmd on success, or NULL * Like which(1), or `command -v foo`
* @param cmd Command to look for in $PATH
*
* @returns A malloc()'ed path to @a cmd on success, or @c NULL.
*/ */
char *which(const char *cmd) char *which(const char *cmd)
{ {
@@ -103,8 +113,11 @@ char *which(const char *cmd)
return NULL; return NULL;
} }
/* /**
* Like which(), above, but only answers TRUE(1)/FALSE(0) * Predicate variant of which()
* @param cmd Command to look for in $PATH
*
* @returns @c TRUE(1) or @c FALSE(0) if @p cmd exists in $PATH.
*/ */
int whichp(const char *cmd) int whichp(const char *cmd)
{ {
+10 -4
View File
@@ -15,6 +15,13 @@
* OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/ */
/**
* @file yorn.c
* @author Joachim Wiberg
* @date 2009-2021
* @copyright ISC License
*/
#include <stdio.h> #include <stdio.h>
#include <stdio_ext.h> /* __fpurge() */ #include <stdio_ext.h> /* __fpurge() */
#include <stdarg.h> #include <stdarg.h>
@@ -56,14 +63,13 @@ static char rawgetch(void)
} }
/** /**
* yorn - Pose a a Yes or No question and return answer * Pose a a Yes or No question and return answer
* @fmt: Standard printf() style argument(s). * @param fmt Standard printf() style argument(s).
* *
* This function prints the given question on screen, waits for user * This function prints the given question on screen, waits for user
* input in the form of yes or no. * input in the form of yes or no.
* *
* Returns: * @returns TRUE(1) or FALSE(0). True if the answer is yes.
* True(1) or False(0). True if the answer is yes.
*/ */
int yorn(const char *fmt, ...) int yorn(const char *fmt, ...)
{ {