log4sh version 1.3.6

Kate Ward

<kate.ward@forestent.com>

2006-09-16

Revision History
Revision 1.3.6	2006-09-16	kwd
Revision 1.3.5	2006-08-19	kwd
Revision 1.3.4	2006-03-25	kwd
Revision 1.3.3	2006-02-11	kwd
Revision 1.3.2	2006-01-18	kwd
Revision 1.3.0	2005-08-15	kwd
Revision 1.2.6	2005-02-01	kwd
Revision 1.2.4	2004-12-28	kwd

Abstract

log4sh is a logging framework for shell scripts that works similar to the other wonderful logging products available from the Apache Software Foundation (eg. log4j, log4perl). Although not as powerful as the others, it can make the task of adding advanced logging to shell scripts easier. It has much more power than just using simple "echo" commands throughout. In addition, it can be configured from a properties file so that scripts in a production environment do not need to be altered to change the amount of logging they produce.

List of Tables

4.1. Logging Levels (from most output to least)
4.2. Appender Types
4.3. Appender Options
4.4. Layouts
4.5. Pattern Options
4.6. log4sh environment variables
5.1. Appender
5.2. FileAppender
5.3. Level
5.4. Log4sh
5.5. Logger
5.6. Property
5.7. SMTPAppender
5.8. SyslogAppender
5.9. Thread
5.10. Trap

List of Examples

2.1. Hello, World!
2.2. Properties Configuration Test
2.3. Runtime Configuration Test
3.1. Sourcing external shell code into current program
3.2. Hello, world (using properties file)
3.3. Hello, world; properties file
3.4. Hello, world (configured in code)
3.5. Standard method of logging a message
3.6. Alternate method of logging a message
4.1. Recommended minimum log4sh.properties file
4.2. Sample appender names
4.3. Setting an appender type
4.4. Setting an appender option
4.5. Setting an appender's layout
4.6. Setting an appender's layout pattern
4.7. LOG4SH_CONFIGURATION variable
4.8. LOG4SH_CONFIG_PREFIX variable

Chapter 1. Introduction

Table of Contents

1. Credits / Contributors
2. Feedback

Log4sh has been developed under the Bourne Again Shell (bash) on Linux, but great care has been taken to make sure it works under the default Bourne Shell of Solaris (sh) as this happens to be the primary platform used by myself.

Tested Operating Systems
Cygwin
FreeBSD
Linux
Solaris 8, 9, 10

Tested Shells
Bourne Shell (sh)
Bourne Again Shell (bash)
Korn Shell (ksh, pdksh)

1. Credits / Contributors

A list of contributors to log4sh can be found in the source archive as doc/contributors.txt. I want to personally thank all those who have contributed to make this a better tool.

2. Feedback

Feedback is most certainly welcome for this document. Send your additions, comments and criticisms to the following email address: <kate.ward@forestent.com>.

Chapter 2. Quickstart

First things first. Go to the directory from which you extracted the log4sh software. In there, you should find a Makefile. If you find one, you are in the right place. We need to setup the environment for running tests, so from this directory, execute the make test-prep command as shown below. Once this is done, a test directory will be created and prepared with everything needed to run the log4sh tests.

Prepare your environment.

$ make test-prep
$ cd test

Example 2.1. Hello, World!

Ok. What kind of a quickstart would this be if the first example wasn't a "Hello, World!" example? Who knows, but this isn't one of those kind of quickstarts.

Run the Hello World test.

$ ./hello_world
1 [main] INFO shell  - Hello, world!

You should have seen output similar to that above. If not, make sure you are in the right location and such. If you really had problems, please send a letter to the log4sh maintainers. Who knows, maybe you already found a bug. Hopefully not!

The Hello, World! test is about as simple as it gets. If you take a look at the test, all it does is load log4sh, reset the default logging level from ERROR to INFO, and the logs a "Hello, world!" message. As you can see, it didn't take much to setup and use log4sh.

Example 2.2. Properties Configuration Test

In this example, a log4sh.properties configuraiton file will be used to pre-configure log4sh before any logging messages are output. It demonstrates that a configuration file can be used to alter the behavior of log4sh without having to change any shell code.

Run the properties configuration test.

$ ./test-prop-config
INFO - We are the Simpsons!
INFO - Mmmmmm .... Chocolate.
INFO - Homer likes chocolate
...

You should see much more output on your terminal that what was listed above. What is actually happening is log4sh is outputting information to STDERR using logging statements that were stored in the test-common script. In addition, there were multiple logfiles generated (take a look in the test directory), and output was written also written via Syslog. Take a look at both the property configuration script (test-prop-config) and the common script (test-common) if you would like to see what is happening. If you do, you will notice that nowhere in code was it configured to write to the any of those different locations. The log4sh.properties configuration file did all of that work for us. Go ahead and take a look at it too. You might be amazed with how easy it was to write to so many locations with such a small amount of code.

Example 2.3. Runtime Configuration Test

This example is exactly like the last example as far as output is concerned (they both execute the same test-common script), but this one is configured instead at runtime with function calls. It demonstrates that log4sh is fully configurable at runtime.

Run the runtime configuration test.

$ ./test-runtime-config
INFO - We are the Simpsons!
INFO - Mmmmmm .... Chocolate.
INFO - Homer likes chocolate
...

You should again see much more output on your terminal that what was listed above. The output should also have been exactly the same (except that the times were different) as the above example. This is because the same logging commands were used. If you take a look a look in the test-runtime-config script though, you will see that this time log4sh was configured completly at runtime. The log4sh.properties was not used. It shows that log4sh can be fully configured without a pre-existing configuration file. This isn't nearly as friendly as using the configuration file, but there are times when it is needed.

Chapter 3. Usage Guide

Table of Contents

1. Preconfigure log4sh (optional)
2. Source log4sh
3. Configure log4sh in code
4. Logging with log4sh

The usage of log4sh is simple. There are only a few simple steps required to setup and use log4sh in your application.

preconfigure log4sh (properties file)
source the log4sh script code into the shell script
configure log4sh in code (optional)
call logging statements

1. Preconfigure log4sh (optional)

To preconfigure log4sh, create a properties file (see the Properties File later in this document). If the properties file is not located in the same directory as log4sh, set the LOG4SH_CONFIGURATION environment variable to the full path to the properties file. If you do not wish to preconfigure log4sh, please read the Configure log4sh in code section later in this chapter.

2. Source log4sh

To source the code into your script (also known as including), one uses the sourcing ability of shell to source one script into another. See the following quick example for how easy this is done.

Example 3.1. Sourcing external shell code into current program

#! /bin/sh

# source log4sh from current directory
. ./log4sh

Here is some sample code that looks for log4sh in the same directory as the script is located, as well as the current directory. If log4sh could not be found, it exits with an error. If log4sh is found, it is loaded, along with the log4sh.properties file in the current directory (see the following example). It then logs a message at the INFO level to STDOUT.

Example 3.2. Hello, world (using properties file)

#! /bin/sh
#
# log4sh example: Hello, world
#
myDir=`dirname $0`

# find and source log4sh
if [ -r "$myDir/log4sh" ]; then
  log4shDir=$myDir
elif [ -r "./log4sh" ]; then
  log4shDir=.
else
  echo "fatal: could not find log4sh" >&2
  exit 1
fi
. $log4shDir/log4sh

# say Hello to the world
logger_info "Hello, world"

Here is the log4sh.properties file for the previous example. Save it in the same directory you are running the above script from.

Example 3.3. Hello, world; properties file

#
# log4sh example: Hello, world properties file
#

# Set root logger level to DEBUG and its only appender to A1
log4sh.rootLogger=INFO, A1

# A1 is set to be a ConsoleAppender.
log4sh.appender.A1=ConsoleAppender

# A1 uses a PatternLayout.
log4sh.appender.A1.layout=PatternLayout
log4sh.appender.A1.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n

3. Configure log4sh in code

If log4sh was not preconfigured, the default configuration will be equivalent the config shown below.

Note: log4sh will complain if no configuration file was specified or found. If you meant for the default configuration to be used, or you want to configure log4sh via code, make sure to define the LOG4SH_CONFIGURATION with the value of 'none'.

log4sh.rootLogger=ERROR, stdout
log4sh.appender.stdout=ConsoleAppender
log4sh.appender.stdout.layout=PatternLayout
log4sh.appender.stdout.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n

To configure log4sh in code, simply call the appropriate functions in your code. The following code sample loads log4sh from the current directory, configures it for STDERR output, and the logs a message at the INFO level.

Example 3.4. Hello, world (configured in code)

#! /bin/sh
#
# log4sh example: Hello, world
#

# source log4sh (disabling properties file warning)
LOG4SH_CONFIGURATION='none' . ./log4sh

# set the global logging level
logger_setLevel INFO

# close the default STDOUT appender, and add a new STDERR appender
appender_close stdout
logger_addAppender stderr
appender_setType stderr FileAppender
appender_file_setFile stderr STDERR

# say Hello to the world
logger_info 'Hello, world'

4. Logging with log4sh

Once log4sh is loaded, logging is as simple as calling the appropriate logging function with a message to be logged. Take a look at the above examples to see just how easy it was to log the statement "Hello, world" at an INFO level.

The samples above show the standard way of logging a message via log4sh. That standard method is by calling the appropriate function, and passing the message as a parameter.

Example 3.5. Standard method of logging a message

logger_info 'message to log'

There is a second way of logging as well. The second method is via pipes. What this method is really good for is logging the standard output (STDOUT) of a command to the logfile. Piping echo statements is a bit silly, but something like piping the output of a ls is more practical (e.g. ls -l |logger_info).

Example 3.6. Alternate method of logging a message

echo 'message to log' |logger_info

Chapter 4. Configuration

Table of Contents

1. Properties File

1.1. Root Logger
1.2. Levels
1.3. Appenders

2. Environment Variables

1. Properties File

Log4sh can be configured with a properties file that is separate from the actual script where the logging takes place. By default, log4sh looks for its properties file called log4sh.properties in the current directory. If the file is located elsewhere or with a different name, log4sh can be configured by setting the LOG4SH_CONFIGURATION environment variable (eg. LOG4SH_CONFIGURATION="/etc/log4sh.conf").

A log4sh.properties file that is completly empty is sufficient to configure log4sh. There will be absolutely no output however (which might just be what is desired). Usually though, some output is desired, so there is at least a recommended minimum configuration file. An explaination of the file follows the example.

Example 4.1. Recommended minimum log4sh.properties file

  log4sh.rootLogger=INFO, stdout
  log4sh.appender.stdout=ConsoleAppender

In the first line, the root logger is configured by setting the default logging level, and defining the name of an appender. In the second line, the stdout appender is defined as a ConsoleAppender.

1.1. Root Logger

(future)

1.2. Levels

Table 4.1. Logging Levels (from most output to least)

Level	Definition
`TRACE`	The `TRACE` level has the lowest possible rank and is intended to turn on all logging.
`DEBUG`	The `DEBUG` level designates fine-grained informational events that are most useful to debug an application.
`INFO`	The `INFO` level designates informational messages that highlight the progress of the application at coarse-grained level.
`WARN`	The `WARN` level designates potentially harmful situations.
`ERROR`	The `ERROR` level designates error events that might still allow the application to continue running.
`FATAL`	The `FATAL` level designates very severe error events that will presumably lead the application to abort.
`OFF`	The `OFF` level has the highest possible rank and is intended to turn off logging.

1.3. Appenders

An appender name can be any alpha-numeric string containing no spaces.

Example 4.2. Sample appender names

myAppender - good

1.3.1. Types

An appender can be set to one of several different types.

Example 4.3. Setting an appender type

    log4sh.appender.A1=FileAppender

Table 4.2. Appender Types

Type	Definition	Supported?
ConsoleAppender	output sent to console (STDOUT)	yes
FileAppender	output sent to a file	yes
DailyRollingFileAppender	output sent to a file that rolls over daily	partial; logs written, but not rotated
RollingFileAppender	output sent to a file that rolls over by size	partial; works, but nees improvement
SMTPAppender	output sent via email	parital; works, but needs improvement
SyslogAppender	output sent to a remote syslog daemon	partial; only localhost supported

1.3.2. Options

An appender can take several different options.

Example 4.4. Setting an appender option

    log4sh.appender.A1.File=output.log

Table 4.3. Appender Options

Option	Definition	Supported?
DatePattern	configure a pattern for the output filename	no (ignored)
File	output filename (special filename of STDERR used for logging to STDERR)	yes
MaxBackupIndex	number of old logfiles to keep	no (ignored)
MaxFileSize	maximum size of old logfiles	no (ignored)
Threshold	logging level of the appender	yes

1.3.3. Layouts

An appender can be configured with various Layouts to customize how the output looks.

Example 4.5. Setting an appender's layout

    log4sh.appender.A1.layout=PatternLayout

Table 4.4. Layouts

Layout	Definition	Supported?
HTMLLayout	layout using HTML	no (same as SimpleLayout)
SimpleLayout	a simple default layout ('%p - %m')	yes
PatternLayout	a patterned layout (default: '%d %p - %m%n')	yes

An layout has many different options to configure how it appears. These are known as patterns.

Example 4.6. Setting an appender's layout pattern

    log4sh.appender.A1.layout.ConversionPattern=%d [%p] %c - %m%n

Table 4.5. Pattern Options

Option	Definition	Supported?
c	Used to output the category of logging request. As this is not applicable in shell, the conversion character will always returns 'shell'.	partial (fixed)
d	Used to output the date of the logging event. The date conversion specifier may be followed by a date format specifier enclosed between braces, but this specifier will be ignored. For example, `%d{HH:mm:ss,SSS}`, or `%d{ISODATE}`. The specifier is allowed only for compatibility with log4j properties files. The default format of the date returned is equavilant to the output of the Unix date command with a format of `+%Y-%m-%d %H:%M:%S`.	yes
F	Used to output the file name where the logging request was issued. The default value is equavilent basename $0.	yes
L	This option is for compatibility with log4j properties files.	no (ignored)
m	Used to output the script supplied message associated with the logging event.	yes
n	This option is for compatibility with log4j properties files.	no (ignored)
p	Used to output the priority of the logging event.	yes
r	Used to output the number of seconds elapsed since the start of the script until the creation of the logging event.	yes
t	Used to output the current executing thread. As shell doesn't actually support threads, this is simply a value that can be set that can be put into the messages.i The default value is 'main'.	yes
x	This option is for compatibility with log4j properties files.	no (ignored)
X	Used to output the MDC (mapped diagnostic context) associated with the thread that generated the logging event. The `X` conversion character must be followed by an environment variable name placed between braces, as in `%X{clientNumber}` where `clientNumber` is the name of the environment variable. The value in the MDC corresponding to the environment variable will be output.	no (ignored)
%	The sequence `%%` outputs a single percent sign.	yes

2. Environment Variables

There are some environment variables that can be used to pre-configure log4sh, or to change some of its default behavior. These variables should be set before log4sh is sourced so that they are immediately available to log4sh.

Here is the full list of supported variables.

Table 4.6. log4sh environment variables

Variable Usage

Variable	Usage
`LOG4SH_CONFIGURATION`	This variable is used to tell log4sh what the name of (and possibly the full path to) the configuration (a.k.a properties) file that should be used to configure log4sh at the time log4sh is sourced. If the value 'none' is passed, than log4sh will expect to be configured at a later time via run-time configuration. Example 4.7. LOG4SH_CONFIGURATION variable LOG4SH_CONFIGURATION='/path/to/log4j.properties'
`LOG4SH_CONFIG_PREFIX`	This variable is used to tell log4sh what prefix it should use when parsing the configuration file. Normally, the default value is 'log4sh' (e.g. 'log4sh.rootLogger'), but the value can be redefined so that a configuration file from another logging frame work such as log4j can be read. Example 4.8. LOG4SH_CONFIG_PREFIX variable LOG4SH_CONFIG_PREFIX='log4j'

LOG4SH_CONFIGURATION

This variable is used to tell log4sh what the name of (and possibly the full path to) the configuration (a.k.a properties) file that should be used to configure log4sh at the time log4sh is sourced. If the value 'none' is passed, than log4sh will expect to be configured at a later time via run-time configuration.

Example 4.7. LOG4SH_CONFIGURATION variable

LOG4SH_CONFIGURATION='/path/to/log4j.properties'

LOG4SH_CONFIG_PREFIX

This variable is used to tell log4sh what prefix it should use when parsing the configuration file. Normally, the default value is 'log4sh' (e.g. 'log4sh.rootLogger'), but the value can be redefined so that a configuration file from another logging frame work such as log4j can be read.

Example 4.8. LOG4SH_CONFIG_PREFIX variable

LOG4SH_CONFIG_PREFIX='log4j'

Chapter 5. Function Reference

Table of Contents

1. Appender
2. FileAppender
3. Level
4. Log4sh
5. Logger
6. Property
7. SMTPAppender
8. SyslogAppender
9. Thread
10. Trap

1. Appender

Table 5.1. Appender

void

appender_activateOptions ( appender);

string appender;

Activate an appender's configuration. This should be called after reconfiguring an appender via code. It needs only to be called once before any logging statements are called. This calling of this function will be required in log4sh 1.4.x.

appender_activateAppender myAppender

void

appender_close ( appender);

string appender;

Disable any further logging via an appender. Once closed, the appender can be reopened by setting it to any logging Level (e.g. INFO).

appender_close myAppender

boolean

appender_exists ( appender);

string appender;

Checks for the existance of a named appender

exists=`appender_exists myAppender`

string

appender_getAppenderType ( index);

integer index;

Deprecated as of 1.3.1

Gets the Type of an Appender at the given array index

type=`appender_getAppenderType 3`

string

appender_getLayout ( appender);

string appender;

Gets the Layout of an Appender

type=`appender_getLayout myAppender`

string

appender_getLevel ( appender);

string appender;

Gets the current logging Level of an Appender

type=`appender_getLevel myAppender`

string

appender_getPattern ( appender);

string appender;

Gets the Pattern of an Appender

pattern=`appender_getPattern myAppender`

string

appender_getType ( appender);

string appender;

Gets the Type of an Appender

type=`appender_getType myAppender`

void

`appender_setAppenderType (`	`appender`,
	`type)`;

`string`	`appender;`
`string`	`type;`

Deprecated as of 1.3.1

Sets the Type of an Appender (e.g. FileAppender)

appender_setAppenderType myAppender FileAppender

void

`appender_setLayout (`	`appender`,
	`layout)`;

`string`	`appender;`
`string`	`layout;`

Sets the Layout of an Appender (e.g. PatternLayout)

appender_setLayout myAppender PatternLayout

void/boolean

`appender_setLevel (`	`appender`,
	`level)`;

`string`	`appender;`
`string`	`level;`

Sets the Level of an Appender (e.g. INFO)

appender_setLevel myAppender INFO

void/boolean

`appender_setPattern (`	`appender`,
	`pattern)`;

`string`	`appender;`
`string`	`pattern;`

Sets the Pattern of an Appender

appender_setPattern myAppender '%d %p - %m%n'

void/boolean

`appender_setType (`	`appender`,
	`type)`;

`string`	`appender;`
`string`	`type;`

Sets the Type of an Appender (e.g. FileAppender)

appender_setType myAppender FileAppender

2. FileAppender

Table 5.2. FileAppender

string

appender_file_getFile ( appender);

string appender;

Get the filename of a FileAppender

appender_file_getFile myAppender

void

`appender_file_setFile (`	`appender`,
	`filename)`;

`string`	`appender;`
`string`	`filename;`

Set the filename for a FileAppender (e.g. "STDERR" or "/var/log/log4sh.log")

appender_file_setFile myAppender STDERR

void

`appender_file_setMaxBackupIndex (`	`appender`,
	`index)`;

`string`	`appender;`
`integer`	`index;`

Not yet implemented

Set the maximum backup index for a DailyRollingFileAppender or RollingFileAppender.

      appender_file_setMaxBackupIndex myAppender 3

void

`appender_file_setMaxFileSize (`	`appender`,
	`size)`;

`string`	`appender;`
`string`	`size;`

Not yet implemented

Set the maximum backup file size for a DailyRollingFileAppender or RollingFileAppender.

appender_file_setMaxBackupIndex myAppender 100KiB

void

`appender_setAppenderFile (`	`appender`,
	`filename)`;

`string`	`appender;`
`string`	`filename;`

Deprecated as of 1.3.2

Set the filename for a FileAppender (e.g. "STDERR" or "/var/log/log4sh.log")

appender_setAppenderFile myAppender STDERR

3. Level

Table 5.3. Level

integer

logger_level_toInt ( level);

string level;

Converts an externally used level tag into its integer equivalent

levelInt=`logger_level_toInt WARN`

string

logger_level_toLevel ( val);

integer val;

Converts an internally used level integer into its external level equivalent

level=`logger_level_toLevel 3`

4. Log4sh

Table 5.4. Log4sh

5. Logger

Table 5.5. Logger

void

`log (`	`level`,
	`message(s))`;

`string`	`level;`
`string[]`	`message(s);`

The base logging command that logs a message to all defined appenders

log DEBUG "This is a test message"`

void/boolean

logger_addAppender ( appender);

string appender;

Add and initialize a new appender

logger_addAppender $appender

void

`logger_addAppenderWithPattern (`	`appender`,
	`pattern)`;

`string`	`appender;`
`string`	`pattern;`

Deprecated as of 1.3.6

Add and initialize a new appender with a specific PatternLayout

logger_addAppenderWithPattern $appender '%d %p - %m%n'

void

logger_debug ( message);

string[] message;

This is a helper function for logging a message at the DEBUG priority

logger_debug "This is a debug message"`

void

logger_error ( message);

string[] message;

This is a helper function for logging a message at the ERROR priority

logger_error "This is a error message"`

void

logger_fatal ( message);

string[] message;

This is a helper function for logging a message at the FATAL priority

logger_fatal This is a fatal message`

string

logger_getFilename ( );

Get the filename that would be shown when the '%F' conversion character is used in a PatternLayout.

myFilename=`logger_setFilename`

string

logger_getLevel ( );

Get the global default logging level (e.g. DEBUG).

level=`logger_getLevel`

void

logger_info ( message);

string[] message;

This is a helper function for logging a message at the INFO priority

logger_info "This is a info message"`

void

logger_setFilename ( filename);

string filename;

Set the filename to be shown when the '%F' conversion character is used in a PatternLayout.

logger_setFilename "myScript.sh"

void

logger_setLevel ( level);

string level;

Sets the global default logging level (e.g. DEBUG).

logger_setLevel INFO

void

logger_trace ( message);

string[] message;

This is a helper function for logging a message at the TRACE priority

logger_trace "This is a trace message"`

void

logger_warn ( message);

string[] message;

This is a helper function for logging a message at the WARN priority

logger_warn "This is a warn message"`

6. Property

Table 5.6. Property

void

log4sh_doConfigure ( configFileName);

string configFileName;

Read configuration from a file. The existing configuration is not cleared or reset. If you require a different behavior, then call the log4sh_resetConfiguration before calling log4sh_doConfigure.

log4sh_doConfigure myconfig.properties

void

log4sh_readProperties ( configFileName);

string configFileName;

Deprecated as of 1.3.6

See log4sh_doConfigure.

log4sh_readProperties myconfig.properties

void

log4sh_resetConfiguration ( );

This function completely resets the log4sh configuration to have no appenders with a global logging level of ERROR.

log4sh_resetConfiguration

7. SMTPAppender

Table 5.7. SMTPAppender

void

`appender_setAppenderRecipient (`	`appender`,
	`email)`;

`string`	`appender;`
`string`	`email;`

Deprecated as of 1.3.1

Set the to address for the given appender

appender_smtp_setTo myAppender user@example.com

void/boolean

`appender_setAppenderSubject (`	`appender`,
	`subject)`;

`string`	`appender;`
`string`	`subject;`

Deprecated as of 1.3.1

Sets the email subject for an SMTP appender

appender_setAppenderSubject myAppender "This is a test"

string

appender_smtp_getSubject ( appender);

string appender;

Get the email subject for the given appender

subject=`appender_smtp_getSubject myAppender`

string

appender_smtp_getTo ( appender);

string appender;

Get the to address for the given appender

email=`appender_smtp_getTo myAppender`

void/boolean

`appender_smtp_setSubject (`	`appender`,
	`subject)`;

`string`	`appender;`
`string`	`subject;`

Sets the email subject for an SMTP appender

appender_smtp_setSubject myAppender "This is a test"

void

`appender_smtp_setTo (`	`appender`,
	`email)`;

`string`	`appender;`
`string`	`email;`

Set the to address for the given appender

appender_smtp_setTo myAppender user@example.com

8. SyslogAppender

Table 5.8. SyslogAppender

string

appender_getSyslogFacility ( index);

integer index;

Deprecated as of 1.3.1

Get the syslog facility of the specified appender by index

facility=`appender_getSyslogFacility 3`

void

`appender_setSyslogFacility (`	`appender`,
	`facility)`;

`string`	`appender;`
`string`	`facility;`

Deprecated as of 1.3.2

Set the syslog facility for the given appender

appender_setSyslogFacility myAppender local4`

void

appender_syslog_getFacility ( appender);

string appender;

Get the syslog facility for the given appender

facility=`appender_syslog_getFacility myAppender`

string

appender_syslog_getHost ( index);

integer index;

(stub function) Get the syslog host of the specified appender

host=`appender_syslog_getHost myAppender`

void

`appender_syslog_setFacility (`	`appender`,
	`facility)`;

`string`	`appender;`
`string`	`facility;`

Set the syslog facility for the given appender

appender_syslog_setFacility myAppender local4`

void

`appender_syslog_setHost (`	`appender`,
	`host)`;

`string`	`appender;`
`string`	`host;`

(stub function) Set the syslog host for the given appender

appender_syslog_setHost myAppender localhost`

9. Thread

Table 5.9. Thread

string

logger_getThreadName ( );

Gets the current thread name.

threadName=`logger_getThreadName`

void

logger_popThreadName ( );

Removes the topmost thread name from the stack. The next thread name on the stack is then placed in the __log4sh_threadName variable. If the stack is empty, or has only one element left, then a warning is given that no more thread names can be popped from the stack.

logger_popThreadName

void

logger_pushThreadName ( threadName);

string threadName;

Sets the thread name (eg. the name of the script) and pushes the old on to a stack for later use. This thread name can be used with the '%t' conversion character within a PatternLayout.

logger_pushThreadName "myThread"

void

logger_setThreadName ( threadName);

string threadName;

Sets the thread name (e.g. the name of the script). This thread name can be used with the '%t' conversion character within a PatternLayout.

logger_setThreadName "myThread"

10. Trap

Table 5.10. Trap

void

log4sh_cleanup ( );

This is a cleanup function to remove the temporary directory used by log4sh. It is provided for scripts who want to do log4sh cleanup work themselves rather than using the automated cleanup of log4sh that is invoked upon a normal exit of the script.

log4sh_cleanup

Chapter 6. Conclusion

The idea of log4sh is obviously not novel, but the availibility of such a powerful logging framework that is available in (nearly) pure shell is. Hopefully you will find it useful in one of your projects as well.

If you like what you see, or have any suggestions on improvements, please feel free to drop me an email at <kate.ward@forestent.com>.

Log4sh is licensed under the GNU Lesser Public License. The contents and copyright of this document and all provided source code are owned by Kate Ward.