The system logger API library module has the file name sys_log.c. This module provides a multi-user/system message logging service. System log messages are sent to the system log server which logs the messages for many computers.
The Unix/Linux version of this API uses the TCP Berkeley socket interprocess communication method. The Windows version of this API uses the Winsock interprocess communication method. The QNX 4.x version of this API uses it's own message passing IPC method.
Normally, this API would be a client of the client IPC API. Since both client and server IPC API's use the same function names, a program bound to the server API could not also bind to the client API in the same program. For this reason, this API does not use the client IPC API. It does, however use the low level TCP functions contained in the module ipcomm.c (TCP only).
Any mention of QNX in this documentation refers to the QNX 4.x OS.
This module contains the following global data:
All logging function calls will immediately return if the log switch is off. All system logger codes and defines are located in the include file sys_log.h.
The system log server uses a primary and alternate log file. If the primary log file is locked or has been held open, log messages will be written to the alternate log file. The system log server usually keeps the log files closed in between writes.
This system logger API uses the socloc interface (TCP only). Automatic failover of a system log server has been built into this API providing that there is another system log server available (TCP only). This API requires a minimum of one running socloc server (TCP only). A valid socloc startup file must also be present in the current directory.
This API is not coded to use the logging manager API, it uses the personal logger API for all messages.
Here is a list of functions in the system logger API library module:
The following modules are required along with this module:
Just make sure you compile and link this module along with the other required modules.
This module requires the header files:
The header sys_log.h is automatically included from the header file enhlib.h which is automatically included from header file stdhead.h except in the case of the DOS platform which does not have a system log server or sys_log API.
Prototype : int sys_log_init(char *apname)
Parameters :
Name : apname
Description: application name
Returns : sys_log code
This function starts the sys_log API. Since this API uses the socloc interface, the socloc API function sloc_initialize must have already been successfully called before calling this function. After the socloc interface has been validated by calling the function sloc_is_init, the first responding system log server is found by calling the socloc function sloc_find. If the find is successful, the host name and port number of the responding system log server are loaded into the module global variables. The QNX version uses the built in nameloc service and does not require socloc. The application name parameter must contain the current application name.
Prototype : void sys_log_end(void)
This function will stop the sys_log API by turning off the sys_log_islog switch. The module global variables containing the system log server host name and TCP port number are also cleared.
Prototype : int sys_log(char *fmt,...)
Parameters :
Name : fmt
Description: printf style format string
Returns : sys_log code
This function will send a request to the sys_log server to log a message. The function sys_log_init must have already been called to activate the sys_log API. It is ok to have spaces in the message. Do not use the single quote in your message as this will confuse the parser. This function automatically surrounds the message in single quotes.
Prototype : int sys_log_nf(char *mes)
Parameters :
Name : mes
Description: message text
Returns : sys_log code
This function behaves just like sys_log except that the function does not allow a variable number of arguments.
Prototype : int sys_log_status(void) Returns : SYS_LOG_OK upon success, another sys_log code otherwise
This function will send the SYS_LOG_STATUS request to the system log server.
Prototype : int sys_log_stop(char *paswd)
Parameters :
Name : passwd
Description: password string
Returns : SYS_LOG_TERM if successful, sys_log code otherwise
This function will halt the system log server. The server password is expected in the password string.
Prototype : int sys_log_lock(void) Returns : SYS_LOG_OK if successful, sys_log code otherwise
This function will lock the system log server primary log file. Once the primary log file is locked, no other changes will be accepted by the system log server. The log server will record all log messages to the alternate log file while the primary log file is locked. It is the callers responsibility to unlock the primary log file once you are done.
Prototype : int sys_log_unlock(void) Returns : SYS_LOG_OK if successful, sys_log code otherwise
This function will unlock the system log server primary log file. The primary log file must have already been locked.
Prototype : int sys_log_open(void) Returns : SYS_LOG_OK if successful, sys_log code otherwise
This function will open the system log server primary log file. This log file will remain open until it is closed by the caller using the function sys_log_close. While the system log server primary log file is left open, all subsequent messages sent to the log server will be written to the system log server alternate log file.
Prototype : int sys_log_close(void) Returns : SYS_LOG_OK if successful, sys_log code otherwise
This function will close the system log server primary log file. The primary log file must have been already opened by calling the function sys_log_open.
Prototype : int sys_log_delete(char *paswd)
Parameters :
Name : passwd
Description: password string
Returns : SYS_LOG_OK if successful, sys_log code otherwise
This function will delete the system log server primary log file. The server password is required in the password string.
Prototype : int sys_log_log_off(void) Returns : SYS_LOG_NOT_IMPLEMENTED
This function normally would turn logging off. The function is present only for common code compliance and does not make sense in this API. For this reason, this function always returns SYS_LOG_NOT_IMPLEMENTED.
Prototype : int sys_log_log_on(char *lfname)
Parameters :
Name : lfname
Description: log file name
Returns : SYS_LOG_NOT_IMPLEMENTED
This function normally would turn logging on. The function is present only for common code compliance and does not make sense in this API. For this reason, this function always returns SYS_LOG_NOT_IMPLEMENTED.
Prototype : int sys_log_log_status(int *lflag, char *lfname)
Parameters :
Name : lflag
Description: returned log flag
Name : lfname
Description: returned primary and alternate log file names
Returns : SYS_LOG_OK if successful, sys_log code otherwise
This function will obtain and return the current log flag, primary log file name and alternate log file name from the currently connected system log server. The log file names (primary and alternate) are placed into lfname in comma delimited format. Lfname must already be allocated to sufficient size by the caller.
Prototype : int sys_log_service_name(char *sname)
Parameters :
Name : sname
Description: returned service name
Returns : SYS_LOG_OK if successful, sys_log code otherwise
This function will obtain and return the service name of the currently connected system log server. This service name is always sys_log (/sys_log for QNX). The parameter sname must already be allocated to sufficient size for the returned service name.
Prototype : int sys_log_version(char *ver)
Parameters :
Name : ver
Description: returned version string
Returns : SYS_LOG_OK if successful, sys_log code otherwise
This function will obtain and return the version string of the currently connected system log server. The parameter ver must already be allocated to sufficient size for the returned version string.
Prototype : int is_sys_log_active(void) Returns : log switch sys_log_islog
This function determines whether the system logger API is active by returning the value of the sys_log_islog flag.
Prototype : void sys_log_console(int flag)
Parameters :
Name : flag
Description: logging flag
This function will set whether logging output will be sent to the console/screen. Output will be turned off if the logging flag is zero. Any other value will cause the output to be turned on. Note that console output is off by default.
Prototype : int sys_log_get_console(void) Returns : console output flag
This function will obtain and return the console output flag.
Prototype : void sys_log_get_active(char *hname, int *port)
Parameters :
Name : hname
Description: returned host name
Name : port
Description: returned TCP port number
This function will obtain and return the host name and TCP port number of the currently connected system log server. The parameter hname must already be allocated to sufficient size for the returned host name. This function applies to the TCP IPC method only.
Prototype : int sys_log_trans_num(long *transout)
Parameters :
Name : transout
Description : returned transaction count
Returns : SYS_LOG_OK if successful, sys_log code otherwise
This function will get the system log server transaction count. Upon success the transaction count will be loaded into the returned transaction count.
Prototype : int sys_log_connect_num(int *connectout)
Parameters :
Name : connectout
Description : returned connection count
Returns : SYS_LOG_OK if successful, sys_log code otherwise
This function will get the system log server connection count. Upon success the connection count will be loaded into the returned connection count.
Prototype : static int sys_log_sr_code(int typ, char *parm)
Parameters :
Name : typ
Description: system log send code
Name : parm
Description: command parameters
Returns : SYS_LOG_OK if successful, sys_log code otherwise
This private function will attempt to send a request to a system log server that returns only a reply code. This function makes sure the system log interface is active and sends the command using the function sys_log_lsr_code. The send command is in a loop detecting a socket error which indicates a failure in the currently connected system log server. If a socket error is detected, the function sys_log_failover is called to select another system log server. (TCP only)
Prototype : static int sys_log_sr_char(int typ, char *parm, char *cout)
Parameters :
Name : typ
Description: system log send code
Name : parm
Description: command parameters
Name : cout
Description: returned string value
Returns : SYS_LOG_OK if successful, sys_log code otherwise
This private function will attempt to send a request to a system log server that returns a string in addition to the reply code. This function makes sure the system log interface is active and sends the command using the function sys_log_lsr_char. The send command is in a loop detecting a socket error which indicates a failure in the currently connected system log server. If a socket error is detected, the function sys_log_failover is called to select another system log server (TCP only).
Prototype : static int sys_log_lsr_code(int typ, char *parm)
Parameters :
Name : typ
Description: system log send code
Name : parm
Description: command parameters
Returns : SYS_LOG_OK if successful, sys_log code otherwise
This private function will attempt to send a request to a system log server that returns only a reply code. The function calls sys_log_client_connect to establish a connection with the current system log server (TCP only).
Prototype : static int sys_log_lsr_char(int typ, char *parm, char *cout)
Parameters :
Name : typ
Description: system log send code
Name : parm
Description: command parameters
Name : cout
Description: returned string value
Returns : SYS_LOG_OK if successful, sys_log code otherwise
This private function will attempt to send a request to a system log server that returns a string in addition to the reply code. The function calls sys_log_client_connect to establish a connection with the current system log server (TCP only).
Prototype : static int sys_log_failover(int dflag)
Parameters :
Name : dflag
Description: delete system log server flag
Returns : SYS_LOG_OK if successful, sys_log code otherwise
This private function will delete the current system log server entry registered with socloc using the function sloc_delete. This deletion will only be attempted when dflag is high. Another responding system log server will try to be found by calling the function sloc_find. If the find is successful, the host name and TCP port number of the new responding system log server will be loaded into the module global variables. This function applies to the TCP IPC method only.
Prototype : static int sys_log_client_connect(void) Returns : TRUE upon success, FALSE otherwise
This private function will attempt to connect to the current system log server. This function applies to the TCP IPC method only.