about summary refs log tree commit diff
path: root/manual/stdio.texi
diff options
context:
space:
mode:
authorUlrich Drepper <drepper@redhat.com>1997-05-24 02:30:09 +0000
committerUlrich Drepper <drepper@redhat.com>1997-05-24 02:30:09 +0000
commit0501d6036744d44cad6d5a6eda8090ddfbe604c4 (patch)
treeac5de4474ab5209dd348b7442dac99d4547851af /manual/stdio.texi
parentbfbc57545a197afff72572c3a6f0563023d553a5 (diff)
downloadglibc-0501d6036744d44cad6d5a6eda8090ddfbe604c4.tar.gz
glibc-0501d6036744d44cad6d5a6eda8090ddfbe604c4.tar.xz
glibc-0501d6036744d44cad6d5a6eda8090ddfbe604c4.zip
Update.
1997-05-24 03:51  Ulrich Drepper  <drepper@cygnus.com>

	* stdlib/Makefile (routines): Add strtol_l, strtoul_l, strtoll_l,
	strtoull_l, strtof_l, strtod_l, and strtold_l.
	* stdlib/stdlib.h: Add prototypes for new functions.
	* stdlib/strtod.c: Change for compiling as strtoX_l.
	* stdlib/strtol.c: Likewise.
	* stdlib/strtof.c: Likewise.
	* stdlib/strtold.c: Likewise.
	* stdlib/strtod_l.c: New file.
	* stdlib/strtof_l.c: New file.
	* stdlib/strtold_l.c: New file.
	* stdlib/strtol_l.c: New file.
	* stdlib/strtoul_l.c: New file.
	* stdlib/strtoll_l.c: New file.
	* stdlib/strtoull_l.c: New file.
	* string/Makefile (routines): Add strcasecmp_l and strncase_l.
	* string/string.h: Add prototypes for new functions.
	* sysdeps/generic/strcasecmp.c: Change for compiling as strcasecmp_l.
	* sysdeps/generic/strncase.c: Change for compiling as strncasecmp_l.
	* sysdeps/generic/strcasecmp_l.c: New file.
	* sysdeps/generic/strncase_l.c: New file.
	* wcsmbs/Makefile (routines): Add wcstol_l, wcstoul_l, wcstoll_l,
	wcstoull_l, wcstod_l, wcstold_l, wcstof_l, wcscasecmp_l, and
	wcsncase_l.
	* wcsmbs/wchar.h: Add prototypes for new functions.
	* wcsmbs/wcscasecmp.c: Change for compiling as wcscasecmp_l.
	* wcsmbs/wcsncase.c: Change for compiling as wcsncasecmp_l.
	* wcsmbs/wcscasecmp_l.c: New file.
	* wcsmbs/wcsncase_l.c: New file.
	* wcsmbs/wcstof.c: Change for compiling as wcstof_l.c
	* wcsmbs/wcstold.c: Change for compiling as wcstold_l.c
	* wcsmcs/wcstod_l.c: New file.
	* wcsmcs/wcstof_l.c: New file.
	* wcsmcs/wcstold_l.c: New file.
	* wcsmcs/wcstol_l.c: New file.
	* wcsmcs/wcstoul_l.c: New file.
	* wcsmcs/wcstoll_l.c: New file.
	* wcsmcs/wcstoull_l.c: New file.

	* Makeconfig (binfmt-subdir): New variable.  Set to `elf' if
	$(elf) is defined.  More to come later when other binary formats
	are supported.
	* Makefile (subdirs): Remove elf.  Add $(binfmt-subdir).
	Suggested by Philip Blundell.

	* stdlib/Makefile (headers): Add fmtmsg.h.
	(routines): Add fmtmsg.
	* stdlib/fmtmsg.c: New file.
	* stdlib/fmtmsg.h: New file.
	* manual/stdio.texi: Add description of fmtmsg and addseverity.
	* manual/examples/fmtmsgexpl.c: Example program for fmtmsg
	documentation.

1997-05-23 15:26  Philip Blundell  <pjb27@cam.ac.uk>

	* resolv/res_query.c (res_querydomain): Avoid potential buffer
	overrun.  Reported by Dan A. Dickey <ddickey@transition.com>.

1997-05-22 18:36  Thomas Bushnell, n/BSG  <thomas@gnu.ai.mit.edu>

	* elf/dl-support.c (_dl_sysdep_open_zero_fill,
	_dl_sysdep_read_whole_file): Moved functions to ...
	* elf/dl-misc.c: This new file.
	* sysdeps/generic/dl-sysdepio.c: Delete file and move functions...
	* elf/dl-misc.c: ... here.
	* sysdeps/generic/dl-sysdep.c (_dl_sysdep_open_zero_fill,
	_dl_sysdep_read_whole_file): Delete functions; they now come from
	elf/dl-misc.c (dl-support.c had contained identical versions).
	* sysdeps/mach/hurd/dl-sysdepio.c: Delete file; move functions...
	* sysdeps/mach/hurd/dl-sysdep.c: ... here, but mark them weak so
	that the regular ones in dl-misc work once we've initialized.
	* elf/Makefile (dl-routines): Remove dl-sysdepio.c.  Add dl-misc.c.

1997-05-22 21:55  Philip Blundell  <pjb27@cam.ac.uk>

	* inet/Makefile (headers): Add netinet/inbits.h.
	* inet/netinet/in.h: New file.
	* sysdeps/generic/netinet/inbits.h: Likewise.
	* sysdeps/unix/sysv/linux/netinet/inbits.h: Likewise.
	* sysdeps/generic/netinet/ip6.h: Move to...
	* inet/netinet/ip6.h: ... here.
	* sysdeps/generic/netinet/icmp6.h: Move to...
	* inet/netinet/icmp6.h: ... here.
	* sysdeps/unix/sysv/linux/netinet/in.h: Remove.
	* sysdeps/generic/netinet/in.h: Remove.

1997-05-22 05:40  Richard Henderson  <rth@tamu.edu>

	* sysdeps/alpha/dl-machine.h (elf_machine_runtime_setup): If we are
	not looking at the new thread-safe .plt, don't be lazy about relocs.
	(_dl_runtime_resolve): Fix up arithmetic for new .plt layout.
	(elf_alpha_fix_plt): Insert wmb as appropriate to ensure safety.
	* elf/dynamic-link.h (ELF_DYNAMIC_RELOCATE): Let
	elf_machine_runtime_setup() decide if we can actually be lazy.
	* elf/rtld.c (_dl_start): So don't call it.
	* elf/dl-reloc.c (_dl_relocate_object): Likewise.
	* sysdeps/i386/dl-machine.h (elf_machine_runtime_setup): Return lazy.
	* sysdeps/m68k/dl-machine.h (elf_machine_runtime_setup): Likewise.
	* sysdeps/mips/dl-machine.h (elf_machine_runtime_setup): Likewise.
	* sysdeps/powerpc/dl-machine.h (elf_machine_runtime_setup): Likewise.
	* sysdeps/sparc/dl-machine.h (elf_machine_runtime_setup): Likewise.
	* sysdeps/stub/dl-machine.h (elf_machine_runtime_setup): Update
	skeleton definition.

1997-05-22 18:45  Ulrich Drepper  <drepper@cygnus.com>

	* sysdeps/i386/fpu/__math.h (logb): Remove second value placed on
	stack by fxtract.

1997-05-22 13:07  Andreas Jaeger  <aj@arthur.rhein-neckar.de>

	* sunrpc/rpcsvc/rusers.x: Provide and correct prototypes,
	add cast to (xdrproc_t) where necessary to prevent warnings.

1997-05-22 12:18  Ulrich Drepper  <drepper@cygnus.com>

	* sysdeps/unix/sysv/linux/powerpc/dl-sysdep.c: Remove I/O functions.

	* sunrpc/rpcinfo.c (get_inet_address): Use INADDR_NONE and INADDR_ANY
	* sysdeps/libm-ieee754/s_cexp.c: Fix typo: string_alias ->
	* nss/XXX-lookup.c: Add missing explanation.
Diffstat (limited to 'manual/stdio.texi')
-rw-r--r--manual/stdio.texi309
1 files changed, 309 insertions, 0 deletions
diff --git a/manual/stdio.texi b/manual/stdio.texi
index 3e73155f4a..3d6a6c1f2f 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -29,6 +29,7 @@ representing a communications channel to a file, device, or process.
 * Stream Buffering::            How to control buffering of streams.
 * Other Kinds of Streams::      Streams that do not necessarily correspond
                                  to an open file.
+* Formatted Messages::          Print strictly formatted messages.
 @end menu
 
 @node Streams
@@ -3815,3 +3816,311 @@ wait until the rest of the manual is more done and polished.
 @end ignore
 
 @c ??? This section could use an example.
+
+
+@node Formatted Messages
+@section Formatted Messages
+@cindex formatted messages
+
+On systems which are based on System V messages of programs (especially
+the system tools) are printed in a strict form using the @code{fmtmsg}
+function.  The uniformity sometimes helps the user to interpret messages
+and the strictness tests of the @code{fmtmsg} function ensures that the
+programmer follows some minimal requirements.
+
+@menu
+* Printing Formatted Messages::   The @code{fmtmsg} function.
+* Adding Severity Classes::       Add more severity classes.
+* Example::                       How to use @code{fmtmsg} and @code{addseverity}.
+@end menu
+
+
+@node Printing Formatted Messages
+@subsection Printing Formatted Messages
+
+Messages can be printed to standard error and/or to the console.  To
+select the destination the programmer can use the following to values,
+bitwise OR combined if wanted, for the @var{classification} parameter of
+@code{fmtmsg}:
+
+@vtable @code
+@item MM_PRINT
+Display the message in standard error.
+@item MM_CONSOLE
+Display the message on the system console.
+@end vtable
+
+The errorneous piece of the system can be signal by exactly one of the
+following values which also is bitwise ORed with the
+@var{classification} parameter to @code{fmtmsg}:
+
+@vtable @code
+@item MM_HARD
+The source of the condition is some hardware.
+@item MM_SOFT
+The source of the condition is some software.
+@item MM_FIRM
+The source of the condition is some firmware.
+@end vtable
+
+A third component of the @var{classification} parameter to @code{fmtmsg}
+can describe the part of the system which detects the problem.  This is
+done by using exactly one of the following values:
+
+@vtable @code
+@item MM_APPL
+The errorneous condition is detected by the application.
+@item MM_UTIL
+The errorneous condition is detected by a utility.
+@item MM_OPSYS
+The errorneous condition is detected by the operating system.
+@end vtable
+
+A last component of @var{classification} can signal the results of this
+message.  Exactly one of the following values can be used:
+
+@vtable @code
+@item MM_RECOVER
+It is a recoverable error.
+@item MM_NRECOV
+It is a non-recoverable error.
+@end vtable
+
+@comment fmtmsg.h
+@comment XPG
+@deftypefun int fmtmsg (long int @var{classification}, const char *@var{label}, int @var{severity}, const char *@var{text}, const char *@var{action}, const char *@var{tag})
+Display a message described by its parameters on the device(s) specified
+in the @var{classification} parameter.  The @var{label} parameter
+identifies the source of the message.  The string should consist of two
+colon separated parts where the first part has not more than 10 and the
+second part not more the 14 characters.  The @var{text} parameter
+descries the condition of the error, the @var{action} parameter possible
+steps to recover from the error and the @var{tag} parameter is a
+reference to the online documentation where more information can be
+found.  It should contain the @var{label} value and a unique
+identification number.
+
+Each of the parameters can be of a special value which means this value
+is to be omitted.  The symbolic names for these values are:
+
+@vtable @code
+@item MM_NULLLBL
+Ignore @var{label} parameter.
+@item MM_NULLSEV
+Ignore @var{severity} parameter.
+@item MM_NULLMC
+Ignore @var{classification} parameter.  This implies that nothing is
+actually printed.
+@item MM_NULLTXT
+Ignore @var{text} parameter.
+@item MM_NULLACT
+Ignore @var{action} parameter.
+@item MM_NULLTAG
+Ignore @var{tag} parameter.
+@end vtable
+
+There is another way certain fields can be omitted from the output the
+standard error.  This is described below in the description of
+environment variables influencing the behaviour.
+
+The @var{severity} parameter can have one of the values in the following
+table:
+@cindex severity class
+
+@vtable @code
+@item MM_NOSEV
+Nothing is printed, this value is the same as @code{MM_NULLSEV}.
+@item MM_HALT
+This value is printed as @code{HALT}.
+@item MM_ERROR
+This value is printed as @code{ERROR}.
+@item MM_WARNING
+This value is printed as @code{WARNING}.
+@item MM_INFO
+This value is printed as @code{INFO}.
+@end vtable
+
+The numeric value of these five macros are between @code{0} and
+@code{4}.  Using the environment variable @code{SEV_LEVEL} or using the
+@code{addseverity} function one can add more severity levels with their
+corresponding string to print.  This is described below
+(@pxref{Adding Severity Classes}).
+
+@noindent
+If no parameter is ignored the output looks like this:
+
+@smallexample
+@var{label}: @var{severity-string}: @var{text}
+TO FIX: @var{action} @var{tag}
+@end smallexample
+
+The colons, new line characters and the @code{TO FIX} string are
+inserted if necessary, i.e., if the corresponding parameter is not
+ignored.
+
+This function is specified in the X/Open Portability Guide.  It is also
+available on all system derived from System V.
+
+The function return the value @code{MM_OK} if no error occurred.  If
+only the printing to standard error failed, it returns @code{MM_NOMSG}.
+If printing to the console fails, it returns @code{MM_NOCON}.  If
+nothing is printed @code{MM_NOTOK} is returned.  Among situation where
+all outputs fail this last value is also returned if a parameter value
+is incorrect.
+@end deftypefun
+
+There are two environment variables which influence the behaviour of
+@code{fmtmsg}.  The first is @code{MSGVERB}.  It is used to control the
+output actually happening on standard error (@emph{not} the console
+output).  Each of the five fields can explicitely be enabled.  To do
+this the user has to put the @code{MSGVERB} variable with a format like
+following in the environment before calling the @code{fmtmsg} function
+the first time:
+
+@smallexample
+MSGVERB=@var{keyword}[:@var{keyword}[:...]]
+@end smallexample
+
+Valid @var{keyword}s are @code{label}, @code{severity}, @code{text},
+@code{action}, and @code{tag}.  If the environment variable is not given
+or is the empty string, a not supported keyword is given or the value is
+somehow else invalid, no part of the message is masked out.
+
+The second environment variable which influences the behaviour of
+@code{fmtmsg} is @code{SEV_LEVEL}.  This variable and the change in the
+behaviour of @code{fmtmsg} is not specified in the X/Open Portability
+Guide.  It is available in System V systems, though.  It can be used to
+introduce no severity levels.  By default, only the five severity levels
+described above are available.  Any other numeric value would make
+@code{fmtmsg} print nothing.
+
+If the user puts @code{SEV_LEVEL} with a format like
+
+@smallexample
+SEV_LEVEL=[@var{description}[:@var{description}[:...]]]
+@end smallexample
+
+@noindent
+in the environment of the process before the first call to
+@code{fmtmsg}, where @var{description} has a value of the form
+
+@smallexample
+@var{severity-keyword},@var{level},@var{printstring}
+@end smallexample
+
+The @var{severity-keyword} part is not used by @code{fmtmsg} but it has
+to be present.  The @var{level} part is a string representation of a
+number.  The numeric value must be a number greater than 4.  This value
+must be used in the @var{severity} parameter of @code{fmtmsg} to select
+this class.  It is not possible to overwrite any of the predefined
+classes.  The @var{printstring} is the string printed when a message of
+this class is processed by @code{fmtmsg} (see above, @code{fmtsmg} does
+not print the numeric value but instead the string representation).
+
+
+@node Adding Severity Classes
+@subsection Adding Severity Classes
+@cindex severity class
+
+There is another possibility to introduce severity classes beside using
+the environment variable @code{SEV_LEVEL}.  This simplifies the task of
+introducing new classes in a running program.  One could use the
+@code{setenv} or @code{putenv} function to set the environment variable,
+but this toilsome.
+
+@deftypefun int addseverity (int @var{severity}, const char *@var{string})
+This function allows to introduce new severity classes which can be
+addressed by the @var{severity} parameter of the @code{fmtmsg} function.
+The @var{severity} parameter of @code{addseverity} must match the value
+for the parameter with the same name of @code{fmtmsg} and @var{string}
+is the string printed in the actual messages instead of the numeric
+value.
+
+If @var{string} is @code{NULL} the severity class with the numeric value
+according to @var{severity} is removed.
+
+The return value is @code{MM_OK} if the task was successfully performed.
+If the return value is @code{MM_NOTOK} something went wrong.  This could
+mean that no more memory is available or a class is not available when
+it has to be removed.
+
+This function is not specified in the X/Open Portability Guide although
+the @code{fmtsmg} is.  It is available on System V systems.
+@end deftypefun
+
+
+@node Example
+@subsection How to use @code{fmtmsg} and @code{addseverity}
+
+Here is a simple example program to illustrate the use of the both
+functions described in this section.
+
+@smallexample
+@include fmtmsgexpl.c.texi
+@end smallexample
+
+The second call to @code{fmtmsg} illustrates a use of this function how
+it usually happens on System V systems which heavily use this function.
+It might be worth a thought to follow the scheme used in System V
+systems so we give a short explanation here.  The value of the
+@var{label} field (@code{UX:cat}) says that the error occured in the
+Unix program @code{cat}.  The explanation of the error follows and the
+value for the @var{action} parameter is @code{"refer to manual"}.  One
+could me more specific here, if needed.  The @var{tag} field contains,
+as proposed above, the value of the string given for the @var{label}
+parameter, and additionally a unique ID (@code{001} in this case).  For
+a GNU environment this string could contain a reference to the
+corresponding node in the Info page for the program.
+
+@noindent
+Running this program without specifying the @code{MSGVERB} and
+@code{SEV_LEVEL} function produces the following output:
+
+@smallexample
+UX:cat: NOTE2: invalid syntax
+TO FIX: refer to manual UX:cat:001
+@end smallexample
+
+We see the different fields of the message and how the extra glue (the
+colons and the @code{TO FIX} string) are printed.  But only one of the
+three calls to @code{fmtmsg} produced output.  The first call does not
+print anything because the @var{label} parameter is not in the correct
+form.  As specified in @ref{Printing Formatted Messages} the string must
+contain two fields, separated by a colon.  The third @code{fmtmsg} call
+produced no output since the class with the numeric value @code{6} is
+not defined.  Although a class with numeric value @code{5} is also not
+defined by default, the call the @code{addseverity} introduces it and
+the second call to @code{fmtmsg} produces the above outout.
+
+When we change the environment of the program to contain
+@code{SEV_LEVEL=XXX,6,NOTE} when running it we get a different result:
+
+@smallexample
+UX:cat: NOTE2: invalid syntax
+TO FIX: refer to manual UX:cat:001
+label:foo: NOTE: text
+TO FIX: action tag
+@end smallexample
+
+Now the third call the @code{fmtmsg} produced some output and we see how
+the string @code{NOTE} from the environment variable appears in the
+message.
+
+Now we can reduce the output by specifying in which fields we are
+interested in.  If we additionally set the environment variable
+@code{MSGVERB} to the value @code{severity:label:action} we get the
+following output:
+
+@smallexample
+UX:cat: NOTE2
+TO FIX: refer to manual
+label:foo: NOTE
+TO FIX: action
+@end smallexample
+
+@noindent
+I.e., the output produced by the @var{text} and the @var{tag} parameters
+to @code{fmtmsg} vanished.  Please also note the now there is no colon
+after the @code{NOTE} and @code{NOTE2} strings in the output.  This is
+not necessary since there is no more output on this line since the text
+is missing.