aboutsummaryrefslogtreecommitdiff
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
glibc-0501d6036744d44cad6d5a6eda8090ddfbe604c4.tar.gz
glibc-0501d6036744d44cad6d5a6eda8090ddfbe604c4.tar.bz2
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.