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