wt/libite
1
0
Fork 0
mirror of https://github.com/troglobit/libite.git synced 2026-09-30 21:12:37 +07:00
Code Issues Packages Projects Releases Wiki Activity

doc: initial effort to enable doxygen

Browse Source 
Framework from libuEv.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
This commit is contained in:
Joachim Wiberg
2021-10-03 19:08:40 +02:00
parent 03598fc01e
commit 6537b11e34
33 changed files with 3781 additions and 275 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Makefile.am
+13
View File
@@ -3,6 +3,19 @@ SUBDIRS = src test
doc_DATA = 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
release-hook:
@if [ ! `git tag -l v$(PACKAGE_VERSION) | grep $(PACKAGE_VERSION)` ]; then \
configure.ac
+18 -1
View File
@@ -5,7 +5,7 @@ AM_SILENT_RULES([yes])
AC_CONFIG_SRCDIR(src/lite.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_PROG_CC
@@ -13,4 +13,21 @@ AC_PROG_INSTALL
m4_ifdef([AM_PROG_AR], [AM_PROG_AR])
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
doc/.gitignore
+3
View File
@@ -0,0 +1,3 @@
html/*
libite.tag
Doxyfile
doc/Doxyfile.in
+2579
View File
File diff suppressed because it is too large Load Diff
doc/Makefile.am
+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
m4/ax_prog_doxygen.m4
+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
])
src/chomp.c
+11 -5
View File
@@ -15,19 +15,25 @@
* 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 <string.h>
/**
* chomp - Perl like chomp function, chop off last char(s) if newline.
* @str: String to chomp
* Perl like chomp function, chop off last char(s) if newline.
* @param str String to chomp
*
* This function is like Perl chomp, but it's set to chop of all
* trailing newlines. Useful in combination with fgets().
*
* Returns:
* If @str is a valid pointer this function returns @str, otherwise
* @errno is set to %EINVAL and this function returns %NULL.
* @returns @a str, or @c NULL with @a errno set, if @a str is not a valid pointer.
* @exception EINVAL if the input argument is not a valid pointer.
*/
char *chomp(char *str)
{
src/conio.c
+21
View File
@@ -15,11 +15,32 @@
* 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 <stdio.h>
#include <termios.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)
{
if (!row || !col)
src/copyfile.c
+34 -30
View File
@@ -21,6 +21,13 @@
* THE SOFTWARE.
*/
/**
* @file copyfile.c
* @author Claudio Matsuoka
* @date 2008
* @copyright MIT License
*/
#include <errno.h>
#include <fcntl.h>
#include <stdlib.h>
@@ -94,28 +101,30 @@ static void set_mtime(int in, int out)
}
/**
* copyfile - Copy a file to another.
* @src: Full path name to source file.
* @dst: Full path name to target file.
* @len: Number of bytes to copy, zero (0) for entire file.
* @opt: An option mask of %LITE_FOPT_COPYFILE_SYM, %LITE_FOPT_KEEP_MTIME
* Copy a file to another.
* @param src Full path name to source file.
* @param dst Full path name to target file.
* @param len Number of bytes to copy, zero (0) for entire file.
* @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
* 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
* of fastinit for the Asus EeePC.
*
* The @opt field replaces the @sym argument in previous releases and
* works as follows. To maintain backwards compatibility with @sym
* the %LITE_FOPT_COPYFILE_SYM maintains a value of 1:
* The @a opt field replaces the @a sym argument in previous releases
* and works as follows. To maintain backwards compatibility with @a
* 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_KEEP_MTIME: Preserve modification time
* - ::LITE_FOPT_COPYFILE_SYM Recreate symlink or follow to copy target
* - ::LITE_FOPT_KEEP_MTIME Preserve modification time
*
* Returns:
* The number of bytes copied, zero may be error (check errno!), but it
* may also indicate that @src was empty. If @src is a directory @errno
* will be set to %EISDIR since copyfile() is not recursive.
* @returns The number of bytes copied, or zero, which may be an error
* (check @a errno, see Exceptions below), but it may also indicate that
* @a src was empty. See exceptions, below.
*
* @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)
{
@@ -203,20 +212,19 @@ exit:
}
/**
* movefile - Move a file to another location
* @src: Source file.
* @dst: Target file, or location.
* Move a file to another location
* @param src Source file.
* @param dst Target file, or location.
*
* This is a C implementation of the command line mv(1) utility.
* Usually the rename() API is sufficient, but not when moving across
* file system boundaries.
*
* The @src argument must include the full path to the source file,
* whereas the @dst argument may only be a directory, in which case the
* same file name from @src is used.
* The @p src argument must include the full path to the source file,
* whereas the @p dst argument may only be a directory, in which case
* the same file name from @p src is used.
*
* Returns:
* POSIX OK(0), or non-zero with errno set.
* @returns POSIX OK(0), or non-zero with @a errno set.
*/
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.
* @src: Source FILE.
* @dst: Destination FILE.
* Copy between FILE *fp.
* @param src Source FILE.
* @param dst Destination FILE.
*
* Function takes signals into account and will restart the syscalls as
* long as error is %EINTR.
*
* Returns:
* POSIX OK(0), or non-zero with errno set on error.
* @returns POSIX OK(0), or non-zero with @a errno set on error.
*/
int fcopyfile(FILE *src, FILE *dst)
{
src/dir.c
+24 -20
View File
@@ -15,6 +15,13 @@
* 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 <dirent.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.
* @dir: Base directory for dir operation.
* @type: File type suffix, e.g. ".cfg".
* @filter: Optional file name filter.
* @list: Pointer to an array of file names.
* @strip: Flag, if set dir() strips the file type.
* List all files of a certain type in the given directory.
* @param dir Base directory for dir operation.
* @param type File type suffix, e.g. ".cfg".
* @param filter Optional file name filter.
* @param list Pointer to an array of file names.
* @param strip Flag, if set dir() strips the file type.
*
* This function returns a @list of files, matching the @type suffix,
* in the given directory @dir.
* This function returns a @a list of files, matching the @a type
* 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
* 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
* @filter returns non-zero the @file argument will be included in the
* resulting @list. If @filter returns zero for given @file it will
* be discarded.
* If @a filter is not @c NULL it will be called for each file found.
* If @a filter returns non-zero the @a file argument is included in the
* resulting @a list. If @a filter returns zero for given @a file it is
* 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
* file type stripped, including the dot. So a match "config0.cfg"
* 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.
* @returns The number of files in @a list, zero if no matching files of
* @a type, or non-zero on error with @a errno set.
*/
int dir(const char *dir, const char *type, int (*filter) (const char *file), char ***list, int strip)
{
src/erasef.c
+11 -5
View File
@@ -15,6 +15,13 @@
* 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 <stdio.h>
#include <stdarg.h>
@@ -24,16 +31,15 @@
#include "lite.h"
/**
* erasef - Like erase() but with formatted string support
* @fmt: Formatted string to be composed into a pathname
* Like erase() but with formatted string support.
* @param fmt Formatted string to be composed into a pathname
*
* 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
* buffer.
*
* Returns:
* Upon successful completion erasef() returns POSIX OK(0), otherwise,
* -1 is returned and errno is set to indicate the error.
* @returns Upon successful completion erasef() returns POSIX OK(0),
* otherwise, -1 is returned and @a errno is set to indicate the error.
*/
int erasef(const char *fmt, ...)
{
src/fexist.c
+10 -4
View File
@@ -21,15 +21,21 @@
* THE SOFTWARE.
*/
/**
* @file fexist.c
* @author Claudio Matsuoka
* @date 2008
* @copyright MIT License
*/
#include <errno.h>
#include <unistd.h>
/**
* fexist - Check if a file exists in the file system.
* @file: File to look for, with full path.
* Check if a file exists in the file system.
* @param file File to look for, with full path.
*
* Returns:
* %TRUE(1) if the file exists, otherwise %FALSE(0).
* @returns @c TRUE(1) if the @a file exists, otherwise @c FALSE(0).
*/
int fexist(const char *file)
{
src/fisdir.c
+10 -4
View File
@@ -21,15 +21,21 @@
* THE SOFTWARE.
*/
/**
* @file fisdir.c
* @author Claudio Matsuoka
* @date 2008
* @copyright MIT License
*/
#include <sys/stat.h>
#include <unistd.h>
/**
* fisdir - Check if a path exists and is a directory.
* @path: Path to file or directory
* Check if a path exists and is a directory.
* @param path Path to file or directory
*
* Returns:
* %TRUE(1) if @path exists and is a directory, otherwise %FALSE(0).
* @returns @c TRUE(1) if @p path exists and is a directory, otherwise @c FALSE(0).
*/
int fisdir(const char *path)
{
src/fopenf.c
+13 -6
View File
@@ -15,22 +15,29 @@
* 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 <stdio.h>
#include <stdarg.h>
#include <stdlib.h>
/**
* fopenf - Open a file based on the formatted string and optional arguments
* @mode: Last argument in optional list, if omitted EINVAL
* @fmt: Formatted string to be composed into a pathname
* Open a file based on the formatted string and optional arguments
* @param mode An fopen() mode string, e.g. "w+"
* @param fmt Formatted string to be composed into a pathname
*
* 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.
*
* Returns:
* Upon successful completion fopenf() a FILE pointer. Otherwise, NULL
* is returned and errno is set to indicate the error.
* @returns Upon successful completion, fopenf() returns a FILE pointer.
* Otherwise, @c NULL is returned and @a errno is set to indicate the
* error.
*/
FILE *fopenf(const char *mode, const char *fmt, ...)
{
src/fparseln.c
+26 -4
View File
@@ -24,6 +24,13 @@
* 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 <errno.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 \
* and eliminating trailing newlines, or comments starting with
* the comment char.
/**
* Read a line from a file parsing continuations and trailing newlines
* @param fp FILE pointer to read from
* @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 *
fparseln(FILE *fp, size_t *size, size_t *lineno, const char str[3], int flags)
src/fremove.c
+11 -4
View File
@@ -15,20 +15,27 @@
* 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 <stdio.h>
#include <stdarg.h>
#include <stdlib.h>
/**
* fremove - Remove a file based on the formatted string and optional arguments
* @fmt: Formatted string to be composed into a pathname
* Remove a file based on the formatted string and optional arguments
* @param fmt Formatted string to be composed into a pathname
*
* This function is an extension to remove(), lessening the burden of
* first having to compose the filename from parts in a seprate buffer.
*
* Returns:
* Return value for remove(3).
* @returns same as remove(3), with an extra @a errno, @c ENOBUFS if
* alloca() fails to get a temporary buffer for composing the file name.
*/
int fremove(const char *fmt, ...)
{
src/fsendfile.c
+18 -11
View File
@@ -21,25 +21,32 @@
* THE SOFTWARE.
*/
/**
* @file fsendfile.c
* @author Tobias Waldekranz
* @date 2013
* @copyright MIT License
*/
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
/**
* fsendfile - copy data between file streams
* @src: Source stream
* @dst: Destination stream
* @len: Number of bytes to copy
* Copy data between file streams.
* @param src Source stream
* @param dst Destination stream
* @param len Number of bytes to copy
*
* @dst may be %NULL, in which case @len bytes are read and discarded
* from @src. This can be useful for streams where seeking is not
* permitted. Additionally, @len may be the special value zero (0), in
* which case fsendfile() will copy until %EOF is seen on @src.
* The @p dst argument may be @c NULL, in which case @a len bytes are
* read and discarded from @a src. This can be useful for streams where
* seeking is not permitted. Additionally, @a len may be the special
* value zero (0), in which case fsendfile() copies until @c EOF is seen
* on @a src.
*
* Returns:
* The number of bytes copied. If an error is detected -1 is returned
* and @errno will be set accordingly.
* @returns The number of bytes copied. If an error is detected -1 is
* returned and @a errno will be set accordingly.
*/
ssize_t fsendfile(FILE *src, FILE *dst, size_t len)
{
src/ifconfig.c
+14 -7
View File
@@ -22,6 +22,14 @@
* THE SOFTWARE.
*/
/**
* @file ifconfig.c
* @author Claudio Matsuoka
* @author Joachim Wiberg
* @date 2008-2021
* @copyright MIT License
*/
#include <arpa/inet.h>
#include <errno.h>
#include <net/if.h>
@@ -34,14 +42,13 @@
extern size_t strlcpy(char *dst, const char *src, size_t siz);
/**
* ifconfig - Basic ifconfig like operations on an interface
* @ifname: Name of interface to operate on
* @addr: If @up then set this optional IPv4 address
* @mask: If @up and @addr, and @addr is not INADDR_ANY, then set netmask
* @up: Control %IFF_UP flag on interface
* Basic ifconfig like operations on an interface
* @param ifname Name of interface to operate on
* @param addr If @p up then set this optional IPv4 address
* @param mask If @p up and @p addr, and @p addr is not @c INADDR_ANY, then set netmask
* @param up Control @c IFF_UP flag on interface
*
* Returns:
* POSIX OK(0) on success, or non-zero on error.
* @returns POSIX OK(0) on success, or non-zero on error.
*/
int ifconfig(const char *ifname, const char *addr, const char *mask, int up)
{
src/lfile.c
+38 -35
View File
@@ -15,26 +15,33 @@
* 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 <stdio.h> /* FILE */
#include <stdlib.h> /* atoi() */
#include <string.h> /* strlen(), strncmp(), strtok_r() */
#include <sys/param.h> /* MAX() */
/** @private for internal use only */
typedef struct lfile {
FILE *fp;
char buf[256];
char *save;
const char *sep;
FILE *fp; /**< FILE pointer to current stream */
char buf[256]; /**< Internal buffer, limted to 256 bytes per line */
char *save; /**< Internal save pointer */
const char *sep; /**< Record separator, from lfopen() */
} lfile_t;
/**
* lfopen - Open file and return parsing context
* @file: File to parse
* @sep: Separator(s) to use in lftok()
* Open file and return parsing context.
* @param file File to parse
* @param sep Separator(s) to use in lftok()
*
* Returns:
* Pointer to a &lftile_t parser context, or %NULL on error.
* @returns Pointer to an @a lfile_t parser context, or @c NULL on error.
*/
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
* @lf: Pointer to &lfile_t context from lfopen()
* Close a parser context.
* @param lf: Pointer to @a lfile_t parser context from lfopen()
*/
void lfclose(lfile_t *lf)
{
@@ -76,12 +83,11 @@ void lfclose(lfile_t *lf)
}
/**
* lftok - Get next token in file
* @lf: Pointer to &lfile_t context from lfopen()
* Get next token in file
* @param lf: Pointer to @a lfile_t parser context from lfopen()
*
* Returns:
* Next token, read from file previously opened with lfopen(),
* or %NULL if EOF.
* @returns Next token, read from file previously opened with lfopen(),
* or @c NULL if EOF.
*/
char *lftok(lfile_t *lf)
{
@@ -110,18 +116,17 @@ char *lftok(lfile_t *lf)
}
/**
* lfgetkey - Find key in file
* @lf: Pointer to &lfile_t context from lfopen()
* @key: Key to look for
* Find key in file
* @param lf Pointer to @a lfile_t parser context from lfopen()
* @param key Key to look for
*
* Locate @key from the current position in the file parser context
* returned from lfopen(). Please note, the search for @key does not
* Locate @a key from the current position in the file parser context
* returned from lfopen(). Please note, the search for @a key does not
* start from the beginning of the file, it searches from the current
* position. To restart search from the beginning use rewind() on the
* lf->fp.
*
* Returns:
* The value to @key, or %NULL if not found.
* @returns The value to @a key, or @c NULL if not found.
*/
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
* @lf: Pointer to &lfile_t context from lfopen()
* @key: Key to look for
* Same as lfgetkey() but returns an integer.
* @param lf Pointer to @a lfile_t parser context from lfopen()
* @param key Key to look for
*
* 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:
* The positive integer value for @key, or -1 if not found.
* @returns The positive integer value for @a key, or -1 if not found.
*/
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
* @file: File to search for @key
* @sep: Separator for tokens in @file
* @key: Key to look for in @file
* Find the integer value for key in a file.
* @param file File to search for @a key
* @param sep Separator for tokens in @a file
* @param key Key to look for in @a file
*
* This is a convenience wrapper for lfopen(), lfgetint(), and
* lfclose().
*
* Returns:
* The positive integer value for @key, or -1 if not found.
* @returns The positive integer value for @a key, or -1 if not found.
*/
int fgetint(const char *file, const char *sep, const char *key)
{
src/lite.h
+58 -18
View File
@@ -22,6 +22,17 @@
* 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
extern "C"
{
@@ -43,21 +54,21 @@ extern "C"
/*
* fparseln() specific operation flags.
*/
#define FPARSELN_UNESCESC 0x01
#define FPARSELN_UNESCCONT 0x02
#define FPARSELN_UNESCCOMM 0x04
#define FPARSELN_UNESCREST 0x08
#define FPARSELN_UNESCALL 0x0f
#define FPARSELN_UNESCESC 0x01 /**< Remove escape preceding an escaped comment. */
#define FPARSELN_UNESCCONT 0x02 /**< Remove escape preceding an escaped continuation. */
#define FPARSELN_UNESCCOMM 0x04 /**< Remove escape preceding an escaped escape. */
#define FPARSELN_UNESCREST 0x08 /**< Remove escape preceding any other character. */
#define FPARSELN_UNESCALL 0x0f /**< All of the above. */
/*
* copyfile() and rsync() option flags
*/
#define LITE_FOPT_RSYNC_DELETE 0x01
#define LITE_FOPT_COPYFILE_SYM 0x01
#define LITE_FOPT_KEEP_MTIME 0x02
#define LITE_FOPT_RSYNC_DELETE 0x01 /**< Prune files from destination that are not in source */
#define LITE_FOPT_COPYFILE_SYM 0x01 /**< Recreate symlink or follow to copy target */
#define LITE_FOPT_KEEP_MTIME 0x02 /**< Preserve modification time */
typedef struct lfile lfile_t;
typedef struct sdbuf sdbuf_t;
typedef struct lfile lfile_t; /**< Opqaue context struct for lfile APIs */
typedef struct sdbuf sdbuf_t; /**< Opqaue context struct for telnet APIs */
char *chomp (char *str);
@@ -120,6 +131,12 @@ int whichp (const char *cmd);
#ifndef touch
#include <sys/stat.h> /* utimensat() */
#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)
{
if (utimensat(AT_FDCWD, path, NULL, 0)) {
@@ -131,6 +148,12 @@ static inline int touch(const char *path)
}
#endif
#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)
{
if (mkdir(path, mode) && errno != EEXIST)
@@ -139,6 +162,12 @@ static inline int makedir(const char *path, mode_t mode)
}
#endif
#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)
{
if (mkfifo(path, mode) && errno != EEXIST)
@@ -147,6 +176,12 @@ static inline int makefifo(const char *path, mode_t mode)
}
#endif
#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)
{
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. */
#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
#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
#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
#ifndef SETBIT
#define SETBIT(word,bit) (word |= (1 << (bit)))
#define SETBIT(word,bit) (word |= (1 << (bit))) /**< Set bit in word. */
#endif
#ifndef CLRBIT
#define CLRBIT(word,bit) (word &= ~(1 << (bit)))
#define CLRBIT(word,bit) (word &= ~(1 << (bit))) /**< Clear bit in word. */
#endif
/* From The Practice of Programming, by Kernighan and Pike */
#ifndef NELEMS
#define NELEMS(array) (sizeof(array) / sizeof(array[0]))
#define NELEMS(array) (sizeof(array) / sizeof(array[0])) /**< Number of elements in array. */
#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)
{
if (!dir)
@@ -202,7 +242,7 @@ static inline int fisslashdir(const char *dir)
/* Compat */
#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)
#endif /* LITE_H_ */
src/makepath.c
+28 -23
View File
@@ -15,6 +15,13 @@
* 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 <libgen.h>
#include <stdarg.h>
@@ -24,12 +31,11 @@
#include "lite.h"
/**
* mkpath - Like makepath() but takes a mode_t argument
* @dir: Directory to created, relative or absolute
* @mode: A &mode_t mode to create @dir with
* makepath() but takes a mode_t argument.
* @param dir Directory to created, relative or absolute
* @param mode A &mode_t mode to create @a dir with
*
* Returns:
* POSIX OK(0) on success, otherwise -1 with @errno set.
* @returns POSIX OK(0) on success, otherwise -1 with @a errno set.
*/
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()
* @mode: A &mode_t mode to create directories with
* @fmt: Formatted string to be composed into a pathname
* Formatted version of mkpath().
* @param mode A mode_t mode to create directories with
* @param fmt Formatted string to be composed into a pathname
*
* Note:
* Notice the swapped arguments, compared to mkpath()!
* @note Notice the swapped arguments, compared to mkpath()!
*
* Returns:
* POSIX OK(0) on success, otherwise -1 with @errno set.
* @returns POSIX OK(0) on success, otherwise -1 with @a errno set.
*/
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.
* @dir: Directory to create.
* Create all components of the specified directory.
* @param dir Directory to create.
*
* Comment:
* It is recommended to use mkpath() over this function since it has
* the @mode argument while this function instead default ot 0777,
* which in most cases is insecure.
* @note It is strongly recommended to use mkpath() over this function
* since it has the @a mode argument while this function default to
* 0777, which in most cases is insecure.
*
* Returns:
* POSIX OK (0) on success, otherwise -1 and errno set appropriately.
* This function returns EINVAL on bad argument, or ENOMEM when it
* fails allocating temporary memory. For other error codes see the
* mkdir() syscall description.
* @returns POSIX OK (0) on success, otherwise -1 and @a errno set
* appropriately.
*
* @exception EINVAL on bad argument, or
* @exception ENOMEM when it fails allocating temporary memory.
*
* For other error codes see the mkdir(2) syscall description.
*/
int makepath(const char *dir)
{
src/pidfile.c
+19 -2
View File
@@ -31,6 +31,13 @@
* 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/time.h> /* utimensat() on *BSD */
#include <sys/types.h>
@@ -50,8 +57,18 @@ const char *__pidfile_path = _PATH_VARRUN; /* Note: includes trailing slash '/'
const char *__pidfile_name = NULL;
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 atexit_already;
src/pidfilefn.c
+31 -22
View File
@@ -15,6 +15,13 @@
* 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 <stdio.h>
#include <stdlib.h>
@@ -24,16 +31,20 @@
extern char *chomp(char *str);
/**
* pidfile_read - Reads a PID value from a pidfile.
* @pidfile: File containing PID, usually in /var/run/<PROC>.pid
* Reads a PID value from a pidfile.
* @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:
* On invalid @pidfile -1 and errno set to %EINVAL, when @pidfile does not exist -1
* and errno set to %ENOENT. When the pidfile is empty or when its contents cannot
* be translated this function returns zero (0), on success this function returns
* a PID value greater than one. PID 1 is reserved for the system init process.
* @returns On invalid @p pidfile, -1 with @a errno set. If the @p
* pidfile is empty, or when its contents cannot be translated, this
* function returns zero (0), on success this function returns a PID
* value greater than one.
*
* @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)
{
@@ -66,15 +77,14 @@ pid_t pidfile_read(const char *pidfile)
}
/**
* pidfile_poll - Poll for the existence of a pidfile and return PID
* @pidfile: Path to pidfile to poll for
* Poll for the existence of a pidfile and return PID.
* @param pidfile Path to pidfile to poll for
*
* This function polls for the pidfile at @pidfile for at most 5 seconds
* before timing out. If the file is created within that time span the
* file is read and its PID contents returned.
* This function polls for the pidfile at @p pidfile for at most 5
* seconds before timing out. If the file is created within that time
* span the file is read and its PID contents returned.
*
* Returns:
* The PID read from @pidfile, or zero on timeout.
* @returns The PID read from @p pidfile, or zero on timeout.
*/
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
* @pidfile: File containing PID, usually in /var/run/<PROC>.pid
* @signal: Signal to send to PID found in @pidfile.
* Send signal to a PID and cleanup pidfile afterwards.
* @param pidfile File containing PID, usually in @c /var/run/PROCNAME.pid
* @param signal Signal to send to PID found in @p pidfile.
*
* If @signal is any of %SIGTERM, %SIGKILL, or if kill() returns -1 the
* @pidfile is removed.
* If @p signal is any of @c SIGTERM or @c SIGKILL, or if kill(2)
* returns -1, the @p pidfile is removed.
*
* Returns:
* POSIX OK(0) on success, non-zero otherwise.
* @returns POSIX OK(0) on success, non-zero otherwise.
*/
int pidfile_signal(const char *pidfile, int signal)
{
src/progress.c
+18 -7
View File
@@ -15,6 +15,13 @@
* 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 <stdio.h>
#include <string.h>
@@ -40,21 +47,21 @@ static char spinner(char *style)
}
/**
* progress - Advanced ASCII progress bar with spinner
* @percent: Start first call with this set to 0, end with 100
* @max_width: Max width of progress bar, in total characters.
* Advanced ASCII progress bar with spinner
* @param percent Start first call with this set to 0, end with 100
* @param max_width Max width of progress bar, in total characters.
*
* This function draws an advanced ASCII progressbar at the current
* line. It always start from the first column.
*
* The progress bar will hide the cursor if started with @percent 0 and
* show it again at the end, when called with @percent 100.
* The progress bar will hide the cursor if started with @p percent 0
* and show it again at the end, when called with @p percent 100.
*
* While being called with the same percentage the spinner will spin,
* to show the user the process hasn't frozen.
*
* If the output TTY cannot interpret control characters, like \r, it is
* advised to instead used the progress_simple() function.
* If the output TTY cannot interpret control characters, like `\r`, it
* is advised to instead used the progress_simple() function.
*/
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)
{
static int last = 1;
src/reallocarray.c
+16 -2
View File
@@ -15,6 +15,13 @@
* 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 <errno.h>
#include <stdint.h>
@@ -26,8 +33,15 @@
*/
#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) &&
nmemb > 0 && SIZE_MAX / nmemb < size) {
src/rsync.c
+24 -17
View File
@@ -15,6 +15,13 @@
* 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 <fcntl.h> /* AT_* macros */
#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
* @src: Source directory
* @dst: Destination directory
* @opt: An option mask of %LITE_FOPT_RSYNC_DELETE, %LITE_FOPT_KEEP_MTIME
* @filter: Optional filtering function for source directory.
* Synchronize contents and optionally remove non-existing backups
* @param src Source directory
* @param dst Destination directory
* @param opt An option mask of ::LITE_FOPT_RSYNC_DELETE, ::LITE_FOPT_KEEP_MTIME
* @param filter Optional filtering function for source directory.
*
* This is a miniature implementation of the famous rsync for local use only.
* In fact, it is not even a true rsync since it copies all files from @src
* to @dst. The @delete option is useful for creating backups, when set all
* files removed from src since last backup are pruned from the destination
* (backup) directory.
* This is a miniature implementation of the famous rsync for local use
* only. In fact, it is not even a true rsync since it copies all files
* from @p src to @p dst. The ::LITE_FOPT_RSYNC_DELETE @p opt flag is
* useful for creating backups, when set all files removed from src
* since last backup are pruned from the destination (backup) directory.
*
* The @opt parameter to rsync() is an option mask for the most common
* rsync(1) options. Previously this argument was called @delete and
* The @p opt parameter to rsync() is an option mask for the most common
* rsync(1) options. Previously this argument was called @p delete and
* 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
*
* The filter callback, @filter, if provided, is used to determine what
* files to include from the source directory when backing up. If a
* file is to be skipped the callback should simply return zero.
* The filter callback, @p filter, if provided, is used to determine
* what files to include from the source directory when backing up. If
* a file is to be skipped the callback should simply return zero.
*
* 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))
{
src/systemf.c
+20
View File
@@ -15,12 +15,32 @@
* 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 <stdarg.h>
#include <stdio.h>
#include <stdlib.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, ...)
{
va_list ap;
src/telnet.c
+41 -22
View File
@@ -15,6 +15,13 @@
* 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 <poll.h>
#include <unistd.h>
@@ -33,12 +40,19 @@
# define TELL(fmt, args...)
#endif
/** @private for internal use only */
struct sdbuf {
int sd;
int sd;
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)
{
struct sockaddr_in *sin;
@@ -93,6 +107,12 @@ sdbuf_t *telnet_open(int addr, short port)
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)
{
free(ctx->buf);
@@ -137,20 +157,19 @@ static int wait_substr(sdbuf_t *ctx, char *str)
}
/**
* telnet_expect - Poor man's telnet expect
* @ctx: Telnet session context from telnet_open()
* @script: %NULL terminated list of expect and response strings
* @output: Optional output from session
* Poor man's telnet expect
* @param ctx Telnet session context from telnet_open()
* @param script @c NULL terminated list of expect and response strings
* @param output Optional output from session
*
* Issues @script sequence on telnet session specified in @ctx, with
* optional @output from session.
* Issues @p script sequence on telnet session specified in @p ctx, with
* 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
* "assword: "with response "secret\n", concluded by %NULL.
* "assword: "with response "secret\n", concluded by @c NULL.
*
* Returns:
* POSIX OK(0) or non-zero on error.
* @returns POSIX OK(0) or non-zero on error.
*/
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.
* @addr: Must be in network byte order, use htonl().
* @port: IP port to connect to, use htons().
* @script: Expect like script of paired 'expect', 'response' strings.
* @output: A &FILE pointer to a tmpfile() for output from the last command.
* Very simple expect-like implementation for telnet.
* @param addr Integer encoded IPv4 address, in network byte order, use htonl().
* @param port Internet port to connect to, in network byte order, use htons().
* @param script Expect like script of paired 'expect', 'response' strings.
* @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
* operating daemons remotely over telnet.
*
* The @script is a query-response type of list of strings leading up to
* a final command, which output is then written to the given @output file.
* The @p script is a query-response type of list of strings leading up
* to a final command, which output is then written to the given @p
* output file.
*
* Returns:
* POSIX OK(0), or non-zero with errno set on error.
* @returns POSIX OK(0), or non-zero with @a errno set on error.
*/
int telnet_session(int addr, short port, char *script[], FILE *output)
{
src/tempfile.c
+16 -7
View File
@@ -15,6 +15,13 @@
* 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 <paths.h>
#include <fcntl.h> /* O_TMPFILE requires -D_GNU_SOURCE */
@@ -22,17 +29,19 @@
#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
* GLIBC. The function uses the Linux specific %O_TMPFILE and %O_EXCL
* for security. When the %FILE is fclose()'ed the file contents is
* lost. The file is hidden in the %_PATH_TMP directory on the system.
* GLIBC. It uses the Linux specific @c O_TMPFILE and @c O_EXCL to hide
* the filename. When the @c FILE is fclose()'ed, the file contents is
* 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:
* An open %FILE pointer, or %NULL on error.
* @returns An open @c FILE pointer, or @c NULL on error.
*/
FILE *tempfile(void)
{
src/touchf.c
+11 -5
View File
@@ -15,6 +15,13 @@
* 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 <stdio.h>
#include <stdarg.h>
@@ -24,16 +31,15 @@
#include "lite.h"
/**
* touchf - Like touch() but with formatted string support
* @fmt: Formatted string to be composed into a pathname
* Like touch() but with formatted string support
* @param fmt Formatted string to be composed into a pathname
*
* 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
* buffer.
*
* Returns:
* Upon successful completion touchf() returns POSIX OK(0), otherwise,
* -1 is returned and errno is set to indicate the error.
* @returns Upon successful completion touchf() returns POSIX OK(0),
* otherwise, -1 is returned and @a errno is set to indicate error.
*/
int touchf(const char *fmt, ...)
{
src/truncatef.c
+12 -6
View File
@@ -15,6 +15,13 @@
* 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 <stdio.h>
#include <stdarg.h>
@@ -22,16 +29,15 @@
#include <unistd.h>
/**
* truncatef - Truncate a file based on the formatted string
* @length: Size in bytes to truncate file to, zero to empty it
* @fmt: Formatted string to be composed into a pathname
* Truncate a file based on the formatted string
* @param length Size in bytes to truncate file to, zero to empty it
* @param fmt Formatted string to be composed into a pathname
*
* This is an extension to the truncate() family, lessening the burden
* of having to compose the filename from parts in a seprate buffer.
*
* Returns:
* Upon successful completion truncate() returns POSIX OK(0), otherwise,
* -1 is returned and errno is set to indicate the error.
* @returns Upon successful completion truncate() returns POSIX OK(0),
* otherwise, -1 is returned and @a errno is set to indicate error.
*/
int truncatef(off_t length, const char *fmt, ...)
{
src/which.c
+17 -4
View File
@@ -15,6 +15,13 @@
* 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 <errno.h>
#include <stdio.h> /* snprintf() */
@@ -38,8 +45,11 @@ static char *strip_args(char *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)
{
@@ -103,8 +113,11 @@ char *which(const char *cmd)
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)
{
src/yorn.c
+10 -4
View File
@@ -15,6 +15,13 @@
* 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_ext.h> /* __fpurge() */
#include <stdarg.h>
@@ -56,14 +63,13 @@ static char rawgetch(void)
}
/**
* yorn - Pose a a Yes or No question and return answer
* @fmt: Standard printf() style argument(s).
* Pose a a Yes or No question and return answer
* @param fmt Standard printf() style argument(s).
*
* This function prints the given question on screen, waits for user
* input in the form of yes or no.
*
* Returns:
* True(1) or False(0). True if the answer is yes.
* @returns TRUE(1) or FALSE(0). True if the answer is yes.
*/
int yorn(const char *fmt, ...)
{