Re: bug in openlog()

[Christopher Allen Wing]

Ulrich:

I'm sorry, the patch I sent in my last e-mail had a typo. Here is a
corrected version of the documentation patch.

Would this be an acceptable change?


Thanks,

Chris Wing
address@hidden



--- glibc-2.2.4/manual/syslog.texi.orig Fri Dec 21 18:54:16 2001
+++ glibc-2.2.4/manual/syslog.texi      Fri Dec 21 19:25:26 2001
@@ -146,7 +146,7 @@

 @comment syslog.h
 @comment BSD
address@hidden void openlog (char address@hidden, int @var{option},
address@hidden void openlog (const char address@hidden, int @var{option},
         int @var{facility})

 @code{openlog} opens or reopens a connection to Syslog in preparation
@@ -157,6 +157,43 @@
 to identify the source of the message, and people conventionally set it
 to the name of the program that will submit the messages.

+If @var{ident} is NULL, or if @code{openlog} is not called, the default
+identification string used by @code{syslog} will be the program name,
+taken from argv[0].
+
+Plese note that the string pointer @var{ident} will be retained internally
+by the Syslog routines.  You must not free the memory that @var{ident}
+points to.  If you want to change the @var{ident} string, you must call
address@hidden again; overwriting the string pointed by @var{ident} is not
+threadsafe.
+
+You can cause the Syslog routines to drop the reference to @var{ident} and
+go back to the default string (the program name taken from argv[0]), by
+calling @code{closelog}.
+
+In particular, if you are writing code for a shared library that might get
+loaded and then unloaded (e.g. a PAM module), and you use @code{openlog},
+you must call @code{closelog} before any point where your library might
+get unloaded, as in this example:
+
address@hidden
+#include <syslog.h>
+
+shared_library_function()
address@hidden
+       openlog("mylibrary", option, priority);
+
+       syslog(LOG_INFO, "shared library has been invoked");
+
+       closelog();
address@hidden
address@hidden smallexample
+
+Without the call to @code{closelog}, future invocations of @code{syslog}
+by the program using the shared library may crash, if the memory
+containing the string "mylibrary" becomes unmapped.  This is a limitation
+of the BSD syslog interface.
+
 @code{openlog} may or may not open the @file{/dev/log} socket, depending
 on @var{option}.  If it does, it tries to open it and connect it as a
 stream socket.  If that doesn't work, it tries to open it and connect it
@@ -383,12 +420,20 @@
 @deftypefun void closelog (void)

 @code{closelog} closes the current Syslog connection, if there is one.
-This include closing the @file{dev/log} socket, if it is open.
-
-There is very little reason to use this function.  It does not flush any
-buffers; you can reopen a Syslog connection without closing it first;
-The connection gets closed automatically on exec or exit.
address@hidden has primarily aesthetic value.
+This includes closing the @file{dev/log} socket, if it is open.
address@hidden also sets the @var{ident} string back to the default, if
+one was given to @code{openlog}.  The default string is the program name
+taken from argv[0].
+
+If you are writing shared library code that uses @code{openlog} to
+generate custom syslog output, you should use @code{closelog} to drop the
+GNU C library's internal reference to the @var{ident} pointer when you are
+done.  Please read the section on @code{openlog} for more information:
address@hidden
+
address@hidden does not flush any buffers.  You do not have to call
address@hidden before re-opening a Syslog connection with @code{initlog}.
+Syslog connections are automatically closed on exec or exit.

 @end deftypefun