From 7199e83868fa437be012a368751ef1b0fe1665eb Mon Sep 17 00:00:00 2001 From: gdr-ftp Date: Sun, 25 Oct 1998 17:15:51 +0000 Subject: [PATCH] sprintmt.3: Initial checkin for sprintmt(3) and vsprintmt(3) documentation. syslog.3: Add descriptions of syslogmt(3) and vsyslogmt(3), which are thread- safe variants with more limited format specifiers. progname.3: Added description of the "__progname" variable. This in effect exposes the cache value used by __prognameGS(). It was necessary for the proper operation of the thread-safe syslog routines. --- usr.man/man3/progname.3 | 32 ++++++++++++---- usr.man/man3/sprintmt.3 | 81 +++++++++++++++++++++++++++++++++++++++++ usr.man/man3/syslog.3 | 37 +++++++++++++++++++ 3 files changed, 143 insertions(+), 7 deletions(-) create mode 100644 usr.man/man3/sprintmt.3 diff --git a/usr.man/man3/progname.3 b/usr.man/man3/progname.3 index 545314c..daa1742 100644 --- a/usr.man/man3/progname.3 +++ b/usr.man/man3/progname.3 @@ -1,6 +1,6 @@ .\" Man page by Devin Reade. .\" -.\" $Id: progname.3,v 1.1 1997/02/27 07:32:24 gdr Exp $ +.\" $Id: progname.3,v 1.2 1998/10/25 17:15:51 gdr-ftp Exp $ .\" .TH "__PROGNAMEGS" 3 "21 January 1997" GNO "Library Routines" .SH NAME @@ -9,14 +9,32 @@ .SH SYNOPSIS #include .sp 1 +char *\fB__progname\fR; +.br char *\fB__prognameGS\fR (void); .SH DESCRIPTION +.BR __progname +points to a NULL-terminated string which is the base name of the +executing program. It is initially the string '(unknown)', but is +set to the proper value upon the first call to +.BR __prognameGS . +.LP .BR __prognameGS -returns a NULL-terminated string which is the base name of -the executing program. This is a wrapper function to the GS/OS +sets the string +.BR __progname +to its proper value by using the result of the GS/OS .BR GetNameGS -system call, and is used in the -.BR err (3) -routines. +system call. If for some reason that system call fails, the value of +.BR __progname +is left unchanged. On success, the value is cached, so subsequent calls to +.BR __prognameGS +merely reference +.BR __progname . +.SH RETURN VALUE +.BR __prognameGS +always returns the value of +.BR __progname . .SH SEE ALSO -.BR err (3) +.BR err (3), +.br +The \fIGS/OS Reference Manual\fR. diff --git a/usr.man/man3/sprintmt.3 b/usr.man/man3/sprintmt.3 new file mode 100644 index 0000000..78603ee --- /dev/null +++ b/usr.man/man3/sprintmt.3 @@ -0,0 +1,81 @@ +.\" Man page by Devin Reade. +.\" +.\" $Id: sprintmt.3,v 1.1 1998/10/25 17:15:51 gdr-ftp Exp $ +.\" +.TH SPRINTMT 3 "24 October 1998" GNO "Library Routines" +.SH NAME +.BR sprintmt , +.BR vsprintmt +\- multi threading safe print formatting +.SH SYNOPSIS +#include +.sp 1 +char *\fBsprintmt\fR (char *\fIbuffer\fR, size_t \fIbufferlen\fR, +const char *\fIfmt\fR, ...); +.br +char *\fBvsprintmt\fR (char *\fIbuffer\fR, size_t \fIbufferlen\fR, +const char *\fIfmt\fR, va_list \fIap\fR); +.SH DESCRIPTION +.BR sprintmt +and +.BR vsprintmt +are multithread-safe versions of the +.BR sprintf (3) +and +.BR vsprintf (3) +routines. +.LP +The contents of the format string +.IR fmt , +with appropriate arguments substituted for the format specifiers, +is copied into the user supplied +.IR buffer . +At most, +.IR bufferlen -1 +characters will be written +.IR buffer . +.LP +These routines have a much more limited set of format specifiers than +do the usual stdio routines. They are: +.RS +.IP "\fB%d\fR, \fB%ld\fR" +Print the decimal representation of a value of type +.BR "int" +or +.BR "long int" , +respectively. +.IP "\fB%u\fR, \fB%lu\fR" +Print the decimal representation of a value of type +.BR "unsigned int" +or +.BR "unsigned long int" , +respectively. +.IP "\fB%x\fR, \fB%X\fR, \fB%lx\fR, \fB%lX\fR" +Print the hexadecimal representation of an +.BR "unsigned int" +or +.BR "unsigned long int" . +If the +.B x +character is used, alphabetic characters are in lower case; otherwise +they are in upper case. +.IP \fB%s\fR +Print a NULL-terminated string. +If the 's' is preceeded by an 'l', the 'l' is ignored. +.IP \fB%m\fR +Print the current textual representation of +.BR errno , +as returned by +.BR strerror (3). +If the 'm' is preceeded by an 'l', the 'l' is ignored. +This format specifier is not available in the usual stdio functions. +.RE +.SH RETURN VALUE +These routines return a pointer to the terminating NULL byte in +.IR buffer . +.SH MT STATUS +Safe. +.SH SEE ALSO +.BR printf (3), +.BR stdio (3), +.BR strerror (3). diff --git a/usr.man/man3/syslog.3 b/usr.man/man3/syslog.3 index ae15c60..b76beed 100644 --- a/usr.man/man3/syslog.3 +++ b/usr.man/man3/syslog.3 @@ -35,6 +35,8 @@ .SH NAME .BR syslog , .BR vsyslog , +.BR syslogmt , +.BR vsyslogmt , .BR openlog , .BR closelog , .BR setlogmask @@ -52,6 +54,13 @@ void va_list \fBargs\fR); .br void +\fBsyslogmt\fR (int \fIpriority\fR, const char *\fImessage\fR, ...); +.br +void +\fBvsyslogmt\fR (int \fIpriority\fR, const char *\fImessage\fR, +va_list \fBargs\fR); +.br +void \fBopenlog\fR (const char *\fIident\fR, int \fIlogopt\fR, int \fIfacility\fR); .br void @@ -88,6 +97,24 @@ is an alternate form in which the arguments have already been captured using the variable-length argument facilities of .BR varargs (3). .LP +The +.BR syslogmt +and +.BR vsyslogmt +are multithread-safe variants of the +.BR syslog +and +.BR vsyslog +routines. Note that the permissable list of format specifiers for these +two routines is much smaller than those for +.BR syslog +or +.BR vsyslog . +The full list of format specifiers is given in the +.BR sprintmt (3) +manual page. +These two routines are GNO-specific and therefore non-portable. +.LP The message is tagged with .IR priority . Priorities are encoded as a @@ -263,8 +290,18 @@ syslog(LOG_INFO, "Connection from host %d", CallingHost); syslog(LOG_INFO|LOG_LOCAL2, "foobar error: %m"); .fi +.SH MT STATUS +.BR syslogmt +and +.BR vsyslogmt +are thread safe; the remainder are not. +.BR openlog +should be called in the parent thread before creating the child threads. +This will ensure that any generated messages are properly tagged with +.IR ident . .SH SEE ALSO .BR logger (1), +.BR sprintmt (3), .BR syslogd (8) .SH HISTORY These