OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

Compare Revisions

  • This comparison shows the changes necessary to convert path 
    /or1k/trunk/rtems-20020807/doc/new_chapters
    from Rev 1028 to Rev 1765
    ↔ Reverse comparison
  •

Rev 1028 → Rev 1765

/adminiface.t
0,0 → 1,129
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c adminiface.t,v 1.12 2002/01/17 21:47:45 joel Exp
@c
 
@chapter Administration Interface Manager
 
@section Introduction
 
The administration interface manager provides a portable
interface for some system administrative functions.
The capabilities in this manager are defined in the POSIX
1003.1h/D3 proposed standard titled @b{Services for Reliable,
Available, and Serviceable Systems}.
 
The directives provided by the administration interface manager are:
 
@itemize @bullet
@item @code{admin_shutdown} - Shutdown the system
@end itemize
 
@section Background
 
@subsection admin_args Structure
 
@example
put structure here
@end example
 
@table @b
@item admin_type
This field ...
 
@table @b
@item ADMIN_AUTOBOOT
The default, causing the system to reboot in its usual fashion. The
@code{admin_data} field points to an implementation defined string
that specifies the system image to reboot.
 
@item ADMIN_HALT
The system is simply halted; no reboot takes place.
 
@item ADMIN_FAST
The system does no send SIGTERM to active processes before halting.
 
@item ADMIN_IMMEDIATE
The system does not perform any of the normal shutdown procedures.
 
@item ADMIN_ALTSYSTEM
The system reboots using the @code{admin_data} string as a specification
of the system to be booted.
 
@item ADMIN_ALTCONFIG
The system reboots using the @code{admin_data} string as a specification
of the initial implicit configuration space.
 
@item ADMIN_SYSDUMP
Dump kernal memory before rebooting.
 
@item ADMIN_INIT
An option allowing the specification of an alternate initial program
to be run when the system reboots.
 
@end table
 
@item admin_data
This field ...
 
@end table
 
@section Operations
 
@subsection Shutting Down the System
 
@section Directives
 
This section details the administration interface manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
 
@page
@subsection admin_shutdown - Shutdown the system
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <admin.h>
 
int admin_shutdown(
struct admin_args *args[],
size_t nargs
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
@table @b
@item EINVAL
An invalid argument was passed to the function call.
 
@item EPERM
The caller does not have appropriate permission for shutting down the
system.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{admin_shutdown} function restarts the system. The
@code{args} argument specifies alternate or optional behavior
for the @code{admin_shutdown} function. The @code{admin_type}
member of each element of the @code{args} array specifies the
optional behavior to be performed. There are some @code{admin_types}
values that may provoke unspecified behavior. The @code{nargs}
argument specifies the length of the @code{args} array.
 
@subheading NOTES:
 
The @code{_POSIX_ADMIN} feature flag is defined to indicate
this service is available.
/Makefile.in
0,0 → 1,568
# Makefile.in generated by automake 1.6.2 from Makefile.am.
# @configure_input@
 
# Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002
# Free Software Foundation, Inc.
# This Makefile.in is free software; the Free Software Foundation
# gives unlimited permission to copy and/or distribute it,
# with or without modifications, as long as this notice is preserved.
 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
# PARTICULAR PURPOSE.
 
@SET_MAKE@
 
#
# COPYRIGHT (c) 1988-2002.
# On-Line Applications Research Corporation (OAR).
# All rights reserved.
#
# Makefile.am,v 1.6 2002/03/28 00:53:05 joel Exp
#
SHELL = @SHELL@
 
srcdir = @srcdir@
top_srcdir = @top_srcdir@
VPATH = @srcdir@
prefix = @prefix@
exec_prefix = @exec_prefix@
 
bindir = @bindir@
sbindir = @sbindir@
libexecdir = @libexecdir@
datadir = @datadir@
sysconfdir = @sysconfdir@
sharedstatedir = @sharedstatedir@
localstatedir = @localstatedir@
libdir = @libdir@
infodir = @infodir@
mandir = @mandir@
includedir = @includedir@
oldincludedir = /usr/include
pkgdatadir = $(datadir)/@PACKAGE@
pkglibdir = $(libdir)/@PACKAGE@
pkgincludedir = $(includedir)/@PACKAGE@
top_builddir = ..
 
ACLOCAL = @ACLOCAL@
AUTOCONF = @AUTOCONF@
AUTOMAKE = @AUTOMAKE@
AUTOHEADER = @AUTOHEADER@
 
am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
INSTALL = @INSTALL@
INSTALL_PROGRAM = @INSTALL_PROGRAM@
INSTALL_DATA = @INSTALL_DATA@
install_sh_DATA = $(install_sh) -c -m 644
install_sh_PROGRAM = $(install_sh) -c
install_sh_SCRIPT = $(install_sh) -c
INSTALL_SCRIPT = @INSTALL_SCRIPT@
INSTALL_HEADER = $(INSTALL_DATA)
transform = @program_transform_name@
NORMAL_INSTALL = :
PRE_INSTALL = :
POST_INSTALL = :
NORMAL_UNINSTALL = :
PRE_UNINSTALL = :
POST_UNINSTALL = :
 
EXEEXT = @EXEEXT@
OBJEXT = @OBJEXT@
PATH_SEPARATOR = @PATH_SEPARATOR@
AMTAR = @AMTAR@
AWK = @AWK@
BMENU2 = @BMENU2@
DEPDIR = @DEPDIR@
DVIPS = @DVIPS@
ENDIF = @ENDIF@
EPSTOPDF = @EPSTOPDF@
GS = @GS@
INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
LN_S = @LN_S@
MAINT = @MAINT@
MAKE = @MAKE@
PACKAGE = @PACKAGE@
PERL = @PERL@
PROJECT_ROOT = @PROJECT_ROOT@
PROJECT_TOPdir = @PROJECT_TOPdir@
RTEMS_TOPdir = @RTEMS_TOPdir@
STRIP = @STRIP@
TEXI2DVI = @TEXI2DVI@
TEXI2PDF = @TEXI2PDF@
TEXI2WWW = @TEXI2WWW@
VERSION = @VERSION@
am__include = @am__include@
am__quote = @am__quote@
htmldir = @htmldir@
install_sh = @install_sh@
pkgdocdir = @pkgdocdir@
 
PROJECT = new_chapters
EDITION = 1
 
SUFFIXES = .t .pdf .eps .html
 
MAINTAINERCLEANFILES = $(PROJECT) $(PROJECT)-[0-9] $(PROJECT)-[0-9][0-9] $(GENERATED_FILES)
 
MOSTLYCLEANFILES = $(PDF_IMAGES) index.html $(PROJECT)*.html rtems_header.html \
rtems_footer.html
 
CLEANFILES = $(PROJECT).pdf
 
dvidir = $(pkgdocdir)/dvi
 
psdir = $(pkgdocdir)/ps
 
pdfdir = $(pkgdocdir)/pdf
 
@USE_HTML_TRUE@html_project_DATA = index.html $(PROJECT)*.html
 
@USE_DVI_TRUE@dvi_DATA = $(PROJECT).dvi
 
@USE_DVI_TRUE@@USE_PS_TRUE@ps_DATA = $(PROJECT).ps
 
@USE_PDF_TRUE@pdf_DATA = $(PROJECT).pdf
AM_MAKEINFOFLAGS = -I ..
 
html_projectdir = $(htmldir)/$(PROJECT)
 
TEXI2WWW_ARGS = \
-I $(srcdir) -I $(top_srcdir) \
-dirfile ../index.html \
-header rtems_header.html \
-footer rtems_footer.html \
-icons ../images
 
 
GENERATED_FILES = adminiface.texi confspace.texi dumpcontrol.texi \
eventlog.texi stackchk.texi rtmonuse.texi cpuuse.texi error.texi \
monitor.texi
 
 
COMMON_FILES = $(top_srcdir)/common/setup.texi \
$(top_srcdir)/common/cpright.texi
 
 
FILES =
 
info_TEXINFOS = new_chapters.texi
new_chapters_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)
 
noinst_SCRIPTS = gen_section
 
EXTRA_DIST = adminiface.t base.t confspace.t cpuuse.t dumpcontrol.t error.t \
eventlog.t monitor.t rtmonuse.t stackchk.t STATUS TODO $(noinst_SCRIPTS)
 
subdir = new_chapters
mkinstalldirs = $(SHELL) $(top_srcdir)/../mkinstalldirs
CONFIG_CLEAN_FILES =
SCRIPTS = $(noinst_SCRIPTS)
 
CFLAGS = @CFLAGS@
COMPILE = $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) \
$(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
CCLD = $(CC)
LINK = $(CCLD) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@
DIST_SOURCES =
TEXINFO_TEX = $(top_srcdir)/../texinfo.tex
INFO_DEPS = new_chapters
DVIS = new_chapters.dvi
TEXINFOS = new_chapters.texi
DATA = $(dvi_DATA) $(html_project_DATA) $(pdf_DATA) $(ps_DATA)
 
DIST_COMMON = $(new_chapters_TEXINFOS) ChangeLog Makefile.am \
Makefile.in TODO stamp-vti version.texi
all: all-am
 
.SUFFIXES:
.SUFFIXES: .t .pdf .eps .html .dvi .info .ps .texi
$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ Makefile.am $(top_srcdir)/project.am $(top_srcdir)/main.am $(top_srcdir)/configure.ac $(ACLOCAL_M4)
cd $(top_srcdir) && \
$(AUTOMAKE) --foreign new_chapters/Makefile
Makefile: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.in $(top_builddir)/config.status
cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)
 
$(srcdir)/version.texi: @MAINTAINER_MODE_TRUE@ $(srcdir)/stamp-vti
@:
$(srcdir)/stamp-vti: new_chapters.texi $(top_srcdir)/configure.ac
@(set `$(SHELL) $(top_srcdir)/../mdate-sh $(srcdir)/new_chapters.texi`; \
echo "@set UPDATED $$1 $$2 $$3"; \
echo "@set UPDATED-MONTH $$2 $$3"; \
echo "@set EDITION $(VERSION)"; \
echo "@set VERSION $(VERSION)") > vti.tmp
@cmp -s vti.tmp $(srcdir)/version.texi \
|| (echo "Updating $(srcdir)/version.texi"; \
cp vti.tmp $(srcdir)/version.texi)
-@rm -f vti.tmp
@cp $(srcdir)/version.texi $@
 
mostlyclean-vti:
-rm -f vti.tmp
 
maintainer-clean-vti:
@MAINTAINER_MODE_TRUE@ -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi
 
new_chapters: new_chapters.texi $(srcdir)/version.texi $(new_chapters_TEXINFOS)
new_chapters.dvi: new_chapters.texi $(srcdir)/version.texi $(new_chapters_TEXINFOS)
 
.texi.info:
@cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
cd $(srcdir) \
&& $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \
`echo $< | sed 's,.*/,,'`
 
@USE_DVI_FALSE@.texi.dvi:
@USE_DVI_FALSE@ TEXINPUTS="$(top_srcdir)/..$(PATH_SEPARATOR)$$TEXINPUTS" \
@USE_DVI_FALSE@ MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
@USE_DVI_FALSE@ $(TEXI2DVI) $<
 
.texi:
@cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
cd $(srcdir) \
&& $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \
`echo $< | sed 's,.*/,,'`
 
MAKEINFO = @MAKEINFO@
@USE_DVI_FALSE@@USE_PS_TRUE@.dvi.ps:
@USE_DVI_FALSE@@USE_PS_TRUE@ $(DVIPS) $< -o $@
@USE_DVI_TRUE@@USE_PS_FALSE@.dvi.ps:
@USE_DVI_TRUE@@USE_PS_FALSE@ $(DVIPS) $< -o $@
@USE_DVI_FALSE@@USE_PS_FALSE@.dvi.ps:
@USE_DVI_FALSE@@USE_PS_FALSE@ $(DVIPS) $< -o $@
 
uninstall-info-am:
$(PRE_UNINSTALL)
@if (install-info --version && \
install-info --version | fgrep -i -v debian) >/dev/null 2>&1; then \
list='$(INFO_DEPS)'; \
for file in $$list; do \
echo " install-info --info-dir=$(DESTDIR)$(infodir) --remove $(DESTDIR)$(infodir)/$$file"; \
install-info --info-dir=$(DESTDIR)$(infodir) --remove $(DESTDIR)$(infodir)/$$file; \
done; \
else :; fi
@$(NORMAL_UNINSTALL)
@list='$(INFO_DEPS)'; \
for file in $$list; do \
(if cd $(DESTDIR)$(infodir); then \
echo " rm -f $$file $$file-[0-9] $$file-[0-9][0-9])"; \
rm -f $$file $$file-[0-9] $$file-[0-9][0-9]; \
else :; fi); \
done
 
dist-info: $(INFO_DEPS)
list='$(INFO_DEPS)'; \
for base in $$list; do \
d=$(srcdir); \
for file in $$d/$$base*; do \
relfile=`expr "$$file" : "$$d/\(.*\)"`; \
test -f $(distdir)/$$relfile || \
cp -p $$file $(distdir)/$$relfile; \
done; \
done
 
mostlyclean-aminfo:
-rm -f new_chapters.aux new_chapters.cp new_chapters.cps new_chapters.dvi \
new_chapters.fn new_chapters.fns new_chapters.ky \
new_chapters.log new_chapters.pg new_chapters.ps \
new_chapters.toc new_chapters.tp new_chapters.vr
 
maintainer-clean-aminfo:
cd $(srcdir) && \
list='$(INFO_DEPS)'; for i in $$list; do \
rm -f $$i; \
if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \
rm -f $$i-[0-9]*; \
fi; \
done
dviDATA_INSTALL = $(INSTALL_DATA)
install-dviDATA: $(dvi_DATA)
@$(NORMAL_INSTALL)
$(mkinstalldirs) $(DESTDIR)$(dvidir)
@list='$(dvi_DATA)'; for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
f="`echo $$p | sed -e 's|^.*/||'`"; \
echo " $(dviDATA_INSTALL) $$d$$p $(DESTDIR)$(dvidir)/$$f"; \
$(dviDATA_INSTALL) $$d$$p $(DESTDIR)$(dvidir)/$$f; \
done
 
uninstall-dviDATA:
@$(NORMAL_UNINSTALL)
@list='$(dvi_DATA)'; for p in $$list; do \
f="`echo $$p | sed -e 's|^.*/||'`"; \
echo " rm -f $(DESTDIR)$(dvidir)/$$f"; \
rm -f $(DESTDIR)$(dvidir)/$$f; \
done
html_projectDATA_INSTALL = $(INSTALL_DATA)
install-html_projectDATA: $(html_project_DATA)
@$(NORMAL_INSTALL)
$(mkinstalldirs) $(DESTDIR)$(html_projectdir)
@list='$(html_project_DATA)'; for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
f="`echo $$p | sed -e 's|^.*/||'`"; \
echo " $(html_projectDATA_INSTALL) $$d$$p $(DESTDIR)$(html_projectdir)/$$f"; \
$(html_projectDATA_INSTALL) $$d$$p $(DESTDIR)$(html_projectdir)/$$f; \
done
 
uninstall-html_projectDATA:
@$(NORMAL_UNINSTALL)
@list='$(html_project_DATA)'; for p in $$list; do \
f="`echo $$p | sed -e 's|^.*/||'`"; \
echo " rm -f $(DESTDIR)$(html_projectdir)/$$f"; \
rm -f $(DESTDIR)$(html_projectdir)/$$f; \
done
pdfDATA_INSTALL = $(INSTALL_DATA)
install-pdfDATA: $(pdf_DATA)
@$(NORMAL_INSTALL)
$(mkinstalldirs) $(DESTDIR)$(pdfdir)
@list='$(pdf_DATA)'; for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
f="`echo $$p | sed -e 's|^.*/||'`"; \
echo " $(pdfDATA_INSTALL) $$d$$p $(DESTDIR)$(pdfdir)/$$f"; \
$(pdfDATA_INSTALL) $$d$$p $(DESTDIR)$(pdfdir)/$$f; \
done
 
uninstall-pdfDATA:
@$(NORMAL_UNINSTALL)
@list='$(pdf_DATA)'; for p in $$list; do \
f="`echo $$p | sed -e 's|^.*/||'`"; \
echo " rm -f $(DESTDIR)$(pdfdir)/$$f"; \
rm -f $(DESTDIR)$(pdfdir)/$$f; \
done
psDATA_INSTALL = $(INSTALL_DATA)
install-psDATA: $(ps_DATA)
@$(NORMAL_INSTALL)
$(mkinstalldirs) $(DESTDIR)$(psdir)
@list='$(ps_DATA)'; for p in $$list; do \
if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
f="`echo $$p | sed -e 's|^.*/||'`"; \
echo " $(psDATA_INSTALL) $$d$$p $(DESTDIR)$(psdir)/$$f"; \
$(psDATA_INSTALL) $$d$$p $(DESTDIR)$(psdir)/$$f; \
done
 
uninstall-psDATA:
@$(NORMAL_UNINSTALL)
@list='$(ps_DATA)'; for p in $$list; do \
f="`echo $$p | sed -e 's|^.*/||'`"; \
echo " rm -f $(DESTDIR)$(psdir)/$$f"; \
rm -f $(DESTDIR)$(psdir)/$$f; \
done
tags: TAGS
TAGS:
 
DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
 
top_distdir = ..
distdir = $(top_distdir)/$(PACKAGE)-$(VERSION)
 
distdir: $(DISTFILES)
$(mkinstalldirs) $(distdir)/$(top_srcdir)/common
@list='$(DISTFILES)'; for file in $$list; do \
if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \
if test "$$dir" != "$$file" && test "$$dir" != "."; then \
dir="/$$dir"; \
$(mkinstalldirs) "$(distdir)$$dir"; \
else \
dir=''; \
fi; \
if test -d $$d/$$file; then \
if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \
cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \
fi; \
cp -pR $$d/$$file $(distdir)$$dir || exit 1; \
else \
test -f $(distdir)/$$file \
|| cp -p $$d/$$file $(distdir)/$$file \
|| exit 1; \
fi; \
done
$(MAKE) $(AM_MAKEFLAGS) \
top_distdir="${top_distdir}" distdir="$(distdir)" \
dist-info
check-am: all-am
check: check-am
all-am: Makefile $(INFO_DEPS) $(SCRIPTS) $(DATA)
 
installdirs:
$(mkinstalldirs) $(DESTDIR)$(infodir) $(DESTDIR)$(dvidir) $(DESTDIR)$(html_projectdir) $(DESTDIR)$(pdfdir) $(DESTDIR)$(psdir)
 
install: install-am
install-exec: install-exec-am
install-data: install-data-am
uninstall: uninstall-am
 
install-am: all-am
@$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
 
installcheck: installcheck-am
install-strip:
$(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
INSTALL_STRIP_FLAG=-s \
`test -z '$(STRIP)' || \
echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
mostlyclean-generic:
-test -z "$(MOSTLYCLEANFILES)" || rm -f $(MOSTLYCLEANFILES)
 
clean-generic:
-test -z "$(CLEANFILES)" || rm -f $(CLEANFILES)
 
distclean-generic:
-rm -f Makefile $(CONFIG_CLEAN_FILES)
 
maintainer-clean-generic:
@echo "This command is intended for maintainers to use"
@echo "it deletes files that may require special tools to rebuild."
-test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES)
clean: clean-am
 
clean-am: clean-generic mostlyclean-am
 
distclean: distclean-am
 
distclean-am: clean-am distclean-generic
 
dvi: dvi-am
 
dvi-am: $(DVIS)
 
info: info-am
 
info-am: $(INFO_DEPS)
 
install-data-am: install-dviDATA install-html_projectDATA \
install-info-am install-pdfDATA install-psDATA
 
install-exec-am:
 
install-info: install-info-am
 
install-info-am: $(INFO_DEPS)
@$(NORMAL_INSTALL)
$(mkinstalldirs) $(DESTDIR)$(infodir)
@list='$(INFO_DEPS)'; \
for file in $$list; do \
d=$(srcdir); \
for ifile in echo $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9]; do \
if test -f $$ifile; then \
relfile=`expr "$$ifile" : "$$d/\(.*\)"`; \
echo " $(INSTALL_DATA) $$ifile $(DESTDIR)$(infodir)/$$relfile"; \
$(INSTALL_DATA) $$ifile $(DESTDIR)$(infodir)/$$relfile; \
else : ; fi; \
done; \
done
@$(POST_INSTALL)
@if (install-info --version && \
install-info --version | fgrep -i -v debian) >/dev/null 2>&1; then \
list='$(INFO_DEPS)'; \
for file in $$list; do \
echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\
install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\
done; \
else : ; fi
install-man:
 
installcheck-am:
 
maintainer-clean: maintainer-clean-am
 
maintainer-clean-am: distclean-am maintainer-clean-aminfo \
maintainer-clean-generic maintainer-clean-vti
 
mostlyclean: mostlyclean-am
 
mostlyclean-am: mostlyclean-aminfo mostlyclean-generic mostlyclean-vti
 
uninstall-am: uninstall-dviDATA uninstall-html_projectDATA \
uninstall-info-am uninstall-pdfDATA uninstall-psDATA
 
.PHONY: all all-am check check-am clean clean-generic dist-info \
distclean distclean-generic distdir dvi dvi-am info info-am \
install install-am install-data install-data-am install-dviDATA \
install-exec install-exec-am install-html_projectDATA \
install-info install-info-am install-man install-pdfDATA \
install-psDATA install-strip installcheck installcheck-am \
installdirs maintainer-clean maintainer-clean-aminfo \
maintainer-clean-generic maintainer-clean-vti mostlyclean \
mostlyclean-aminfo mostlyclean-generic mostlyclean-vti \
uninstall uninstall-am uninstall-dviDATA \
uninstall-html_projectDATA uninstall-info-am uninstall-pdfDATA \
uninstall-psDATA
 
 
@EPSTOPDF_TRUE@.eps.pdf:
@EPSTOPDF_TRUE@ $(EPSTOPDF) $< --outfile=$@
 
$(PROJECT).pdf: $(PROJECT).texi $($(PROJECT)_TEXINFOS) $(PDF_IMAGES)
 
rtems_header.html: $(top_srcdir)/rtems_header.html.in version.texi
@sed -e s%\.\./images/%$(top_builddir)/images/%g \
-e s%\@VERSION\@%@VERSION@%g \
< $< > $@
rtems_footer.html: $(top_srcdir)/rtems_footer.html.in version.texi
@sed -e s%\.\./images/%$(top_builddir)/%g \
-e s%\@VERSION\@%@VERSION@%g \
< $< > $@
 
index.html $(PROJECT)*.html: $(PROJECT).texi \
rtems_header.html rtems_footer.html
$(TEXI2WWW) $(TEXI2WWW_ARGS) -base $(PROJECT) $<
 
@USE_DVI_TRUE@.texi.dvi:
@USE_DVI_TRUE@ $(TEXI2DVI) -q -I $(srcdir) -I $(top_srcdir) $<
@USE_DVI_TRUE@@USE_PS_TRUE@.dvi.ps:
@USE_DVI_TRUE@@USE_PS_TRUE@ TEXINPUTS="$(srcdir)$(PATH_SEPARATOR)$$TEXINPUTS" \
@USE_DVI_TRUE@@USE_PS_TRUE@ $(DVIPS) $< -o $@
 
@TEXI2PDF_TRUE@@USE_PDF_TRUE@.texi.pdf:
@TEXI2PDF_TRUE@@USE_PDF_TRUE@ rm -f *.aux *.cp *.fn *.ky *.pg *.tp *.toc *.vr
@TEXI2PDF_TRUE@@USE_PDF_TRUE@ $(TEXI2PDF) -q -I $(srcdir) -I $(top_srcdir) $<
 
$(srcdir)/eventlog.texi: eventlog.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/dumpcontrol.texi: dumpcontrol.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/confspace.texi: confspace.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/adminiface.texi: adminiface.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/stackchk.texi: stackchk.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/rtmonuse.texi: rtmonuse.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/cpuuse.texi: cpuuse.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/error.texi: error.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/monitor.texi: monitor.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
# Tell versions [3.59,3.63) of GNU make to not export all variables.
# Otherwise a system limit (for SysV at least) may be exceeded.
.NOEXPORT:
/STATUS
0,0 → 1,9
#
# STATUS,v 1.3 2002/01/17 21:47:45 joel Exp
#
 
Each of the chapters is individually generated with no attempt to link
the chapters together into a long hypertext chain.
 
Some are chapters for POSIX 1003.1h managers. Some are RTEMS support
libraries that we have not figured out where to put in the documentation.
/stamp-vti
0,0 → 1,4
@set UPDATED 17 January 2002
@set UPDATED-MONTH January 2002
@set EDITION ss-20020717
@set VERSION ss-20020717
/eventlog.t
0,0 → 1,1265
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c eventlog.t,v 1.27 2002/01/17 21:47:45 joel Exp
@c
 
@chapter Event Logging Manager
 
@section Introduction
 
The event logging manager provides a portable method for logging
system and application events and subsequent processing of those
events. The capabilities in this manager were defined in the POSIX
1003.1h/D3 proposed standard titled @b{Services for Reliable,
Available, and Serviceable Systems}.
 
The directives provided by the event logging manager are:
 
@itemize @bullet
@item @code{log_create} - Create a log file
@item @code{log_sys_create} - Create a system log file
@item @code{log_write} - Write to the system Log
@item @code{log_write_any} - Write to any log file
@item @code{log_write_entry} - Write entry to any log file
@item @code{log_open} - Open a log file
@item @code{log_read} - Read from a log file
@item @code{log_notify} - Notify Process of writes to the system log
@item @code{log_close} - Close log descriptor
@item @code{log_seek} - Reposition log file offset
@item @code{log_severity_before} - Compare event record severities
@item @code{log_facilityemptyset} - Manipulate log facility sets
@item @code{log_facilityfillset} - Manipulate log facility sets
@item @code{log_facilityaddset} - Manipulate log facility sets
@item @code{log_facilitydelset} - Manipulate log facility sets
@item @code{log_facilityismember} - Manipulate log facility sets
@item @code{log_facilityisvalid} - Manipulate log facility sets
@end itemize
 
@section Background
 
@subsection Log Files and Events
 
The operating system uses a special log file named @code{syslog}.
This log file is called the system log and is automatically created and
tracked by the operating system. The system log is written with
the @code{log_write()} function. An alternative log file may be written
using the @code{log_write_any()} function. It is possible to use @code{log_read()}
to query the system log and and write the records to a non-system log file
using @code{log_write_entry()} to produce a filtered version of the
system log. For example you could produce a log of all disk controller
faults that have occurred.
 
A non-system log may be a special log file created by an application to
describe application faults, or a subset of the system log created
by the application.
 
 
 
@subsection Facilities
 
A facility is an identification code for a subsystem, device, or
other object about which information is being written to
a log file.
 
A facility set is a collection of facilities.
 
@subsection Severity
 
Severity is a rating of the error that is being logged.
 
@subsection Queries
 
 
The facility identifier and the event severity are the basis for
subsequent log query. A log query is used as a filter to
obtain a subset of a given log file. The log file may be configured
to send out an event.
 
@section Operations
 
@subsection Creating and Writing a non-System Log
 
The following code fragment create a non-System log file at /temp/.
A real filename previously read entry and buffer @code{log_buf} of size
@code{readsize} are written into the log. See the discussion on opening
and reading a log for how the entry is created.
 
@example
#include <evlog.h>
:
logd_t *outlog = NULL;
char *path = "/temp/";
 
log_create( outlog, path );
:
log_write_entry( outlog, &entry, log_buf, readsize );
 
@end example
 
@subsection Reading a Log
 
Discuss opening and reading from a log.
 
@example
build a query
log_open
log_read loop
@end example
 
@section Directives
 
This section details the event logging manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
 
@page
@subsection log_write - Write to the system Log
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_write(
const log_facility_t facility,
const int event_id,
const log_severity_t severity,
const void *buf,
const size_t len
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_write()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item E2BIG
This error indicates an inconsistency in the implementation.
Report this as a bug.
 
@item EINVAL
The @code{facility} argument is not a valid log facility.
 
@item EINVAL
The @code{severity} argument exceeds @code{LOG_SEVERITY_MAX}.
 
@item EINVAL
The @code{len} argument exceeds @code{LOG_MAXIUM_BUFFER_SIZE}.
 
@item EINVAL
The @code{len} argument was non-zero and @code{buf} is @code{NULL}.
 
@item ENOSPC
The device which contains the log file has run out of space.
 
@item EIO
An I/O error occurred in writing to the log file.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_write} function writes an event record to the
system log file. The event record written consists of the
event attributes specified by the @code{facility}, @code{event_id},
and @code{severity} arguments as well as the data identified by the
@code{buf} and @code{len} arguments. The fields of the event record
structure to be written are filled in as follows:
 
@table @b
@item log_recid
This is set to a monotonically increasing log record id
maintained by the system for this individual log file.
 
@item log_size
This is set to the value of the @code{len} argument.
 
@item log_event_id
This is set to the value of the @code{event_id} argument.
 
@item log_facility
This is set to the value of the @code{facility} argument.
 
@item log_severity
This is set to the value of the @code{severity} argument.
 
@item log_uid
This is set to the value returned by @code{geteuid()}.
 
@item log_gid
This is set to the value returned by @code{getegid()}.
 
@item log_pid
This is set to the value returned by @code{getpid()}.
 
@item log_pgrp
This is set to the value returned by @code{getpgrp()}.
 
@item log_time
This is set to the value returned by @code{clock_gettime()} for the
@code{CLOCK_REALTIME clock} source.
 
@end table
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
This implementation can not return the @code{EPERM} error.
 
@page
@subsection log_write_any - Write to the any log file
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_write_any(
const logd_t logdes,
const log_facility_t facility,
const int event_id,
const log_severity_t severity,
const void *buf,
const size_t len
);
@end example
@end ifset
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_write_any()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item E2BIG
This error indicates an inconsistency in the implementation.
Report this as a bug.
 
@item EBADF
The @code{logdes} argument is not a valid log descriptor.
 
@item EINVAL
The @code{facility} argument is not a valid log facility.
 
@item EINVAL
The @code{severity} argument exceeds @code{LOG_SEVERITY_MAX}.
 
@item EINVAL
The @code{len} argument exceeds @code{LOG_MAXIMUM_BUFFER_SIZE}.
 
@item EINVAL
The @code{len} argument was non-zero and @code{buf} is @code{NULL}.
 
@item ENOSPC
The device which contains the log file has run out of space.
 
@item EIO
An I/O error occurred in writing to the log file.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_write_any()} function writes an event record to the log file
specified by @code{logdes}. The event record written consists of the
event attributes specified by the @code{facility}, @code{event_id},
and @code{severity} arguments as well as the data identified by the
@code{buf} and @code{len} arguments. The fields of the event record
structure to be written are filled in as follows:
 
@table @b
@item log_recid
This is set to a monotonically increasing log record id
maintained by the system for this individual log file.
 
@item log_size
This is set to the value of the @code{len} argument.
 
@item log_event_id
This is set to the value of the @code{event_id} argument.
 
@item log_facility
This is set to the value of the @code{facility} argument.
 
@item log_severity
This is set to the value of the @code{severity} argument.
 
@item log_uid
This is set to the value returned by @code{geteuid()}.
 
@item log_gid
This is set to the value returned by @code{getegid()}.
 
@item log_pid
This is set to the value returned by @code{getpid()}.
 
@item log_pgrp
This is set to the value returned by @code{getpgrp()}.
 
@item log_time
This is set to the value returned by @code{clock_gettime()} for the
@code{CLOCK_REALTIME} clock source.
 
@end table
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
This implementation can not return the @code{EPERM} error.
 
This function is not defined in the POSIX specification. It is
an extension provided by this implementation.
 
@page
@subsection log_write_entry - Write entry to any log file
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_write_entry(
const logd_t logdes,
struct log_entry *entry,
const void *buf,
const size_t len
);
@end example
@end ifset
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_write_entry()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item E2BIG
This error indicates an inconsistency in the implementation.
Report this as a bug.
 
@item EBADF
The @code{logdes} argument is not a valid log descriptor.
 
@item EFAULT
The @code{entry} argument is not a valid pointer to a log entry.
 
@item EINVAL
The @code{facility} field in @code{entry} is not a valid log facility.
 
@item EINVAL
The @code{severity} field in @code{entry} exceeds @code{LOG_SEVERITY_MAX}.
 
@item EINVAL
The @code{len} argument exceeds @code{LOG_MAXIMUM_BUFFER_SIZE}.
 
@item EINVAL
The @code{len} argument was non-zero and @code{buf} is NULL.
 
@item ENOSPC
The device which contains the log file has run out of space.
 
@item EIO
An I/O error occurred in writing to the log file.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_write_entry()} function writes an event record
specified by the @code{entry}, @code{buf}, and @code{len} arguments.
Most of the fields of the event record pointed to by @code{entry}
are left intact. The following fields are filled in as follows:
 
@table @b
@item log_recid
This is set to a monotonically increasing log record id
maintained by the system for this individual log file.
 
@item log_size
This is set to the value of the @code{len} argument.
 
@end table
 
This allows existing log entries from one log file to be written to
another log file without destroying the logged information.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
This implementation can not return the @code{EPERM} error.
 
This function is not defined in the POSIX specification. It is
an extension provided by this implementation.
 
@page
@subsection log_open - Open a log file
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_open(
logd_t *logdes,
const char *path,
const log_query_t *query
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_open()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item EACCES
Search permission is denied on a component of the @code{path} prefix,
or the log file exists and read permission is denied.
 
@item EINTR
A signal interrupted the call to @code{log_open()}.
 
@item EINVAL
The log_severity field of the query argument exceeds
@code{LOG_SEVERITY_MAX}.
 
@item EINVAL
The @code{path} argument referred to a file that was not a log file.
 
@item EMFILE
Too many log file descriptors are currently in use by this
process.
 
@item ENAMETOOLONG
The length of the path string exceeds @code{PATH_MAX}, or a pathname
component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is
in effect.
 
@item ENFILE
Too many files are currently open in the system.
 
@item ENOENT
The file specified by the @code{path} argument does not exist.
 
@item ENOTDIR
A component of the @code{path} prefix is not a directory.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_open()} function establishes the connection between a
log file and a log file descriptor. It creates an open log file
descriptor that refers to this query stream on the specified log file
The log file descriptor is used by the other log functions to refer
to that log query stream. The @code{path} argument points to a
pathname for a log file. A @code{path} argument of @code{NULL} specifies
the current system log file.
 
The @code{query} argument is not @code{NULL}, then it points to a log query
specification that is used to filter the records in the log file on
subsequent @code{log_read()} operations. This restricts the set of
event records read using the returned log file descriptor to those
which match the query. A query match occurs for a given record when
that record's facility is a member of the query's facility set and
the record's severity is greater than or equal to the severity specified
in the query.
 
If the value of the @code{query} argument is @code{NULL}, no query filter
shall be applied.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
POSIX specifies that @code{EINVAL} will be returned if the
@code{log_facilities} field of the @code{query} argument is not
a valid facility set. In this implementation, this condition
can never occur.
 
Many error codes that POSIX specifies to be returned by @code{log_open()}
should actually be detected by @code{open()} and passed back by the
@code{log_open()} implementation. In this implementation, @code{EACCESS},
@code{EMFILE}, @code{ENAMETOOLONG}, @code{ENFILE}, @code{ENOENT},
and @code{ENOTDIR} are detected in this manner.
 
@page
@subsection log_read - Read from a log file
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_read(
const logd_t logdes,
struct log_entry *entry,
void *log_buf,
const size_t log_len,
const size_t *log_sizeread
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_read()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item E2BIG
This error indicates an inconsistency in the implementation.
Report this as a bug.
 
@item EBADF
The @code{logdes} argument is not a valid log file descriptor.
 
@item EFAULT
The @code{entry} argument is not a valid pointer to a log entry structure.
 
@item EFAULT
The @code{log_sizeread} argument is not a valid pointer to a size_t.
 
@item EBUSY
No data available. There are no unread event records remaining
in this log file.
 
@item EINTR
A signal interrupted the call to @code{log_read()}.
 
@item EIO
An I/O error occurred in reading from the event log.
 
@item EINVAL
The matching event record has data associated with it and
@code{log_buf} was not a valid pointer.
 
@item EINVAL
The matching event record has data associated with it which is
longer than @code{log_len}.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_read()} function reads the @code{log_entry}
structure and up to @code{log_len} bytes of data from the next
event record of the log file associated with the open log file
descriptor @code{logdes}. The event record read is placed
into the @code{log_entry} structure pointed to by
@code{entry} and any data into the buffer pointed to by @code{log_buf}.
The log record ID of the returned event record is be stored in the
@code{log_recid} member of the @code{log_entry} structure for the event
record.
 
If the query attribute of the open log file description associated with
the @code{logdes} is set, the event record read will match that query.
 
If the @code{log_read()} is successful the call stores the actual length
of the data associated with the event record into the location specified by
@code{log_sizeread}. This number will be less than or equal to
@code{log_len}.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
When @code{EINVAL} is returned, then no data is returned although the
event record is returned. This is an extension to the POSIX specification.
 
The POSIX specification specifically allows @code{log_read()} to write
greater than @code{log_len} bytes into @code{log_buf}. This is highly
undesirable and this implementation will NOT do this.
 
@page
@subsection log_notify - Notify Process of writes to the system log.
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_notify(
const logd_t logdes,
const struct sigevent *notification
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_notify()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item EBADF
The logdes argument is not a valid log file descriptor.
 
@item EINVAL
The notification argument specifies an invalid signal.
 
@item EINVAL
The process has requested a notify on a log that will not be
written to.
 
@item ENOSYS
The function @code{log_notify()} is not supported by this implementation.
 
@end table
 
@subheading DESCRIPTION:
 
If the argument @code{notification} is not @code{NULL} this function registers
the calling process to be notified of event records received by the system
log, which match the query parameters associated with the open log descriptor
specified by @code{logdes}. The notification specified by the
@code{notification} argument shall be sent to the process when an event
record received by the system log is matched by the query attribute of the
open log file description associated with the @code{logdes} log file
descriptor. If the calling process has already registered a notification
for the @code{logdes} log file descriptor, the new notification shall
replace the existing notification registration.
 
If the @code{notification} argument is @code{NULL} and the calling process is
currently registered to be notified for the @code{logdes} log file
descriptor, the existing registration shall be removed.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
@page
@subsection log_close - Close log descriptor
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_close(
const logd_t logdes
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_close()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item EBADF
The logdes argument is not a valid log file descriptor.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_close()} function deallocates the open log file descriptor
indicated by @code{log_des}.
 
When all log file descriptors associated with an open log file description
have been closed, the open log file description is freed.
 
If the link count of the log file is zero, when all log file descriptors
have been closed, the space occupied by the log file is freed and the
log file shall no longer be accessible.
 
If the process has successfully registered a notification request for the
log file descriptor, the registration is removed.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
@page
@subsection log_seek - Reposition log file offset
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_seek(
const logd_t logdes,
log_recid_t log_recid
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_seek()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item EBADF
The @code{logdes} argument is not a valid log file descriptor.
@item EINVAL
The @code{log_recid} argument is not a valid record id.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_seek()} function sets the log file offset of the open
log description associated with the @code{logdes} log file descriptor
to the event record in the log file identified by @code{log_recid}.
The @code{log_recid} argument is either the record id of a valid event
record or one of the following values, as defined in the header file
@code{<evlog.h>:}
 
@table @b
@item LOG_SEEK_START
Set log file position to point at the first event
record in the log file.
 
@item LOG_SEEK_END
Set log file position to point after the last event
record in the log file.
 
@end table
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
This implementation can not return EINTR.
 
This implementation can not return EINVAL to indicate that
the @code{log_recid} argument is not a valid record id.
 
@page
@subsection log_severity_before - Compare event record severities
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_severity_before(
log_severity_t s1,
log_severity_t s2
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
@table @b
@item 0
The severity of @code{s1} is less than that of @code{s2}.
 
@item 1
The severity of @code{s1} is greater than or equal that of @code{s2}.
 
@item EINVAL
The value of either s1 or s2 exceeds @code{LOG_SEVERITY_MAX}.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_severity_before()} function compares the severity order
of the @code{s1} and @code{s2} arguments. If @code{s1} is of
severity greater than or equal to that of @code{s2}, then this
function returns 1. Otherwise, it returns 0.
 
If either @code{s1} or @code{s2} specify invalid severity values, the
return value of @code{log_severity_before()} is unspecified.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
The POSIX specification of the return value for this function is ambiguous.
If EINVAL is equal to 1 in an implementation, then the application
can not distinguish between greater than and an error condition.
 
@page
@subsection log_facilityemptyset - Manipulate log facility sets
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_facilityemptyset(
log_facility_set_t *set
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_facilityemptyset()} returns a value of zero
and a unsuccessful call returns the @code{errno}.
 
@table @b
@item EFAULT
The @code{set} argument is an invalid pointer.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_facilityemptyset()} function initializes the facility
set pointed to by the argument @code{set}, such that all facilities
are excluded.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
Applications shall call either @code{log_facilityemptyset()} or
@code{log_facilityfillset()} at least once for each object of type
@code{log_facilityset_t} prior to any other use of that object. If
such an object is not initialized in this way, but is nonetheless
supplied as an argument to any of the @code{log_facilityaddset()},
@code{logfacilitydelset()}, @code{log_facilityismember()} or
@code{log_open()} functions, the results are undefined.
 
@page
@subsection log_facilityfillset - Manipulate log facility sets
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_facilityfillset(
log_facility_set_t *set
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_facilityfillset()} returns a value of zero
and a unsuccessful call returns the @code{errno}.
 
@table @b
@item EFAULT
The @code{set} argument is an invalid pointer.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_facilityfillset()} function initializes the facility
set pointed to by the argument @code{set}, such that all facilities
are included.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
Applications shall call either @code{log_facilityemptyset()} or
@code{log_facilityfillset()} at least once for each object of type
@code{log_facilityset_t} prior to any other use of that object. If
such an object is not initialized in this way, but is nonetheless
supplied as an argument to any of the @code{log_facilityaddset()},
@code{logfacilitydelset()}, @code{log_facilityismember()} or
@code{log_open()} functions, the results are undefined.
 
@page
@subsection log_facilityaddset - Manipulate log facility sets
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_facilityaddset(
log_facility_set_t *set,
log_facility_t facilityno
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_facilityaddset()} returns a value of zero
and a unsuccessful call returns the @code{errno}.
 
@table @b
@item EFAULT
The @code{set} argument is an invalid pointer.
 
@item EINVAL
The @code{facilityno} argument is not a valid facility.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_facilityaddset()} function adds the individual
facility specified by the value of the argument @code{facilityno}
to the facility set pointed to by the argument @code{set}.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
Applications shall call either @code{log_facilityemptyset()} or
@code{log_facilityfillset()} at least once for each object of type
@code{log_facilityset_t} prior to any other use of that object. If
such an object is not initialized in this way, but is nonetheless
supplied as an argument to any of the @code{log_facilityaddset()},
@code{logfacilitydelset()}, @code{log_facilityismember()} or
@code{log_open()} functions, the results are undefined.
 
@page
@subsection log_facilitydelset - Manipulate log facility sets
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_facilitydelset(
log_facility_set_t *set,
log_facility_t facilityno
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_facilitydelset()} returns a value of zero
and a unsuccessful call returns the @code{errno}.
 
@table @b
@item EFAULT
The @code{set} argument is an invalid pointer.
 
@item EINVAL
The @code{facilityno} argument is not a valid facility.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_facilitydelset()} function deletes the individual
facility specified by the value of the argument @code{facilityno}
from the facility set pointed to by the argument @code{set}.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
Applications shall call either @code{log_facilityemptyset()} or
@code{log_facilityfillset()} at least once for each object of type
@code{log_facilityset_t} prior to any other use of that object. If
such an object is not initialized in this way, but is nonetheless
supplied as an argument to any of the @code{log_facilityaddset()},
@code{logfacilitydelset()}, @code{log_facilityismember()} or
@code{log_open()} functions, the results are undefined.
 
@page
@subsection log_facilityismember - Manipulate log facility sets
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_facilityismember(
const log_facility_set_t *set,
log_facility_t facilityno,
const int *member
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_facilityismember()} returns a value
of zero and a unsuccessful call returns the @code{errno}.
 
@table @b
@item EFAULT
The @code{set} or @code{member} argument is an invalid pointer.
 
@item EINVAL
The @code{facilityno} argument is not a valid facility.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_facilityismember()} function tests whether the facility
specified by the value of the argument @code{facilityno} is a member
of the set pointed to by the argument @code{set}. Upon successful
completion, the @code{log_facilityismember()} function either returns
a value of one to the location specified by @code{member} if the
specified facility is a member of the specified set or value of
zero to the location specified by @code{member} if the specified
facility is not a member of the specified set.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
Applications shall call either @code{log_facilityemptyset()} or
@code{log_facilityfillset()} at least once for each object of type
@code{log_facilityset_t} prior to any other use of that object. If
such an object is not initialized in this way, but is nonetheless
supplied as an argument to any of the @code{log_facilityaddset()},
@code{logfacilitydelset()}, @code{log_facilityismember()} or
@code{log_open()} functions, the results are undefined.
 
@page
@subsection log_facilityisvalid - Manipulate log facility sets
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_facilityisvalid(
log_facility_t facilityno
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A return value of zero indicates that the @code{facilityno} is valid and
a return value other than zero represents an @code{errno}.
 
@table @b
@item EFAULT
The @code{set} or @code{member} argument is an invalid pointer.
 
@item EINVAL
The @code{facilityno} argument is not a valid facility.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{log_facilityisvalid()} function tests whether the facility
specified by the value of the argument @code{facilityno} is a valid
facility number. Upon successful completion, the
the @code{log_facilityisvalid()} function either returns a value of
0 if the specified facility is a valid facility or value of EINVAL
if the specified facility is not a valid facility.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
Applications shall call either @code{log_facilityemptyset()} or
@code{log_facilityfillset()} at least once for each object of type
@code{log_facilityset_t} prior to any other use of that object. If
such an object is not initialized in this way, but is nonetheless
supplied as an argument to any of the @code{log_facilityaddset()},
@code{logfacilitydelset()}, @code{log_facilityismember()} or
@code{log_open()} functions, the results are undefined.
 
@page
@subsection log_create - Creates a log file
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_create(
logd_t *ld,
const char *path,
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_create()} returns a value
of zero and a unsuccessful call returns the @code{errno}.
 
@table @b
 
@item EEXIST
The @code{path} already exists and O_CREAT and O_EXCL were used.
 
@item EISDIR
The @code{path} refers to a directory and the access requested involved
writing.
 
@item ETXTBSY
The @code{path} refers to an executable image which is currently being
executed and write access was requested.
 
@item EFAULT
The @code{path} points outside your accessible address space.
 
@item EACCES
The requested access to the file is not allowed, or one of the
directories in @code{path} did not allow search (execute) permission.
 
@item ENAMETOOLONG
The @code{path} was too long.
 
@item ENOENT
A directory component in @code{path} does not exist or is a dangling symbolic
link.
 
@item ENOTDIR
A component used as a directory in @code{path} is not, in fact, a directory.
 
@item EMFILE
The process already has the maximum number of files open.
 
@item ENFILE
The limit on the total number of files open on the system has been reached.
 
@item ENOMEM
Insufficient kernel memory was available.
 
@item EROFS
The @code{path} refers to a file on a read-only filesystem and write access
was requested.
 
@item ELOOP
The @code{path} contains a reference to a circular symbolic link, ie a
symbolic link whose expansion contains a reference to itself.
 
@end table
 
@subheading DESCRIPTION:
 
This function attempts to create a file associated with the @code{logdes}
argument in the directory provided by the argument @code{path}.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
 
@page
@subsection log_sys_create - Creates a system log file
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <evlog.h>
 
int log_sys_create();
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{log_sys_create()} returns a value
of zero and a unsuccessful call returns the @code{errno}.
 
@table @b
@item EEXIST
The directory path to the system log already exist.
 
@end table
 
@subheading DESCRIPTION:
 
This function will create a predefined system log directory path and
system log file if they do not already exist.
 
@subheading NOTES:
 
The @code{_POSIX_LOGGING} feature flag is defined to indicate
this service is available.
/ChangeLog
0,0 → 1,15
2002-03-27 Ralf Corsepius <corsepiu@faw.uni-ulm.de>
 
* Makefile.am: Remove AUTOMAKE_OPTIONS.
 
2002-01-18 Ralf Corsepius <corsepiu@faw.uni-ulm.de>
 
* Makefile.am: include main.am, require automake-1.5.
 
2001-01-17 Joel Sherrill <joel@OARcorp.com>
 
* .cvsignore: Added rtems_header.html and rtems_footer.html.
 
2000-08-10 Joel Sherrill <joel@OARcorp.com>
 
* ChangeLog: New file.
/monitor.t
0,0 → 1,224
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c monitor.t,v 1.3 2002/01/17 21:47:45 joel Exp
@c
 
@chapter Monitor Task
 
@section Introduction
 
The monitor task is a simple interactive shell that allows the user to
make inquries about he state of various system objects. The routines
provided by the monitor task manager are:
 
@itemize @bullet
@item @code{rtems_monitor_init} - Initialize the Monitor Task
@item @code{rtems_monitor_wakeup} - Wakeup the Monitor Task
@end itemize
 
@section Background
 
There is no background information.
 
@section Operations
 
@subsection Initializing the Monitor
 
The monitor is initialized by calling @code{rtems_monitor_init}. When
initialized, the monitor is created as an independent task. An example
of initializing the monitor is shown below:
 
@example
@group
#include <rtems/monitor.h>
...
rtems_monitor_init(0);
@end group
@end example
 
The "0" parameter to the @code{rtems_monitor_init} routine
causes the monitor to immediately enter command mode.
This parameter is a bitfield. If the monitor is to suspend
itself on startup, then the @code{RTEMS_MONITOR_SUSPEND} bit
should be set.
 
@section Routines
 
This section details the monitor task manager's routines.
A subsection is dedicated to each of this manager's routines
and describes the calling sequence, related constants, usage,
and status codes.
 
@page
@subsection rtems_monitor_init - Initialize the Monitor Task
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
void rtems_monitor_init(
unsigned32 monitor_flags
);
@end example
@end ifset
 
@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset
 
@subheading STATUS CODES: NONE
 
@subheading DESCRIPTION:
 
This routine initializes the RTEMS monitor task. The
@code{monitor_flags} parameter indicates how the server
task is to start. This parameter is a bitfield and
has the following constants associated with it:
 
@itemize @bullet
@item @b{RTEMS_MONITOR_SUSPEND} - suspend monitor on startup
@item @b{RTEMS_MONITOR_GLOBAL} - monitor should be global
@end itemize
 
If the @code{RTEMS_MONITOR_SUSPEND} bit is set, then the
monitor task will suspend itself after it is initialized.
A subsequent call to @code{rtems_monitor_wakeup} will be required
to activate it.
 
@subheading NOTES:
 
The monitor task is created with priority 1. If there are
application tasks at priority 1, then there may be times
when the monitor task is not executing.
 
@page
@subsection rtems_monitor_wakeup - Wakeup the Monitor Task
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
void rtems_monitor_wakeup( void );
@end example
@end ifset
 
@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset
 
@subheading STATUS CODES: NONE
 
@subheading DESCRIPTION:
 
This routine is used to activate the monitor task if it is suspended.
 
@subheading NOTES:
 
NONE
 
@page
@section Monitor Interactive Commands
 
The following commands are supported by the monitor task:
 
@itemize @bullet
@item @code{help} - Obtain Help
@item @code{pause} - Pause Monitor for a Specified Number of Ticks
@item @code{exit} - Invoke a Fatal RTEMS Error
@item @code{symbol} - Show Entries from Symbol Table
@item @code{continue} - Put Monitor to Sleep Waiting for Explicit Wakeup
@item @code{config} - Show System Configuration
@item @code{itask} - List Init Tasks
@item @code{mpci} - List MPCI Config
@item @code{task} - Show Task Information
@item @code{queue} - Show Message Queue Information
@item @code{extension} - User Extensions
@item @code{driver} - Show Information About Named Drivers
@item @code{dname} - Show Information About Named Drivers
@item @code{object} - Generic Object Information
@item @code{node} - Specify Default Node for Commands That Take IDs
@end itemize
 
 
@subsection help - Obtain Help
 
The @code{help} command prints out the list of commands. If invoked
with a command name as the first argument, detailed help information
on that command is printed.
 
@subsection pause - Pause Monitor for a Specified Number of Ticks
 
The @code{pause} command cause the monitor task to suspend itself
for the specified number of ticks. If this command is invoked with
no arguments, then the task is suspended for 1 clock tick.
 
@subsection exit - Invoke a Fatal RTEMS Error
 
The @code{exit} command invokes @code{rtems_error_occurred} directive
with the specified error code. If this command is invoked with
no arguments, then the @code{rtems_error_occurred} directive is
invoked with an arbitrary error code.
 
@subsection symbol - Show Entries from Symbol Table
 
The @code{symbol} command lists the specified entries in the symbol table.
If this command is invoked with no arguments, then all the
symbols in the symbol table are printed.
 
@subsection continue - Put Monitor to Sleep Waiting for Explicit Wakeup
 
The @code{continue} command suspends the monitor task with no timeout.
 
@subsection config - Show System Configuration
 
The @code{config} command prints the system configuration.
 
@subsection itask - List Init Tasks
 
The @code{itask} command lists the tasks in the initialization tasks table.
 
@subsection mpci - List MPCI Config
 
The @code{mpci} command shows the MPCI configuration information
 
@subsection task - Show Task Information
 
The @code{task} command prints out information about one or more tasks in
the system. If invoked with no arguments, then
information on all the tasks in the system is printed.
 
@subsection queue - Show Message Queue Information
 
The @code{queue} command prints out information about one or more
message queues in the system. If invoked with no arguments, then
information on all the message queues in the system is printed.
 
@subsection extension - User Extensions
 
The @code{extension} command prints out information about the user
extensions.
 
@subsection driver - Show Information About Named Drivers
 
The @code{driver} command prints information about the device driver table.
 
@subsection dname - Show Information About Named Drivers
 
The @code{dname} command prints information about the named device drivers.
 
@subsection object - Generic Object Information
 
The @code{object} command prints information about RTEMS objects.
 
@subsection node - Specify Default Node for Commands That Take IDs
 
The @code{node} command sets the default node for commands that look
at object ID ranges.
 
/new_chapters.texi
0,0 → 1,130
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename new_chapters
@setcontentsaftertitlepage
@syncodeindex vr fn
@synindex ky cp
@paragraphindent 0
@c %**end of header
 
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c new_chapters.texi,v 1.8 2002/01/17 21:47:45 joel Exp
@c
 
@c
@c Master file for the C User's Guide
@c
 
@c Joel's Questions
@c
@c 1. Why does paragraphindent only impact makeinfo?
@c 2. Why does paragraphindent show up in HTML?
@c
 
@include version.texi
@include common/setup.texi
 
@ifset use-ascii
@dircategory RTEMS On-Line Manual
@direntry
* RTEMS New Chapters: (new_chapters). Miscellaneous New Chapters
@end direntry
@end ifset
 
@c variable substitution info:
@c
@c Note: At the moment we do not document the Ada interface but by building
@c in the infrastructure Florist support should be simple to add.
@set is-C
@clear is-Ada
@set LANGUAGE C
@set STRUCTURE structure
@set ROUTINE function
@set OR |
@set RPREFIX RTEMS_
@set DIRPREFIX rtems_
@c the language is @value{LANGUAGE}
@c NOTE: don't use underscore in the name
@c
 
@c
@c Title Page Stuff
@c
 
@c
@c I don't really like having a short title page. --joel
@c
@c @shorttitlepage New Chapters
 
@setchapternewpage odd
@settitle New Chapters
@titlepage
@finalout
 
@title New Chapters
@subtitle Edition @value{EDITION}, for RTEMS @value{VERSION}
@sp 1
@subtitle @value{UPDATED}
@author On-Line Applications Research Corporation
@page
@include common/cpright.texi
@end titlepage
 
@c This prevents a black box from being printed on "overflow" lines.
@c The alternative is to rework a sentence to avoid this problem.
 
@include eventlog.texi
@include dumpcontrol.texi
@include confspace.texi
@include adminiface.texi
@include stackchk.texi
@include rtmonuse.texi
@include cpuuse.texi
@include error.texi
@include monitor.texi
@ifinfo
@node Top, , (dir), (dir)
@top posix_users_new
 
This is the online version of the RTEMS POSIX API User's Guide
 
@menu
* Event Logging Manager::
* Process Dump Control Manager::
* Configuration Space Manager::
* Administration Interface Manager::
* Stack Bounds Checker::
* Rate Monotonic Period Statistics::
* CPU Usage Statistics::
* Error Reporting Support::
* Monitor Task::
* Command and Variable Index::
* Concept Index::
@end menu
 
@end ifinfo
@c
@c
@c Need to copy the emacs stuff and "trailer stuff" (index, toc) into here
@c
 
@node Command and Variable Index, Concept Index, , Top
@unnumbered Command and Variable Index
 
There are currently no Command and Variable Index entries.
 
@c @printindex fn
 
@node Concept Index, , Command and Variable Index, Top
@unnumbered Concept Index
 
There are currently no Concept Index entries.
@c @printindex cp
 
@contents
@bye
 
/error.t
0,0 → 1,164
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c error.t,v 1.3 2002/01/17 21:47:45 joel Exp
@c
 
@chapter Error Reporting Support
 
@section Introduction
 
These error reporting facilities are an RTEMS support
component that provide convenient facilities for handling
error conditions in an RTEMS application.
of each task using a period. The services provided by the error
reporting support component are:
 
@itemize @bullet
@item @code{rtems_error} - Report an Error
@item @code{rtems_panic} - Report an Error and Panic
@item @code{rtems_status_text} - ASCII Version of RTEMS Status
@end itemize
 
@section Background
 
@subsection Error Handling in an Embedded System
 
Error handling in an embedded system is a difficult problem. If the error
is severe, then the only recourse is to shut the system down in a safe
manner. Other errors can be detected and compensated for. The
error reporting routines in this support component -- @code{rtems_error}
and @code{rtems_panic} assume that if the error is severe enough,
then the system should be shutdown. If a simple shutdown with
some basic diagnostic information is not sufficient, then
these routines should not be used in that particular system. In this case,
use the @code{rtems_status_text} routine to construct an application
specific error reporting routine.
 
@section Operations
 
@subsection Reporting an Error
 
The @code{rtems_error} and @code{rtems_panic} routines
can be used to print some diagnostic information and
shut the system down. The @code{rtems_error} routine
is invoked with a user specified error level indicator.
This error indicator is used to determine if the system
should be shutdown after reporting this error.
 
@section Routines
 
This section details the error reporting support compenent's routine.
A subsection is dedicated to each of this manager's routines
and describes the calling sequence, related constants, usage,
and status codes.
 
@page
@subsection rtems_status_text - ASCII Version of RTEMS Status
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
const char *rtems_status_text(
rtems_status_code status
);
@end example
@end ifset
 
@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset
 
@subheading STATUS CODES:
 
Returns a pointer to a constant string that describes the given
RTEMS status code.
 
@subheading DESCRIPTION:
 
This routine returns a pointer to a string that describes
the RTEMS status code specified by @code{status}.
 
@subheading NOTES:
 
NONE
 
@page
@subsection rtems_error - Report an Error
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
int rtems_error(
int error_code,
const char *printf_format,
...
);
@end example
@end ifset
 
@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset
 
@subheading STATUS CODES:
 
Returns the number of characters written.
 
@subheading DESCRIPTION:
 
This routine prints the requested information as specified by the
@code{printf_format} parameter and the zero or more optional arguments
following that parameter. The @code{error_code} parameter is an error
number with either @code{RTEMS_ERROR_PANIC} or @code{RTEMS_ERROR_ABORT}
bitwise or'ed with it. If the @code{RTEMS_ERROR_PANIC} bit is set, then
then the system is system is shutdown via a call to @code{_exit}.
If the @code{RTEMS_ERROR_ABORT} bit is set, then
then the system is system is shutdown via a call to @code{abort}.
 
@subheading NOTES:
 
NONE
 
@page
@subsection rtems_panic - Report an Error and Panic
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
int rtems_panic(
const char *printf_format,
...
);
@end example
@end ifset
 
@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset
 
@subheading STATUS CODES:
 
Returns the number of characters written.
 
@subheading DESCRIPTION:
 
This routine is a wrapper for the @code{rtems_error} routine with
an implied error level of @code{RTEMS_ERROR_PANIC}. See
@code{rtems_error} for more information.
 
@subheading NOTES:
 
NONE
 
/gen_section
0,0 → 1,238
#
# This shell script generates the starting template for a manager chapter.
#
 
 
# Set this based on which chapter you want to generate a template for.
chapter=$1
 
case ${chapter} in
process)
CHAPTER_CAPS="Process Creation and Execution"
CHAPTER_LOWER="process creation and execution"
ROUTINES="fork execl execv execle execve execlp execvp pthread_atfork \
wait waitpid _exit"
;;
procenv)
CHAPTER_CAPS="Process Environment"
CHAPTER_LOWER="process environment"
ROUTINES="getpid getppid getuid geteuid getgid getegid setuid setgid \
getgroups getlogin getlogin_r getpgrp setsid setpgid uname times \
getenv ctermid ttyname ttyname_r isatty sysconf "
;;
files)
CHAPTER_CAPS="Files and Directories"
CHAPTER_LOWER="files and directories"
ROUTINES="opendir readdir readdir_r rewinddir closedir \
chdir getcwd open creat umask link mkdir mkfifo unlink \
rmdir rename stat fstat access chmod fchmod chown \
utime ftrunctate pathconf fpathconf"
;;
io)
CHAPTER_CAPS="Input and Output Primitives"
CHAPTER_LOWER="input and output primitives"
ROUTINES="pipe dup dup2 close read write fcntl lseek fsynch fdatasynch \
aio_read aio_write lio_listio aio_error aio_return aio_cancel \
aio_suspend aio_fsync"
;;
device)
CHAPTER_CAPS="Device- and Class- Specific Functions"
CHAPTER_LOWER="device- and class- specific functions"
ROUTINES="cfgetispeed cfgetospeed cfsetispeed cfsetospeed tcgetattr \
tcsetattr tcsendbreak tcdrain tcflush tcflow tcgetpgrp tcsetpgrp"
;;
cspecific)
CHAPTER_CAPS="Language-Specific Services for the C Programming Language"
CHAPTER_LOWER="language-specific services for the C programming language"
ROUTINES="setlocale fileno fdopen flcokfile ftrylockfile funlockfile \
getc_unlocked getchar_unlocked putc_unlocked putchar_unlocked \
setjmp longjmp sigsetjmp siglongjmp tzset strtok_r asctime_r \
ctime_r gmtime_r localtime_r rand_r"
;;
systemdb)
CHAPTER_CAPS="System Databases"
CHAPTER_LOWER="system databases"
ROUTINES="getgrgid getgrgid_r getgrnam getgrnam_r getpwuid getpwuid_r \
getpwnam getpwnam_r"
;;
semaphores)
CHAPTER_CAPS="Semaphores"
CHAPTER_LOWER="semaphore"
ROUTINES="sem_init sem_destroy sem_open sem_close sem_unlink sem_wait \
sem_trywait sem_post sem_getvalue"
;;
memorymgmt)
CHAPTER_CAPS="Memory Management"
CHAPTER_LOWER="memory management"
ROUTINES="mlockall munlockall mlock munlock mmap munmap mprotect \
msync shm_open shm_unlink"
;;
message)
CHAPTER_CAPS="Message Passing"
CHAPTER_LOWER="message passing"
ROUTINES="mq_open mq_close mq_unlink mq_send mq_receive mq_notify \
mq_setattr mq_getattr"
;;
cancel)
CHAPTER_CAPS="Thread Cancellation"
CHAPTER_LOWER="thread cancellation"
ROUTINES="pthread_cancel pthread_setcancelstate pthread_setcanceltype \
pthread_testcancel pthread_cleanup_push"
;;
eventlog)
CHAPTER_CAPS="Event Logging"
CHAPTER_LOWER="event logging"
ROUTINES="log_write log_open log_read log_notify log_close log_seek \
log_severity_before log_facilityemptyset log_facilityfillset \
log_facilityaddset log_facilitydelset log_facilityismember"
;;
dumpcontrol)
CHAPTER_CAPS="Process Dump Control"
CHAPTER_LOWER="process dump control"
ROUTINES="dump_setpath"
;;
confspace)
CHAPTER_CAPS="Configuration Space"
CHAPTER_LOWER="configuration space"
ROUTINES="cfg_mount cfg_unmount cfg_mknod cfg_get cfg_set cfg_link \
cfg_unlink cfg_open cfg_read cfg_children cfg_mark cfg_close"
;;
adminiface)
CHAPTER_CAPS="Administration Interface"
CHAPTER_LOWER="administration interface"
ROUTINES="admin_shutdown"
;;
# XXX this is not all of the C Library Stuff
libc_ctype)
CHAPTER_CAPS="C Library Character Handling"
CHAPTER_LOWER="character handling"
ROUTINES="isalnum isalpha iscntrl isdigit isgraph islower isprint \
ispunct isspace isupper isxdigit tolower toupper"
;;
libc_math)
CHAPTER_CAPS="C Math Library"
CHAPTER_LOWER="math library"
ROUTINES="acos asis atan atan2 cos sin tan cosh sinh tanh exp frexp ldexp
log log10 modf pow sqrt ceil fabs floor fmod"
;;
libc_io)
CHAPTER_CAPS="C Library IO"
CHAPTER_LOWER="C Library IO"
ROUTINES="clearerr fclose feof ferror fflush fgetc fgets fopen fputc \
fputs fread freopen fseek ftell fwrite getc getchar gets perror \
printf fprintf sprintf putc putchar puts remove rename rewind \
scanf fscanf sscanf setbuf tempfile tmpnam ungetc"
;;
libc_string)
CHAPTER_CAPS="C Library String Handling"
CHAPTER_LOWER="string handling"
ROUTINES="strcpy strncpy strcat strncat strcmp strncmp strchr strcspn \
strpbrk strrchr strspn strstr strtok stlen"
;;
misc_stackchk)
CHAPTER_CAPS="Stack Bounds Checker"
CHAPTER_LOWER="stack bounds checker"
ROUTINES="Stack_check_Initialize Stack_check_Dump_usage"
;;
misc_rtmonuse)
CHAPTER_CAPS="Rate Monotonic Period Statistics"
CHAPTER_LOWER="rate monotonic period statistics"
ROUTINES="Period_usage_Initialize Period_usage_Reset \
Period_usage_Update Period_usage_Dump"
;;
misc_cpuuse)
CHAPTER_CAPS="CPU Usage Statistics"
CHAPTER_LOWER="CPU usage statistics"
ROUTINES="CPU_usage_Dump CPU_usage_Reset"
;;
misc_error)
CHAPTER_CAPS="Error Reporting Support"
CHAPTER_LOWER="error reporting support"
ROUTINES="rtems_error rtems_panic"
;;
misc_monitor)
CHAPTER_CAPS="Monitor Task"
CHAPTER_LOWER="monitor task"
ROUTINES="rtems_monitor_init rtems_monitor_wakeup"
;;
*)
echo "Unknown chapter name"
exit 1
;;
esac
 
if [ "x${CHAPTER_CAPS}" = "x" -o "x${CHAPTER_LOWER}" = "x" \
-o "x${ROUTINES}" = "x" ] ; then
echo "initialization problem"
exit 1
fi
 
echo "@c"
echo "@c COPYRIGHT (c) 1988-2002."
echo "@c On-Line Applications Research Corporation (OAR)."
echo "@c All rights reserved. "
echo "@c"
echo "@c \$Id\$"
echo "@c"
echo ""
echo "@chapter ${CHAPTER_CAPS}" Manager
echo ""
echo "@section Introduction"
echo ""
echo "The "
echo "${CHAPTER_LOWER} manager is ..."
echo ""
echo "The directives provided by the ${CHAPTER_LOWER} manager are:"
echo ""
echo "@itemize @bullet"
 
for routine in ${ROUTINES}
do
echo "@item @code{${routine}} - "
done
echo "@end itemize"
 
echo ""
echo "@section Background"
echo ""
echo "@section Operations"
echo ""
echo "@section Directives"
echo ""
echo "This section details the ${CHAPTER_LOWER} manager's directives."
echo "A subsection is dedicated to each of this manager's directives"
echo "and describes the calling sequence, related constants, usage,"
echo "and status codes."
echo ""
 
for routine in ${ROUTINES}
do
echo "@page"
echo "@subsection ${routine} - "
echo ""
echo "@subheading CALLING SEQUENCE:"
echo ""
echo "@ifset is-C"
echo "@example"
echo "int ${routine}("
echo ");"
echo "@end example"
echo "@end ifset"
echo ""
echo "@ifset is-Ada"
echo "@end ifset"
echo ""
echo "@subheading STATUS CODES:"
echo ""
echo "@table @b"
echo "@item E"
echo "The"
echo ""
echo "@end table"
echo ""
echo "@subheading DESCRIPTION:"
echo ""
echo "@subheading NOTES:"
echo ""
done
 
/stackchk.t
0,0 → 1,192
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c stackchk.t,v 1.3 2002/01/17 21:47:45 joel Exp
@c
 
@chapter Stack Bounds Checker
 
@section Introduction
 
The stack bounds checker is an RTEMS support component that determines
if a task has overflowed its run-time stack. The routines provided
by the stack bounds checker manager are:
 
@itemize @bullet
@item @code{Stack_check_Initialize} - Initialize the Stack Bounds Checker
@item @code{Stack_check_Dump_usage} - Report Task Stack Usage
@end itemize
 
@section Background
 
@subsection Task Stack
 
Each task in a system has a fixed size stack associated with it. This
stack is allocated when the task is created. As the task executes, the
stack is used to contain parameters, return addresses, saved registers,
and local variables. The amount of stack space required by a task
is dependent on the exact set of routines used. The peak stack usage
reflects the worst case of subroutine pushing information on the stack.
For example, if a subroutine allocates a local buffer of 1024 bytes, then
this data must be accounted for in the stack of every task that invokes that
routine.
 
Recursive routines make calculating peak stack usage difficult, if not
impossible. Each call to the recursive routine consumes @i{n} bytes
of stack space. If the routine recursives 1000 times, then @code{1000 * @i{n}}
bytes of stack space are required.
 
@subsection Execution
 
The stack bounds checker operates as a set of task extensions. At
task creation time, the task's stack is filled with a pattern to
indicate the stack is unused. As the task executes, it will overwrite
this pattern in memory. At each task switch, the stack bounds checker's
task switch extension is executed. This extension checks that the last
@code{n} bytes of the task's stack have not been overwritten. If they
have, then a blown stack error is reported.
 
The number of bytes checked for an overwrite is processor family dependent.
The minimum stack frame per subroutine call varies widely between processor
families. On CISC families like the Motorola MC68xxx and Intel ix86, all
that is needed is a return address. On more complex RISC processors,
the minimum stack frame per subroutine call may include space to save
a significant number of registers.
 
Another processor dependent feature that must be taken into account by
the stack bounds checker is the direction that the stack grows. On some
processor families, the stack grows up or to higher addresses as the
task executes. On other families, it grows down to lower addresses. The
stack bounds checker implementation uses the stack description definitions
provided by every RTEMS port to get for this information.
 
@section Operations
 
@subsection Initializing the Stack Bounds Checker
 
The stack checker is initialized automatically when its task
create extension runs for the first time. When this occurs,
the @code{Stack_check_Initialize} is invoked.
 
The application must include the stack bounds checker extension set
in its set of Initial Extensions. This set of extensions is
defined as @code{STACK_CHECKER_EXTENSION}. If using @code{<confdefs.h>}
for Configuration Table generation, then all that is necessary is
to define the macro @code{STACK_CHECKER_ON} before including
@code{<confdefs.h>} as shown below:
 
@example
@group
#define STACK_CHECKER_ON
...
#include <confdefs.h>
@end group
@end example
 
@subsection Reporting Task Stack Usage
 
The application may dynamically report the stack usage for every task
in the system by calling the @code{Stack_check_Dump_usage} routine.
This routine prints a table with the peak usage and stack size of
every task in the system. The following is an example of the
report generated:
 
@example
@group
ID NAME LOW HIGH AVAILABLE USED
0x04010001 IDLE 0x003e8a60 0x003e9667 2952 200
0x08010002 TA1 0x003e5750 0x003e7b57 9096 1168
0x08010003 TA2 0x003e31c8 0x003e55cf 9096 1168
0x08010004 TA3 0x003e0c40 0x003e3047 9096 1104
0xffffffff INTR 0x003ecfc0 0x003effbf 12160 128
@end group
@end example
 
Notice the last time. The task id is 0xffffffff and its name is "INTR".
This is not actually a task, it is the interrupt stack.
 
@subsection When a Task Overflows the Stack
 
When the stack bounds checker determines that a stack overflow has occurred,
it will attempt to print a message identifying the task and then shut the
system down. If the stack overflow has caused corruption, then it is
possible that the message can not be printed.
 
The following is an example of the output generated:
 
@example
@group
BLOWN STACK!!! Offending task(0x3eb360): id=0x08010002; name=0x54413120
stack covers range 0x003e5750 - 0x003e7b57 (9224 bytes)
Damaged pattern begins at 0x003e5758 and is 128 bytes long
@end group
@end example
 
The above includes the task id and a pointer to the task control block as
well as enough information so one can look at the task's stack and
see what was happening.
 
@section Routines
 
This section details the stack bounds checker's routines.
A subsection is dedicated to each of routines
and describes the calling sequence, related constants, usage,
and status codes.
 
@page
@subsection Stack_check_Initialize - Initialize the Stack Bounds Checker
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
void Stack_check_Initialize( void );
@end example
@end ifset
 
@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset
 
@subheading STATUS CODES: NONE
 
@subheading DESCRIPTION:
 
Initialize the stack bounds checker.
 
@subheading NOTES:
 
This is performed automatically the first time the stack bounds checker
task create extension executes.
 
@page
@subsection Stack_check_Dump_usage - Report Task Stack Usage
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
void Stack_check_Dump_usage( void );
@end example
@end ifset
 
@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset
 
@subheading STATUS CODES: NONE
 
@subheading DESCRIPTION:
 
This routine prints a table with the peak stack usage and stack space
allocation of every task in the system.
 
@subheading NOTES:
 
NONE
/version.texi
0,0 → 1,4
@set UPDATED 17 January 2002
@set UPDATED-MONTH January 2002
@set EDITION ss-20020717
@set VERSION ss-20020717
/confspace.t
0,0 → 1,1351
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c confspace.t,v 1.19 2002/01/17 21:47:45 joel Exp
@c
 
@chapter Configuration Space Manager
 
@section Introduction
 
The configuration space manager provides a portable
interface for manipulating configuration data.
The capabilities in this manager were defined in the POSIX
1003.1h/D3 proposed standard titled @b{Services for Reliable,
Available, and Serviceable Systems}.
 
The directives provided by the configuration space manager are:
 
@itemize @bullet
@item @code{cfg_mount} - Mount a Configuration Space
@item @code{cfg_unmount} - Unmount a Configuration Space
@item @code{cfg_mknod} - Create a Configuration Node
@item @code{cfg_get} - Get Configuration Node Value
@item @code{cfg_set} - Set Configuration Node Value
@item @code{cfg_link} - Create a Configuration Link
@item @code{cfg_unlink} - Remove a Configuration Link
@item @code{cfg_open} - Open a Configuration Space
@item @code{cfg_read} - Read a Configuration Space
@item @code{cfg_children} - Get Node Entries
@item @code{cfg_mark} - Set Configuration Space Option
@item @code{cfg_readdir} - Reads a directory
@item @code{cfg_umask} - Sets a file creation mask
@item @code{cfg_chmod} - Changes file mode
@item @code{cfg_chown} - Changes the owner and/or group of a file
@end itemize
 
@section Background
 
@subsection Configuration Nodes
 
@subsection Configuration Space
 
@subsection Format of a Configuration Space File
 
@section Operations
 
@subsection Mount and Unmounting
 
@subsection Creating a Configuration Node
 
@subsection Removing a Configuration Node
 
@subsection Manipulating a Configuration Node
 
@subsection Traversing a Configuration Space
 
@section Directives
 
This section details the configuration space manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
 
@page
@subsection cfg_mount - Mount a Configuration Space
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <cfg.h>
 
int cfg_mount(
const char *file,
const char *cfgpath,
log_facility_t notification,
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_mount()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item EPERM
The caller does not have the appropriate privilege.
 
@item EACCES
Search permission is denied for a component of the path prefix.
 
@item EEXIST
The file specified by the @code{file} argument does not exist
 
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.
 
@item ENOENT
A component of @code{cfgpath} does not exist.
 
@item ENOTDIR
A component of the @code{file} path prefix is not a directory.
 
@item EBUSY
The configuration space defined by @code{file} is already mounted.
 
@item EINVAL
The notification argument specifies an invalid log facility.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{cfg_mount()} function maps a configuration space defined
by the file identified by the the @code{file} argument. The
distinguished node of the mapped configuration space is
mounted in the active space at the point identified by the
@code{cfgpath} configuration pathname.
 
The @code{notification} argument specifies how changes to the
mapped configuration space are communicated to the application.
If the @code{notification} argument is NULL, no notification will be
be performed for the mapped configuration space. If the Event
Logging option is defined, the notification argument defines the
facility to which changes in the mapped configuration space are
logged. Otherwise, the @code{notification} argument specifies
an implementation defined method of notifying the application
of changes to the mapped configuration space.
 
@subheading NOTES:
 
The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.
 
@page
@subsection cfg_unmount - Unmount a Configuration Space
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <cfg.h>
 
int cfg_unmount(
const char *cfgpath
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_umount()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item EPERM
The caller does not have the appropriate privileges.
 
@item EACCES
Search permission is denied for a component of the path prefix.
 
@item ENOENT
A component of @code{cfgpath} does not exist.
 
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.
 
@item EINVAL
The requested node is not the distinguished node of a mounted
configuration space.
 
@item EBUSY
One or more processes has an open configuration traversal
stream for the configuration space whose distinguished node is
referenced by the cfgpath argument.
 
@item ELOOP
A node appears more than once in the path specified by the
@code{cfgpath} argument
 
@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument
 
@end table
 
@subheading DESCRIPTION:
 
The @code{cfg_umount()} function unmaps the configuration space whose
distinguished node is mapped in the active space at the location defined
by @code{cfgpath} configuration pathname. All system resources
allocated for this configuration space should be deallocated.
 
@subheading NOTES:
 
The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.
 
@page
@subsection cfg_mknod - Create a Configuration Node
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <cfg.h>
 
int cfg_mknod(
const char *cfgpath,
mode_t mode,
cfg_type_t type
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_mknod()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.
 
@item ENOENT
A component of the path prefix does not exist.
 
@item EACCES
Search permission is denied for a component of the path prefix.
 
 
@item EPERM
The calling process does not have the appropriate privilege.
 
@item EEXIST
The named node exists.
 
@item EINVAL
The value of @code{mode} is invalid.
 
@item EINVAL
The value of @code{type} is invalid.
 
@item ELOOP
A node appears more than once in the path specified by the
@code{cfg_path} argument
 
@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the @code{cfgpath} argument.
 
@item EROFS
The named @code{node} resides on a read-only configuration space.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{cfg_mknod()} function creates a new node in the configuration
space which contains the pathname prefix of @code{cfgpath}. The node
name is defined by the pathname suffix of @code{cfgpath}. The node
permissions are specified by the value of @code{mode}. The node type
is specified by the value of @code{type}.
 
@subheading NOTES:
 
The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.
 
@page
@subsection cfg_get - Get Configuration Node Value
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <cfg.h>
 
int cfg_get(
const char *cfgpath
cfg_value_t *value
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_get()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.
 
@item ENOENT
A component of @code{cfgpath} does not exist.
 
@item EACCES
Search permission is denied for a component of the path prefix.
 
@item EPERM
The calling process does not have the appropriate privileges.
 
@item ELOOP
A node appears more than once in the path specified by the
@code{cfgpath} argument
 
@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the @code{cfgpath} argument.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{cfg_get()} function stores the value attribute of the
configuration node identified by @code{cfgpath}, into the buffer
described by the @code{value} pointer.
 
@subheading NOTES:
 
The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.
 
@page
@subsection cfg_set - Set Configuration Node Value
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <cfg.h>
 
int cfg_set(
const char *cfgpath
cfg_value_t *value
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_set()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.
 
@item ENOENT
A component of @code{cfgpath} does not exist
 
@item EACCES
Search permission is denied for a component of the path prefix.
 
@item EPERM
The calling process does not have the appropriate privilege.
 
@item ELOOP
A node appears more than once in the path specified by the
@code{cfgpath} argument.
 
@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{cfg_set()} function stores the value specified by the
@code{value} argument in the configuration node defined by the
@code{cfgpath} argument.
 
@subheading NOTES:
 
The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.
 
@page
@subsection cfg_link - Create a Configuration Link
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <cfg.h>
 
int cfg_link(
const char *src
const char *dest
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_link()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters while
@code{_POSIX_NO_TRUNC} is in effect.
 
@item ENOENT
A component of either path prefix does not exist.
 
@item EACCES
A component of either path prefix denies search permission.
 
@item EACCES
The requested link requires writing in a node with a mode that
denies write permission.
 
@item ENOENT
The node named by @code{src} does not exist.
 
@item EEXIST
The node named by @code{dest} does exist.
 
@item EPERM
The calling process does not have the appropriate privilege to
modify the node indicated by the @code{src} argument.
 
@item EXDEV
The link named by @code{dest} and the node named by @code{src} are from different
configuration spaces.
 
@item ENOSPC
The node in which the entry for the new link is being placed
cannot be extended because there is no space left on the
configuration space containing the node.
 
@item EIO
An I/O error occurred while reading from or writing to the
configuration space to make the link entry.
 
@item EROFS
The requested link requires writing in a node on a read-only
configuration space.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{src} and @code{dest} arguments point to pathnames which
name existing nodes. The @code{cfg_link()} function atomically creates
a link between specified nodes, and increment by one the link count
of the node specified by the @code{src} argument.
 
If the @code{cfg_link()} function fails, no link is created, and the
link count of the node remains unchanged by this function call.
 
 
@subheading NOTES:
 
The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.
 
@page
@subsection cfg_unlink - Remove a Configuration Link
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <cfg.h>
 
int cfg_unlink(
const char *cfgpath
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_unlink()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item ENAMETOOLONG
A component of a pathname exceeded @code{NAME_MAX} characters,
or an entire path name exceed @code{PATH_MAX} characters.
 
@item EACCES
Search permission is denied on the node containing the link to
be removed.
 
@item EACCES
Write permission is denied on the node containing the link to
be removed.
 
@item ENOENT
A component of @code{cfgpath} does not exist.
 
@item EPERM
The calling process does not have the appropriate privilege to
modify the node indicated by the path prefix of the @code{cfgpath}
argument.
 
@item EBUSY
The node to be unlinked is the distinguished node of a mounted
configuration space.
 
@item EIO
An I/O error occurred while deleting the link entry or deallocating
the node.
 
@item EROFS
The named node resides in a read-only configuration space.
 
@item ELOOP
A node appears more than once in the path specified by the
@code{cfgpath} argument.
 
@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{cfg_unlink()} function removes the link between the node
specified by the @code{cfgpath} path prefix and the parent node
specified by @code{cfgpath}, and decrements the link count
of the @code{cfgpath} node.
 
When the link count of the node becomes zero, the space occupied
by the node is freed and the node is no longer be accessible.
 
@subheading NOTES:
 
The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.
 
@page
@subsection cfg_open - Open a Configuration Space
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <cfg.h>
 
int cfg_open(
const char *pathnames[],
int options,
int (*compar)(const CFGENT **f1, const CFGENT **f2),
CFG **cfgstream
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_open()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item EACCES
Search permission is denied for any component of a pathname.
 
@item ELOOP
A loop exists in symbolic links encountered during resolution
of a pathname.
 
@item ENAMETOOLONG
The length of a pathname exceeds @code{PATH_MAX}, or a pathname
component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC}
 
@item ENOENT
The pathname argument is an empty string or the named node
does not exist.
 
@item EINVAL
Either both or neither of @code{CFG_LOGICAL} and @code{CFG_PHYSICAL} are
specified by the @code{options} argument
 
@item ENOMEM
Not enough memory is available to create the necessary structures.
 
@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the @code{pathnames} argument.
 
@item ENAMETOOLONG
As a result of encountering a symbolic link in resolution of the
pathname specified by the @code{pathnames} argument, the length of
the substituted pathname string exceeded @code{PATH_MAX}.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{cfg_open()} function opens a configuration traversal stream
rooted in the configuration nodes name by the @code{pathnames} argument.
It stores a pointer to a CFG object that represents that stream at
the location identified the @code{cfgstream} pointer. The @code{pathnames}
argument is an array of character pointers to NULL-terminated strings.
The last member of this array is a NULL pointer.
 
The value of @code{options} is the bitwise inclusive OR of values from the
following lists. Applications supply exactly one of the first two values
below in @code{options}.
 
@table @b
 
@item CFG_LOGICAL
When symbolic links referencing existing nodes are
encountered during the traversal, the @code{cfg_info}
field of the returned CFGENT structure describes the
target node pointed to by the link instead of the
link itself, unless the target node does not exist.
If the target node has children, the pre-order return,
followed by the return of structures referencing all of
its descendants, followed by a post-order return, is done.
@item CFG_PHYSICAL
When symbolic links are encountered during the traversal,
the @code{cfg_info} field is used to describe the symbolic
link.
 
@end table
 
Any combination of the remaining flags can be specified in the value of
@code{options}
 
@table @b
 
@item CFG_COMFOLLOW
When symbolic links referencing existing nodes are
specified in the @code{pathnames} argument, the
@code{cfg_info} field of the returned CFGENT structure
describes the target node pointed to by the link
instead of the link itself, unless the target node does
not exist. If the target node has children, the
pre-order return, followed by the return of structures
referencing all its descendants, followed by a post-order
return, is done.
 
@item CFG_XDEV
The configuration space functions do not return a
CFGENT structure for any node in a different configuration
space than the configuration space of the nodes identified
by the CFGENT structures for the @code{pathnames} argument.
 
@end table
 
The @code{cfg_open()} argument @code{compar} is either a NULL or point
to a function that is called with two pointers to pointers to CFGENT
structures that returns less than, equal to , or greater than zero if
the node referenced by the first argument is considered to be respectively
less than, equal to, or greater than the node referenced by the second.
The CFGENT structure fields provided to the comparison routine is as
described with the exception that the contents of the @code{cfg_path} and
@code{cfg_pathlen} fields are unspecified.
 
This comparison routine is used to determine the order in which nodes in
directories encountered during the traversal are returned, and the order
of traversal when more than one node is specified in the @code{pathnames}
argument to @code{cfg_open()}. If a comparison routine is specified, the
order of traversal is from the least to the greatest. If the @code{compar}
argument is NULL, the order of traversal shall is listed in the
@code{pathnames} argument.
 
@subheading NOTES:
 
The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.
 
@page
@subsection cfg_read - Read a Configuration Space
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <cfg.h>
 
int cfg_read(
CFG *cfgp,
CFGENT **node
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_read()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item EACCES
Search permission is denied for any component of a pathname.
 
@item EBADF
The @code{cfgp} argument does not refer to an open configuration
space.
 
@item ELOOP
A loop exists in symbolic links encountered during resolution
of a pathname.
 
@item ENOENT
A named @code{node} does not exist.
 
@item ENOMEM
Not enough memory is available to create the necessary structures.
 
@item ELOOP
More than @code{SYMLOOP_MAX} symbolic links were encountered during
resolution of the cfgpath argument.
 
@item ENAMETOOLONG
As a result of encountering a symbolic link in resolution of the
pathname specified by the pathnames argument, the length of the
substituted pathname string exceeded @code{PATH_MATH}.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{cfg_read()} function returns a pointer to a CFGENT structure
representing a node in the configuration space to which @code{cfgp}
refers. The returned pointer is stored at the location indicated
by the @code{node} argument.
 
The child nodes of each node in the configuration tree is returned
by @code{cfg_read()}. If a comparison routine was specified to the
@code{cfg_open()} function, the order of return of the child nodes is
as specified by the @code{compar} routine, from least to greatest.
Otherwise, the order of return is unspecified.
 
Structures referencing nodes with children is returned by the
function @code{cfg_read()} at least twice [unless the application
specifies otherwise with @code{cfg_mark()}]-once immediately before
the structures representing their descendants, are returned
(pre-order), and once immediately after structures representing all
of their descendants, if any, are returned (post-order). The
CFGENT structure returned in post-order (with the exception of the
@code{cfg_info} field) is identical to that returned in pre-order.
Structures referencing nodes of other types is returned at least
once.
 
The fields of the CFGENT structure contains the following
information:
 
@table @b
 
@item cfg_parent
A pointer to the structure returned by the
@code{cfg_read()} function for the node that contains
the entry for the current node. A @code{cfg_parent}
structure is provided for the node(s) specified by
the @code{pathnames} argument to the @code{cfg_open()}
function, but the contents of other than its
@code{cfg_number}, @code{cfg_pointer}, @code{cfg_parent},
and @code{cfg_parent}, and @code{cfg_level} fields are
unspecified. Its @code{cfg_link} field is unspecified.
 
@item cfg_link
Upon return from the @code{cfg_children()} function, the
@code{cfg_link} field points to the next CFGENT structure
in a NULL-terminated linked list of CFGENT structures.
Otherwise, the content of the @code{cfg_link} field is
unspecified.
 
@item cfg_cycle
If the structure being returned by @code{cfg_read()}
represents a node that appears in the @code{cfg_parent}
linked list tree, the @code{cfg_cycle} field shall point
to the structure representing that entry from the
@code{cfg_parent} linked list. Otherwise the content of
the @code{cfg_cycle} field is unspecified.
 
@item cfg_number
The @code{cfg_number} field is provided for use by the
application program. It is initialized to zero for
each new node returned by the @code{cfg_read()} function,
but is not further modified by the configuration space
routines.
 
@item cfg_pointer
The @code{cfg_pointer} field is provided for use by the
application program. It is initialized to NULL for
each new node returned by the @code{cfg_read()} function,
but is not further modified by the configuration
space routines.
 
@item cfg_path
A pathname for the node including and relative to the
argument supplied to the @code{cfg_open()} routine for this
configuration space. This pathname may be longer than
@code{PATH_MAX} bytes. This pathname is NULL-terminated.
 
@item cfg_name
The nodename of the node.
 
@item cfg_pathlen
The length of the string pointed at by the @code{cfg_path}
field when returned by @code{cfg_read()}.
 
@item cfg_namelen
The length of the string pointed at by the @code{cfg_name}
field.
 
@item cfg_level
The depth of the current entry in the configuration space.
The @code{cfg_level} field of the @code{cfg_parent}
structure for each of the node(s) specified in the
@code{pathnames} argument to the @code{cfg_open()} function
is set to 0, and this number is incremented for each
node level descendant.
 
@item cfg_info
This field contains one of the values listed below. If
an object can have more than one info value, the first
appropriate value listed below is returned.
 
@table @b
 
@item CFG_D
The structure represents a node with children in
pre-order.
 
@item CFG_DC
The structure represents a node that is a parent
of the node most recently returned by @code{cfg_read()}.
The @code{cfg_cycle} field references the structure
previously returned by @code{cfg_read} that is the
same as the returned structure.
 
@item CFG_DEFAULT
The structure represents a node that is not
represented by one of the other node types
 
@item CFG_DNR
The structure represents a node, not of type symlink,
that is unreadable. The variable @code{cfg_errno}
is set to the appropriate value.
 
@item CFG_DP
The structure represents a node with children in
post-order. This value occurs only if CFG_D
has previously been returned for this entry.
 
@item CFG_ERR
The structure represents a node for which an error has
occurred. The variable @code{cfg_errno} is set to the
appropriate value.
 
@item CFG_F
The structure represents a node without children.
 
@item CFG_SL
The structure represents a node of type symbolic link.
 
@item CFG_SLNONET
The structure represents a node of type symbolic link
with a target node for which node characteristic
information cannot be obtained.
 
@end table
 
@end table
 
Structures returned by @code{cfg_read()} with a @code{cfg_info} field equal
to CFG_D is accessible until a subsequent call, on the same
configuration traversal stream, to @code{cfg_close()}, or to @code{cfg_read()}
after they have been returned by the @code{cfg_read} function in
post-order. Structures returned by @code{cfg_read()} with an
@code{cfg_info} field not equal to CFG_D is accessible until a subsequent
call, on the same configuration traversal stream, to @code{cfg_close()}
or @code{cfg_read()}.
 
The content of the @code{cfg_path} field is specified only for the
structure most recently returned by @code{cfg_read()}.
 
The specified fields in structures in the list representing nodes for
which structures have previously been returned by @code{cfg_children()},
is identical to those returned by @code{cfg_children()}, except that
the contents of the @code{cfg_path} and @code{cfg_pathlen} fields are
unspecified.
@subheading NOTES:
 
The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.
 
@page
@subsection cfg_children - Get Node Entries
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <cfg.h>
 
int cfg_children(
CFG *cfgp,
int options,
CFGENT **children
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_children()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item EACCES
Search permission is denied for any component of a pathname
 
@item EBADF
The @code{cfgp} argument does not refer to an open configuration space.
 
@item ELOOP
A loop exists in symbolic links encountered during resolution of
a pathname.
 
@item ENAMETOOLONG
The length of a pathname exceeds @code{PATH_MAX}, or a pathname
component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is
in effect.
 
@item EINVAL
The specified value of the @code{options} argument is invalid.
 
@item ENOENT
The named node does not exist.
 
@item ENOMEM
Not enough memory is available to create the necessary structures.
 
@end table
 
@subheading DESCRIPTION:
 
The first @code{cfg_children()} call after a @code{cfg_read()} returns
information about the first node without children under the node
returned by @code{cfg_read()}. Subsequent calls to @code{cfg_children()}
without the intervening @code{cfg_read()} shall return information
about the remaining nodes without children under that same node.
 
If @code{cfg_read()} has not yet been called for the configuration
traversal stream represented by @code{cfgp}, @code{cfg_children()}
returns a pointer to the first entry in a list of the nodes
represented by the @code{pathnames} argument to @code{cfg_open()}.
 
In either case, the list is NULL-terminated, ordered by the
user-specified comparison function, if any, and linked through the
@code{cfg_link} field.
 
@subheading NOTES:
 
The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.
 
@page
@subsection cfg_mark - Set Configuration Space Options
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <cfg.h>
 
int cfg_mark(
CFG *cfgp,
CFGENT *f,
int options
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_mark()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item EINVAL
The specified combination of the @code{cfgp} and @code{f} arguments is not
supported by the implementation.
 
@item EINVAL
The specified value of the @code{options} argument is invalid.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{cfg_mark()} function modifies the subsequent behavior of
the @code{cfg} functions with regard to the node referenced by the structure
pointed to by the argument @code{f} or the configuration space referenced
by the structure pointed to by the argument @code{cfgp}.
 
Exactly one of the @code{f} argument and the @code{cfgp} argument is NULL.
 
The value of the @code{options} argument is exactly one of the flags
specified in the following list:
 
@table @b
 
@item CFG_AGAIN
If the @code{cfgp} argument is non-NULL, or the @code{f}
argument is NULL, or the structure referenced by @code{f}
is not the one most recently returned by @code{cfg_read()},
@code{cfg_mark()} returns an error. Otherwise, the next
call to the @code{cfg_read()} function returns the structure
referenced by @code{f} with the @code{cfg_info} field
reinitialized. Subsequent behavior of the @code{cfg}
functions are based on the reinitialized value of
@code{cfg_info}.
 
@item CFG_SKIP
If the @code{cfgp} argument is non-NULL, or the @code{f}
argument is NULL, or the structure referenced by @code{f}
is not one of those specified as accessible, or the structure
referenced by @code{f} is not for a node of type pre-order
node, @code{cfg_mark()} returns an error. Otherwise, no
more structures for the node referenced by @code{f} or its
descendants are returned by the @code{cfg_read()} function.
 
@item CFG_FOLLOW
If the @code{cfgp} argument is non-NULL, or the @code{f}
argument is NULL, or the structure referenced by @code{f}
is not one of those specified as accessible, or the structure
referenced by @code{f} is not for a node of type symbolic link,
@code{cfg_mark()} returns an error. Otherwise, the next
call to the @code{cfg_read()} function returns the structure
referenced by @code{f} with the @code{cfg_info} field reset
to reflect the target of the symbolic link instead of the
symbolic link itself. If the target of the link is node with
children, the pre-order return, followed by the return of
structures referencing all of its descendants, followed by a
post-order return, shall be done.
 
@end table
 
If the target of the symbolic link does not exist, the fields
of the structure by @code{cfg_read()} shall be unmodified, except
that the @code{cfg_info} field shall be reset to @code{CFG_SLNONE}.
 
@subheading NOTES:
 
The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.
 
@page
@subsection cfg_close - Close a Configuration Space
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <cfg.h>
 
int cfg_close(
CFG *cfgp
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_close()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item EBADF
The @code{cfgp} argument does not refer to an open configuration space
traversal stream.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{cfg_close()} function closes a configuration space transversal
stream represented by the CFG structure pointed at by the @code{cfgp}
argument. All system resources allocated for this configuration space
traversal stream should be deallocated. Upon return, the value of
@code{cfgp} need not point to an accessible object of type CFG.
 
@subheading NOTES:
 
The @code{_POSIX_CFG} feature flag is defined to indicate
this service is available.
 
@page
@subsection cfg_readdir - Reads a directory
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <sys/types.h>
#include <dirent.h>
 
struct dirent *cfg_readdir(
DIR *dirp
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
@table @b
@item EBADF
Invalid file descriptor
 
@end table
 
@subheading DESCRIPTION:
 
The @code{cfg_readdir()} function returns a pointer to a structure @code{dirent}
representing the next directory entry from the directory stream pointed to
by @code{dirp}. On end-of-file, NULL is returned.
 
The @code{cfg_readdir()} function may (or may not) return entries for . or .. Your
program should tolerate reading dot and dot-dot but not require them.
 
The data pointed to be @code{cfg_readdir()} may be overwritten by another call to
@code{readdir()} for the same directory stream. It will not be overwritten by
a call for another directory.
 
@subheading NOTES:
 
If @code{ptr} is not a pointer returned by @code{malloc()}, @code{calloc()}, or
@code{realloc()} or has been deallocated with @code{free()} or @code{realloc()},
the results are not portable and are probably disastrous.
 
This function is not defined in the POSIX specification. It is an extension
provided by this implementation.
 
@page
@subsection cfg_umask - Sets a file creation mask.
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <sys/types.h>
#include <sys/stat.h>
 
mode_t cfg_umask(
mode_t cmask
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
@subheading DESCRIPTION:
 
The @code{cfg_umask()} function sets the process node creation mask to @code{cmask}.
The file creation mask is used during @code{open()}, @code{creat()}, @code{mkdir()},
@code{mkfifo()} calls to turn off permission bits in the @code{mode} argument.
Bit positions that are set in @code{cmask} are cleared in the mode of the
created file.
 
The file creation mask is inherited across @code{fork()} and @code{exec()} calls.
This makes it possible to alter the default permission bits of created files.
 
@subheading NOTES: None
 
The @code{cmask} argument should have only permission bits set. All other
bits should be zero.
 
@page
@subsection cfg_chmod - Changes file mode.
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <sys/types.h>
#include <sys/stat.h>
 
int cfg_chmod(
const char *path,
mode_t mode
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_chmod()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item EACCES
Search permission is denied for a directory in a file's path prefix
@item ENAMETOOLONG
Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
effect.
@item ENOENT
A file or directory does not exist.
@item ENOTDIR
A component of the specified pathname was not a directory when a directory
was expected.
@item EPERM
Operation is not permitted. Process does not have the appropriate priviledges
or permissions to perform the requested operations.
@item EROFS
Read-only file system.
 
@end table
 
@subheading DESCRIPTION:
 
Set the file permission bits, the set user ID bit, and the set group ID bit
for the file named by @code{path} to @code{mode}. If the effective user ID
does not match the owner of the node and the calling process does not have
the appropriate privileges, @code{cfg_chmod()} returns -1 and sets @code{errno} to
@code{EPERM}.
 
@subheading NOTES:
 
@page
@subsection cfg_chown - Changes the owner and/or group of a file.
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <sys/types.h>
#include <unistd.h>
 
int cfg_chown(
const char *path,
uid_t owner,
gid_t group
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
A successful call to @code{cfg_chown()} returns a value of zero
and an unsuccessful call returns the @code{errno}.
 
@table @b
@item EACCES
Search permission is denied for a directory in a file's path prefix
@item EINVAL
Invalid argument
@item ENAMETOOLONG
Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in
effect.
@item ENOENT
A file or directory does not exist.
@item ENOTDIR
A component of the specified pathname was not a directory when a directory
was expected.
@item EPERM
Operation is not permitted. Process does not have the appropriate priviledges
or permissions to perform the requested operations.
@item EROFS
Read-only file system.
 
@end table
 
@subheading DESCRIPTION:
 
The user ID and group ID of the file named by @code{path} are set to
@code{owner} and @code{path}, respectively.
 
For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID)
bits are cleared.
 
Some systems consider it a security violation to allow the owner of a file to
be changed, If users are billed for disk space usage, loaning a file to
another user could result in incorrect billing. The @code{cfg_chown()} function
may be restricted to privileged users for some or all files. The group ID can
still be changed to one of the supplementary group IDs.
 
@subheading NOTES:
 
This function may be restricted for some file. The @code{pathconf} function
can be used to test the _PC_CHOWN_RESTRICTED flag.
 
 
/TODO
0,0 → 1,4
 
General - check that all nodes have "none" if they don't have a note.
 
 
/cpuuse.t
0,0 → 1,142
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c cpuuse.t,v 1.3 2002/01/17 21:47:45 joel Exp
@c
 
@chapter CPU Usage Statistics
 
@section Introduction
 
The CPU usage statistics manager is an RTEMS support
component that provides a convenient way to manipulate
the CPU usage information associated with each task
The routines provided by the CPU usage statistics manager are:
 
@itemize @bullet
@item @code{CPU_usage_Dump} - Report CPU Usage Statistics
@item @code{CPU_usage_Reset} - Reset CPU Usage Statistics
@end itemize
 
@section Background
 
@section Operations
 
@section Report CPU Usage Statistics
 
@subsection Reporting Period Statistics
 
The application may dynamically report the CPU usage for every
task in the system by calling the @code{CPU_usage_Dump} routine.
This routine prints a table with the following information per task:
 
@itemize @bullet
@item task id
@item task name
@item number of clock ticks executed
@item percentage of time consumed by this task
@end itemize
 
The following is an example of the report generated:
 
@example
@group
CPU Usage by thread
ID NAME TICKS PERCENT
0x04010001 IDLE 0 0.000
0x08010002 TA1 1203 0.748
0x08010003 TA2 203 0.126
0x08010004 TA3 202 0.126
 
Ticks since last reset = 1600
 
Total Units = 1608
@end group
@end example
 
Notice that the "Total Units" is greater than the ticks per reset.
This is an artifact of the way in which RTEMS keeps track of CPU
usage. When a task is context switched into the CPU, the number
of clock ticks it has executed is incremented. While the task
is executing, this number is incremented on each clock tick.
Otherwise, if a task begins and completes execution between
successive clock ticks, there would be no way to tell that it
executed at all.
 
Another thing to keep in mind when looking at idle time, is that
many systems -- especially during debug -- have a task providing
some type of debug interface. It is usually fine to think of the
total idle time as being the sum of the IDLE task and a debug
task that will not be included in a production build of an application.
 
@section Reset CPU Usage Statistics
 
Invoking the @code{CPU_usage_Reset} routine resets the CPU usage
statistics for all tasks in the system.
 
@section Directives
 
This section details the CPU usage statistics manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
 
@page
@subsection CPU_usage_Dump - Report CPU Usage Statistics
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
void CPU_usage_Dump( void );
@end example
@end ifset
 
@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset
 
@subheading STATUS CODES: NONE
 
@subheading DESCRIPTION:
 
This routine prints out a table detailing the CPU usage statistics for
all tasks in the system.
 
@subheading NOTES:
 
NONE
 
@page
@subsection CPU_usage_Reset - Reset CPU Usage Statistics
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
void CPU_usage_Reset( void );
@end example
@end ifset
 
@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset
 
@subheading STATUS CODES: NONE
 
@subheading DESCRIPTION:
 
This routine re-initializes the CPU usage statistics for all tasks
in the system to their initial state. The initial state is that
a task has not executed and thus has consumed no CPU time.
default state which is when zero period executions have occurred.
 
@subheading NOTES:
 
NONE
/dumpcontrol.t
0,0 → 1,98
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c dumpcontrol.t,v 1.13 2002/01/17 21:47:45 joel Exp
@c
 
@chapter Process Dump Control Manager
 
@section Introduction
 
The process dump control manager provides a portable
interface for changing the path to which a process dump
is written. The capabilities in this manager were defined in
the POSIX 1003.1h/D3 proposed standard titled @b{Services for Reliable,
Available, and Serviceable Systems}.
 
The directives provided by the process dump control manager are:
 
@itemize @bullet
@item @code{dump_setpath} - Dump File Control
@end itemize
 
@section Background
 
There is currently no text in this section.
 
@section Operations
 
There is currently no text in this section.
 
@section Directives
 
This section details the process dump control manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
 
@page
@subsection dump_setpath - Dump File Control
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
#include <dump.h>
 
int dump_setpath(
const char *path
);
@end example
@end ifset
 
@ifset is-Ada
@end ifset
 
@subheading STATUS CODES:
 
@table @b
@item EACESS
Search permission is denied for a component of the path prefix,
or write permission is denied on the directory containing the
file.
 
@item ENAMETOOLONG
The length of the argument exceeds @code{PATH_MAX} or a pathname
component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC}
is in effect.
 
@item ENOENT
The path argument points to an empty string.
 
@item ENOTDIR
A component of the path prefix is not a directory.
 
@item EROFS
The directory entry specified resides on a read-only file system.
 
@end table
 
@subheading DESCRIPTION:
 
The @code{dump_setpath()} function defines the pathname where process
dumps are written. The pathname pointed to by @code{path} defines
where a process dump file is written if the calling process
terminates with a dump file. The @code{path} argument does not
name a directory.
 
If the @code{path} argument is NULL, the system does not write a
process dump file if the calling process terminates with a dump
file. If the @code{dump_setpath} function fails, the pathname for
writing process dumps does not change.
 
@subheading NOTES:
 
The @code{_POSIX_DUMP} feature flag is defined to indicate
this service is available.
/Makefile.am
0,0 → 1,76
#
# COPYRIGHT (c) 1988-2002.
# On-Line Applications Research Corporation (OAR).
# All rights reserved.
#
# Makefile.am,v 1.6 2002/03/28 00:53:05 joel Exp
#
 
 
PROJECT = new_chapters
EDITION = 1
 
include $(top_srcdir)/project.am
include $(top_srcdir)/main.am
 
GENERATED_FILES = adminiface.texi confspace.texi dumpcontrol.texi \
eventlog.texi stackchk.texi rtmonuse.texi cpuuse.texi error.texi \
monitor.texi
 
COMMON_FILES = $(top_srcdir)/common/setup.texi \
$(top_srcdir)/common/cpright.texi
 
FILES =
 
info_TEXINFOS = new_chapters.texi
new_chapters_TEXINFOS = $(FILES) $(COMMON_FILES) $(GENERATED_FILES)
 
$(srcdir)/eventlog.texi: eventlog.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/dumpcontrol.texi: dumpcontrol.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/confspace.texi: confspace.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/adminiface.texi: adminiface.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/stackchk.texi: stackchk.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/rtmonuse.texi: rtmonuse.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/cpuuse.texi: cpuuse.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/error.texi: error.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
$(srcdir)/monitor.texi: monitor.t
$(BMENU2) -p "" \
-u "Top" \
-n "" < $< > $@
 
noinst_SCRIPTS = gen_section
 
EXTRA_DIST = adminiface.t base.t confspace.t cpuuse.t dumpcontrol.t error.t \
eventlog.t monitor.t rtmonuse.t stackchk.t STATUS TODO $(noinst_SCRIPTS)
/base.t
0,0 → 1,62
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c base.t,v 1.5 2002/01/17 21:47:45 joel Exp
@c
 
@chapter Mutex Manager
 
@section Introduction
 
The mutex manager ...
 
The directives provided by the mutex manager are:
 
@itemize @bullet
@item @code{sigaddset} -
@item @code{sigdelset} -
@item @code{sigfillset} -
@item @code{sigismember} -
@item @code{sigemptyset} -
@item @code{sigaction} -
@item @code{pthread_kill} -
@item @code{pthread_sigmask} -
@item @code{kill} -
@item @code{sigwait} -
@end itemize
 
@section Background
 
There is currently no text in this section.
 
@section Operations
 
There is currently no text in this section.
 
@section Directives
 
This section details the mutex manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.
 
@page
@subsection sigaddset
 
@subheading CALLING SEQUENCE:
 
@example
int sigaddset(
sigset_t *set,
int signo
);
@end example
 
@subheading STATUS CODES:
 
@subheading DESCRIPTION:
 
@subheading NOTES:
 
/rtmonuse.t
0,0 → 1,294
@c
@c COPYRIGHT (c) 1988-2002.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c rtmonuse.t,v 1.3 2002/01/17 21:47:45 joel Exp
@c
 
@chapter Rate Monotonic Period Statistics
 
@section Introduction
 
The rate monotonic period statistics manager is an RTEMS support
component that maintains statistics on the execution characteristics
of each task using a period. The routines provided by the rate
monotonic period statistics manager are:
 
@itemize @bullet
@item @code{Period_usage_Initialize} - Initialize the Period Statistics
@item @code{Period_usage_Reset} - Reset the Period Statistics
@item @code{Period_usage_Update} - Update the Statistics for this Period
@item @code{Period_usage_Dump} - Report Period Statistics Usage
@end itemize
 
@section Background
 
@section Period Statistics
 
This manager maintains a set of statistics on each period. The following
is a list of the information kept:
 
@itemize @bullet
@item @code{id}
is the id of the period.
 
@item @code{count}
is the total number of periods executed.
 
@item @code{missed_count}
is the number of periods that were missed.
 
@item @code{min_cpu_time}
is the minimum amount of CPU execution time consumed
on any execution of the periodic loop.
 
@item @code{max_cpu_time}
is the maximum amount of CPU execution time consumed
on any execution of the periodic loop.
 
@item @code{total_cpu_time}
is the total amount of CPU execution time consumed
by executions of the periodic loop.
 
@item @code{min_wall_time}
is the minimum amount of wall time that passed
on any execution of the periodic loop.
 
@item @code{max_wall_time}
is the maximum amount of wall time that passed
on any execution of the periodic loop.
 
@item @code{total_wall_time}
is the total amount of wall time that passed
during executions of the periodic loop.
 
@end itemize
 
The above information is inexpensive to maintain and can provide very
useful insights into the execution characteristics of a periodic
task loop.
 
@subsection Analysis of the Reported Information
 
The period statistics reported must be analyzed by the user in terms
of what the applications is. For example, in an application where
priorities are assigned by the Rate Monotonic Algorithm, it would
be very undesirable for high priority (i.e. frequency) tasks to
miss their period. Similarly, in nearly any application, if a
task were supposed to execute its periodic loop every 10 milliseconds
and it averaged 11 milliseconds, then application requirements
are not being met.
 
The information reported can be used to determine the "hot spots"
in the application. Given a period's id, the user can determine
the length of that period. From that information and the CPU usage,
the user can calculate the percentage of CPU time consumed by that
periodic task. For example, a task executing for 20 milliseconds
every 200 milliseconds is consuming 10 percent of the processor's
execution time. This is usually enough to make it a good candidate
for optimization.
 
However, execution time alone is not enough to gauge the value of
optimizing a particular task. It is more important to optimize
a task executing 2 millisecond every 10 milliseconds (20 percent
of the CPU) than one executing 10 milliseconds every 100 (10 percent
of the CPU). As a general rule of thumb, the higher frequency at
which a task executes, the more important it is to optimize that
task.
 
@section Operations
 
@subsection Initializing the Period Statistics
 
The period statistics manager must be explicitly initialized before
any calls to this manager. This is done by calling the
@code{Period_usage_Initialize} service.
 
@subsection Updating Period Statistics
 
It is the responsibility of each period task loop to update the statistics
on each execution of its loop. The following is an example of a
simple periodic task that uses the period statistics manager:
 
@example
@group
rtems_task Periodic_task()
@{
rtems_name name;
rtems_id period;
rtems_status_code status;
 
name = rtems_build_name( 'P', 'E', 'R', 'D' );
 
(void) rate_monotonic_create( name, &period );
 
while ( 1 ) @{
if ( rate_monotonic_period( period, 100 ) == TIMEOUT )
break;
 
/* Perform some periodic actions */
 
/* Report statistics */
Period_usage_Update( period_id );
@}
 
/* missed period so delete period and SELF */
 
(void) rate_monotonic_delete( period );
(void) task_delete( SELF );
@}
@end group
@end example
 
@subsection Reporting Period Statistics
 
The application may dynamically report the period usage for every
period in the system by calling the @code{Period_usage_Dump} routine.
This routine prints a table with the following information per period:
 
@itemize @bullet
@item period id
@item id of the task that owns the period
@item number of periods executed
@item number of periods missed
@item minimum/maximum/average cpu use per period
@item minimum/maximum/average wall time per period
@end itemize
 
The following is an example of the report generated:
 
@example
@group
Period information by period
ID OWNER PERIODS MISSED CPU TIME WALL TIME
0x28010001 TA1 502 0 0/1/ 1.00 0/0/0.00
0x28010002 TA2 502 0 0/1/ 1.00 0/0/0.00
0x28010003 TA3 502 0 0/1/ 1.00 0/0/0.00
0x28010004 TA4 502 0 0/1/ 1.00 0/0/0.00
0x28010005 TA5 10 0 0/1/ 0.90 0/0/0.00
@end group
@end example
 
@section Routines
 
This section details the rate monotonic period statistics manager's routines.
A subsection is dedicated to each of this manager's routines
and describes the calling sequence, related constants, usage,
and status codes.
 
@page
@subsection Period_usage_Initialize - Initialize the Period Statistics
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
void Period_usage_Initialize( void );
@end example
@end ifset
 
@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset
 
@subheading STATUS CODES: NONE
 
@subheading DESCRIPTION:
 
This routine allocates the table used to contain the period statistics.
This table is then initialized by calling the @code{Period_usage_Reset}
service.
 
@subheading NOTES:
 
This routine invokes the @code{malloc} routine to dynamically allocate
memory.
 
@page
@subsection Period_usage_Reset - Reset the Period Statistics
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
void Period_usage_Reset( void );
@end example
@end ifset
 
@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset
 
@subheading STATUS CODES: NONE
 
@subheading DESCRIPTION:
 
This routine re-initializes the period statistics table to its
default state which is when zero period executions have occurred.
 
@subheading NOTES:
 
NONE
 
@page
@subsection Period_usage_Update - Update the Statistics for this Period
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
void Period_usage_Update(
rtems_id id
);
@end example
@end ifset
 
@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset
 
@subheading STATUS CODES: NONE
 
@subheading DESCRIPTION:
 
The @code{Period_usage_Update} routine must be invoked at the "bottom"
of each periodic loop iteration to update the statistics.
 
@subheading NOTES:
 
NONE
 
@page
@subsection Period_usage_Dump - Report Period Statistics Usage
 
@subheading CALLING SEQUENCE:
 
@ifset is-C
@example
void Period_usage_Dump( void );
@end example
@end ifset
 
@ifset is-Ada
@example
An Ada interface is not currently available.
@end example
@end ifset
 
@subheading STATUS CODES: NONE
 
@subheading DESCRIPTION:
 
This routine prints out a table detailing the period statistics for
all periods in the system.
 
@subheading NOTES:
 
NONE
/.
. Property changes : Added: svn:ignore ## -0,0 +1,31 ## +Makefile +Makefile.in +adminiface.texi +confspace.texi +cpuuse.texi +dumpcontrol.texi +error.texi +eventlog.texi +index.html +mdate-sh +monitor.texi +new_chapters +new_chapters*.html +new_chapters-? +new_chapters-?? +new_chapters.aux +new_chapters.cp +new_chapters.dvi +new_chapters.fn +new_chapters.ky +new_chapters.log +new_chapters.pdf +new_chapters.pg +new_chapters.ps +new_chapters.toc +new_chapters.tp +new_chapters.vr +rtmonuse.texi +stackchk.texi +rtems_header.html +rtems_footer.html

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.