probe or kprobe Kernel Service

Purpose

Logs errors with symptom strings.

Library (for probe)

Run-time Services Library.

Syntax

#include <sys/probe.h>
or
#include <sys/sysprobe.h>
int probe ( probe_p)
probe_t *probe_p

int kprobe (probe_p)
probe_t *probe_p

Description

The probe subroutine logs an entry to the error log. The entry consists of an error log entry as defined in the errlog subroutine and the err_rec.h header file, and a symptom string.

The probe subroutine is called from an application, while kprobe is called from the Kernel and Kernel extensions. Both probe and kprobe have the same interfaces, except for return codes.

IBM® software should use the sys/sysprobe.h header file while non-IBM programs should include the sys/probe.h file. This is because IBM symptom strings must conform to different rules than non-IBM strings. It also tells any electronic support application whether or not to route the symptom string to IBM's Retain database.

Parameters

Item Description
probe_p is a pointer to the data structure which contains the pointer and length of the error record, and the data for the probe. The error record is described under the errlog subroutine and defined in err_rec.h.

The first word of the structure is a magic number to identify this version of the structure. The magic number should be set to PROBE_MAGIC.

Note: PROBE_MAGIC is different between probe.h and sysprobe.h to distinguish an IBM symptom string from a non-IBM string.

The probe data consists of flags which control probe handling, the number of symptom string keywords, followed by an array consisting of one element for each keyword.

Flags

Item Description
SSNOSEND indicates this symptom string shouldn't be forwarded to automatic problem opening facilities. An example where SSNOSEND should be used is in symptom data used for debugging purposes.
nsskwd This gives the number of keywords specified (i.e.), the number of elements in the sskwds array.
sskwds This is an array of keyword/value pairs. The keywords and their values are in the following table. The I/S value indicates whether the keyword and value are informational or are part of the logged symptom string. The number in parenthesis indicates, where applicable, the maximum string length. 
keyword          I/S   value   type   Description

SSKWD_LONGNAME   I     char *  (30)   Product's long name
SSKWD_OWNER      I     char *  (16)   Product's owner
SSKWD_PIDS       S     char *  (11)   product id.
(required for IBM symptom strings)
SSKWD_LVLS       S     char *  (5)    product level 
																			(required for IBM symptom strings)
SSKWD_APPLID     I     char *  (8)    application id.
SSKWD_PCSS       S     char *  (8)    probe id 
																			(required for all symptom strings)
SSKWD_DESC       I     char *  (80)   problem description
SSKWD_SEV        I     int            severity from 
																			1 (highest) to 4 (lowest).
																		  3 is the default.
SSKWD_AB         S     char *  (5)    abend code
SSKWD_ADRS       S     void *         address. If used at all, 
																			this should be a relative address.
SSKWD_DEVS       S     char *  (6)    Device type
SSKWD_FLDS       S     char *  (9)    arbitrary character string. 
																			This is usually a field name and
                                      the SSKWD_VALUE 
																			keyword specifies the value.
SSKWD_MS         S     char *  (11)   Message number
SSKWD_OPCS       S     char *  (8)    OP code
SSKWD_OVS        S     char *  (9)    overwritten storage
SSKWD_PRCS       S                    unsigned long return code
SSKWD_REGS       S     char *  (4)    Register name (e.g.) 
																			GR15 or LR unsigned long Value
SSKWD_VALU       S
SSKWD_RIDS       S     char *  (8)    resource or module id.
SSKWD_SIG        S .   int            Signal number
SSKWD_SN         S     char *  (7)    Serial Number
SSKWD_SRN        S     char *  (9)    Service Req. Number If specified,
																			and no error is logged,
                                      a hardware error is assumed.
SSKWD_WS         S     char *  (10)   Coded wait
Note: The SSKWD_PCCS value is always required. This is the probe id. Additionally, for IBM symptom strings, the SSKWD_PIDS and SSKWD_LVLS keywords are also required

If either the erecp or erecl fields in the probe_rec structure is 0 then no error logging record is being passed, and one of the default templates for symptom strings is used. The default template indicating a software error is used unless the SSKWD_SRN keyword is specified. If it is, the error is assumed to be a hardware error. If you don't want to log your own error with a symptom string, and you want to have a hardware error, and don't want to use the SSKWD_SRN value, then you can supply an error log record using the error identifier of ERRID_HARDWARE_SYMPTOM, see the /usr/include/sys/errids.h file.

Return Values for probe Subroutine

Item Description
0 Successful
-1 Error. The errno variable is set to
EINVAL Indicates an invalid parameter
EFAULT Indicates an invalid address

Return Values for kprobe Kernal Service

Item Description
0 Successful
EINVAL Indicates an invalid parameter

Execution Environment

probe is executed from the application environment.

kprobe is executed from the Kernel and Kernel extensions. Currently, kprobe must not be called with interrupts disabled.

Files

Item Description
/usr/include/sys/probe.h Contains parameter definition.