Discard
@end itemize
-Syslogd can also handle messages from other systems. It listens on the
+Syslogd can also handle messages from other systems. It listens on the
@code{syslog} UDP port as well as the local socket for messages.
Syslog can handle messages from the kernel itself. But the kernel
@item priority
This tells how important the content of the message is. Examples of
defined priority values are: debug, informational, warning, critical.
-For the complete list, @xref{syslog; vsyslog}. Except for
+For the complete list, see @ref{syslog; vsyslog}. Except for
the fact that the priorities have a defined order, the meaning of each
of these priorities is entirely determined by the system administrator.
the kernel is zero, and that makes priority and facility/priority the
same value).
-The GNU C library provides functions to submit messages to Syslog. They
+@Theglibc{} provides functions to submit messages to Syslog. They
do it by writing to the @file{/dev/log} socket. @xref{Submitting Syslog
Messages}.
-The GNU C library functions only work to submit messages to the Syslog
+The @glibcadj{} functions only work to submit messages to the Syslog
facility on the same system. To submit a message to the Syslog facility
on another system, use the socket I/O functions to write a UDP datagram
to the @code{syslog} UDP port on that system. @xref{Sockets}.
@node Submitting Syslog Messages
@section Submitting Syslog Messages
-The GNU C library provides functions to submit messages to the Syslog
+@Theglibc{} provides functions to submit messages to the Syslog
facility:
@menu
@comment syslog.h
@comment BSD
-@deftypefun void openlog (char *@var{ident}, int @var{option},
- int @var{facility})
+@deftypefun void openlog (const char *@var{ident}, int @var{option}, int @var{facility})
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+@c openlog @asulock @aculock @acsfd
+@c libc_lock_lock @asulock @aculock
+@c openlog_internal @acsfd [always guarded by syslog_lock, so no race]
+@c strncpy dup ok
+@c socket dup @acsfd
+@c fcntl dup ok
+@c connect dup ok
+@c close dup @acsfd
+@c cancel_handler(NULL) @aculock
+@c libc_lock_unlock @aculock
@code{openlog} opens or reopens a connection to Syslog in preparation
for submitting messages.
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 in Syslog messages will be the program name,
+taken from argv[0].
+
+Please 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. It is also dangerous to pass a reference to an
+automatic variable since leaving the scope would mean ending the
+lifetime of the variable. If you want to change the @var{ident} string,
+you must call @code{openlog} again; overwriting the string pointed to by
+@var{ident} is not thread-safe.
+
+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}: @xref{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:
+
+@smallexample
+#include <syslog.h>
+
+void
+shared_library_function (void)
+@{
+ openlog ("mylibrary", option, priority);
+
+ syslog (LOG_INFO, "shared library has been invoked");
+
+ closelog ();
+@}
+@end smallexample
+
+Without the call to @code{closelog}, future invocations of @code{syslog}
+by the program using the shared library may crash, if the library gets
+unloaded and the memory containing the string @code{"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
+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
as a datagram socket. The socket has the ``Close on Exec'' attribute,
so the kernel will close it if the process performs an exec.
You don't have to use @code{openlog}. If you call @code{syslog} without
having called @code{openlog}, @code{syslog} just opens the connection
implicitly and uses defaults for the information in @var{ident} and
-@var{options}.
+@var{options}.
@var{options} is a bit string, with the bits as defined by the following
single bit masks:
@c syslog() is implemented as a call to vsyslog().
@comment syslog.h
@comment BSD
-@deftypefun void syslog (int @var{facility_priority}, char *@var{format}, ...)
+@deftypefun void syslog (int @var{facility_priority}, const char *@var{format}, @dots{})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c syslog @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c va_start dup ok
+@c vsyslog_chk @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c syslog(INTERNALLOG) dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c open_memstream @ascuheap @acsmem
+@c stpcpy dup ok
+@c getpid dup ok
+@c mempcpy dup ok
+@c fsetlocking [no @mtasurace:stream @asulock for exclusive stream]
+@c fprintf @mtslocale @ascuheap @acsmem [no @asucorrupt @aculock @acucorrupt on temp memstream]
+@c time dup ok
+@c localtime_r dup @mtsenv @mtslocale @ascuheap @asulock @aculock @acsmem @acsfd
+@c strftime_l(C) dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c ftell dup ok [no @asucorrupt @aculock @acucorrupt on temp memstream]
+@c fputs_unlocked dup ok [no @mtasurace:stream @asucorrupt @acucorrupt on temp memstream]
+@c putc_unlocked dup ok [no @mtasurace:stream @asucorrupt @acucorrupt on temp memstream]
+@c vfprintf/vfprintf_chk dup @mtslocale @ascuheap @acsmem [no @mtasurace:stream @asucorrupt @acucorrupt on temp memstream]
+@c fclose dup @ascuheap @acsmem [no @asulock @aculock @acsfd on caller-locked memstream]
+@c writev dup ok
+@c libc_lock_lock dup @asulock @aculock
+@c memset dup ok
+@c sigemptyset dup ok
+@c sigaction(SIGPIPE) dup @mtasusig:PIPE @acusig:PIPE
+@c openlog_internal dup @acsfd
+@c send dup ok
+@c closelog_internal dup @acsfd
+@c open dup @acsfd
+@c dprintf dup ok
+@c libc_lock_unlock @asulock @aculock
+@c free dup @acsuheap @acsmem
+@c va_end dup ok
@code{syslog} submits a message to the Syslog facility. It does this by
writing to the Unix domain socket @code{/dev/log}.
@code{syslog} submits the message with the facility and priority indicated
by @var{facility_priority}. The macro @code{LOG_MAKEPRI} generates a
-facility/priority from a facility and a priority, as in the following
+facility/priority from a facility and a priority, as in the following
example:
@smallexample
@c Internally, there is also LOG_KERN, but LOG_KERN == 0, which means
@c if you try to use it here, just selects default.
-@table @code
+@vtable @code
@item LOG_USER
A miscellaneous user process
@item LOG_MAIL
Locally defined
@item LOG_LOCAL7
Locally defined
-@end table
+@end vtable
Results are undefined if the facility code is anything else.
-@strong{note:} Syslog recognizes one other facility code: that of the
-kernel. But you can't specify that facility code with these functions.
-If you try, it looks the same to @code{syslog} as if you are requesting
-the default facility. But you wouldn't want to anyway, because any
-program that uses the GNU C library is not the kernel.
+@strong{NB:} @code{syslog} recognizes one other facility code: that of
+the kernel. But you can't specify that facility code with these
+functions. If you try, it looks the same to @code{syslog} as if you are
+requesting the default facility. But you wouldn't want to anyway,
+because any program that uses @theglibc{} is not the kernel.
You can use just a priority code as @var{facility_priority}. In that
case, @code{syslog} assumes the default facility established when the
The possible values for the priority code are (macros):
-@table @code
+@vtable @code
@item LOG_EMERG
The message says the system is unusable.
@item LOG_ALERT
The message is purely informational.
@item LOG_DEBUG
The message is only for debugging purposes.
-@end table
+@end vtable
Results are undefined if the priority code is anything else.
-If the process does not presently have a Syslog connection open (i.e.
+If the process does not presently have a Syslog connection open (i.e.,
it did not call @code{openlog}), @code{syslog} implicitly opens the
connection the same as @code{openlog} would, with the following defaults
for information that would otherwise be included in an @code{openlog}
connection options in @var{options} is as if those bits were off.
@code{syslog} leaves the Syslog connection open.
-If the @file{dev/log} socket is not open and connected, @code{syslog}
+If the @file{/dev/log} socket is not open and connected, @code{syslog}
opens and connects it, the same as @code{openlog} with the
@code{LOG_NDELAY} option would.
@smallexample
#include <syslog.h>
-syslog(LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR),
- "Unable to make network connection to %s. Error=%m", host);
+syslog (LOG_MAKEPRI(LOG_LOCAL1, LOG_ERROR),
+ "Unable to make network connection to %s. Error=%m", host);
@end smallexample
@comment syslog.h
@comment BSD
-@deftypefun void vsyslog (int @var{facility_priority}, char *@var{format},
- __gnuc_va_list arglist)
+@deftypefun void vsyslog (int @var{facility_priority}, const char *@var{format}, va_list @var{arglist})
+@safety{@prelim{}@mtsafe{@mtsenv{} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{} @asulock{} @ascudlopen{}}@acunsafe{@acucorrupt{} @aculock{} @acsmem{} @acsfd{}}}
+@c vsyslog @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
+@c vsyslog_chk dup @mtsenv @mtslocale @asucorrupt @ascuheap @asulock @ascudlopen @acucorrupt @aculock @acsmem @acsfd
This is functionally identical to @code{syslog}, with the BSD style variable
length argument.
@comment syslog.h
@comment BSD
-@deftypefun void closelog ()
+@deftypefun void closelog (void)
+@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
+@c closelog @asulock @aculock @acsfd
+@c libc_lock_lock @asulock @aculock
+@c closelog_internal @acsfd [always guarded by syslog_lock, so no race]
+@c close dup@acsfd
+@c cancel_handler(NULL) @aculock
+@c libc_lock_unlock @aculock
@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.
-@code{closelog} has primarily aesthetic value.
+This includes closing the @file{/dev/log} socket, if it is open.
+@code{closelog} also sets the identification string for Syslog messages
+back to the default, if @code{openlog} was called with a non-NULL argument
+to @var{ident}. The default identification 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
+@theglibc{}'s internal reference to the @var{ident} pointer when you are
+done. Please read the section on @code{openlog} for more information:
+@xref{openlog}.
+
+@code{closelog} does not flush any buffers. You do not have to call
+@code{closelog} before re-opening a Syslog connection with @code{openlog}.
+Syslog connections are automatically closed on exec or exit.
@end deftypefun
@comment syslog.h
@comment BSD
@deftypefun int setlogmask (int @var{mask})
+@safety{@prelim{}@mtunsafe{@mtasurace{:LogMask}}@asunsafe{}@acsafe{}}
+@c Read and modify are not guarded by syslog_lock, so concurrent changes
+@c or even uses are undefined. This should use an atomic swap instead,
+@c at least for modifications.
@code{setlogmask} sets a mask (the ``logmask'') that determines which
future @code{syslog} calls shall be ignored. If a program has not
LOG_UPTO(LOG_ERROR)
@end smallexample
-The unfortunate naming of the macro is due to the fact that internally,
+The unfortunate naming of the macro is due to the fact that internally,
higher numbers are used for lower message priorities.
@end deftypefun
@smallexample
#include <syslog.h>
-setlogmask(LOG_UPTO(LOG_NOTICE));
+setlogmask (LOG_UPTO (LOG_NOTICE));
-openlog("exampleprog", LOG_CONS | LOG_PID | LOG_NDELAY, LOG_LOCAL1);
+openlog ("exampleprog", LOG_CONS | LOG_PID | LOG_NDELAY, LOG_LOCAL1);
-syslog(LOG_NOTICE, "Program started by User %d", getuid());
-syslog(LOG_INFO, "A tree falls in a forest");
+syslog (LOG_NOTICE, "Program started by User %d", getuid ());
+syslog (LOG_INFO, "A tree falls in a forest");
-closelog();
+closelog ();
@end smallexample
-
-
-
git.samba.org / jlayton / glibc.git / blobdiff