Man Pages

---

Back to Software Index  Manpage Top Level

Name

Synopsis

voidcfht_log(who,type,message)

voidcfht_logv(who,type,fmt,arg1...)

intwho;

inttype;

char*message;

char*fmt;

libcfht.a

Description

cfht_logv() allows printf(3) type syntax from the variable arg list arg1, ... .

message should not be period or "\n" terminated or prefaced with program identification. All three will happen automatically. Calls from library routines must identify the routine in use in a standard way. For example, a call from a procedure named cfp_init() should look like:

cfht_logv(CFHT_LIBCFP, CFHT_LOGONLY,

(cfp_init:%d) missing CPU, __LINE__);

The who argument identifies whether the caller is the main program or a specified library. who should be one of the following:

CFHT_MAIN

the caller is the main program. This should be used for all calls from normal user programs.

CFHT_LIB

the caller is an unregistered library (not found in the rest of this list).

CFHT_LIBCAMAC

the caller is the CAMAC library.

CFHT_LIBCCD

the caller is the ccd control library.

CFHT_LIBCFHT

the caller is the cfht library.

CFHT_LIBCFP

the caller is the configuration file parser part of the cfht library.

CFHT_LIBFF

the caller is the fits library.

CFHT_LIBHH

the caller is the high level HP-IB library.

CFHT_LIBMUSIC

the caller is the music library imported from Lick.

CFHT_LIBOCS

the caller is the Observatory Communications System library.

CFHT_LIBRET

the caller is the reticon library.

The type parameter identifies the kind or severity of a message and its destination. There are currently two destinations for messages. All messages are added to a log file that is maintained as a circular buffer (roll file). In addition messages that are of interest to the operator are displayed in a feedback window on the user’s console. The type parameter is one of the following:

CFHT_LOG_ID

This type is special and is used to identify the program in all following cfp_log() or cfp_logv() calls during this execution. message will be prepended to all future messages along with some other stuff. It is intended that this type be used before any other type and that it contain the program name. Only the real program code should make this call. Libraries should assume that it is already done for them. This call is an exception in that nothing is added to the log file. Note that cfp_parse(3) will automatically make this call.

CFHT_START

This type is used to log the program invocation and its parameters. message should be a concatenation of all argv’s. Only the real program code should make this call. Libraries should assume that it is already done for them. message is output to the log file and the feedback window in the normal color. Note that cfp_parse(3) will automatically make this call.

CFHT_DONE

This is the final message before a successful completion. Usally an exit(EXIT_PASS); will follow. message will be logged and displayed in the normal color.

CFHT_STATUS

This is a status message meant to inform the user of program progress. message will be logged and displayed (if status display is not disabled by the environment variable CFHTNODISP). This message will be in the normal color.

CFHT_WARN

This level of message is an indication that something is not right, but that execution is continuing anyway. It may indicate an unexpected configuration, the potential for collecting bogus data, or that for some reason the results may not be as expected. The observer should be made aware of the situation so that they can decide whether to continue. The message is displayed in the warning color and logged.

CFHT_ERROR

This is a true error message meant for users to see. These messages will be logged always, but display can be disabled by setting the CFHTERROR environment variable to a "False" value. This message will be in the error color.

This

type should only appear in real program code. Libraries should log their diagnostic information using the CFHT_LOGONLY type. The intent is that the code level that understands the context should issue this message to the operator, usually just before an exit(EXIT_FAIL); call or a punt and restart in a server. The CFHT_ERROR message is similar to the CFHT_DONE message except it is for terminal error conditions. An error occurred which will probably result in corrupt information or failed exposure. It indicates that the operator must fix something. If a hardware problem is described, hardware adjustments are probably needed. If a software problem is described, a phone call should probably be next. In both cases, the detailed information on what happened should have already been logged using CFHT_LOGONLY messages. The CFHT_ERROR message should be from a procedure near the top of the procedure call stack since that is where the context is understood. For example, a call to cfp_parse(3) might look like:

if ((id = cfp_parse(CFP_PAR, argc, argv))

== FAIL) {

cfp_log(CFHT_MAIN, CFHT_ERROR, par file error);

exit(EXIT_FAIL);

The

libcfp routines will have already logged details on why the error occurred using CFHT_LOGONLY messages.

CFHT_ERRNO

Identical to CFHT_ERROR except that a perror(3) style message based on errno will be appended to message. The errno based message will be in parentheses preceded with a space.

This

type should not be used in new code and should be removed from old code. If the code has just done a system call that failed leaving a value in errno, use a CFHT_LOGONLY message including a call to strerror(3) instead (see CFHT_LOGONLY).

CFHT_FATAL

This type is historical. It is currently the same as CFHT_ERROR and should be removed from any code that uses it.

CFHT_LOGONLY

This is a log message normally not meant for users to see. message is output to the log file only. It should be used to enter program status information or programmer level diagnostics into the log file. In general there should be a CFHT_LOGONLY type message before any return(FAIL); or return(NULL); error return explaining why the error occurred so the programmer can look at it later. If a failed system call has just occurred, message should include a translation of errno, using a strerror(errno) call, as in

cfht_logv(CFHT_LIBCFP, CFHT_LOGONLY,

(cfp_init:%d) par open ’%s’ failed (%s),

__LINE__, FilePath, strerror(errno));

so that the correct

errno value will be included in the log.

This

type should be used any time the program knows that something worth recording has just happened. In general it should indicate the reason for some external error, not a program error. It should not be used for tracing program execution or to record values that might be nice to have if the program ever fails; that is provided by CFHT_DEBUG.

CFHT_DEBUG

This is a debug message never meant for users to see. message will be written to the log file only if environment variable(s) is/are set to enable debug logging (see ENVIRONMENT VARIABLES). (In the future a separate window will pop up showing these messages. This window will have a larger scroll region and may be backed up by a separate file which is not a circular buffer.)

This

type should be used to do the kinds of things one uses

#ifdef DEBUG

printf("index=%d, answer=%s\n"", index, answer);"

#endif

for in stand alone programs while debugging. This call adds very little

overhead and should be used to record any values that might be nice to have if you need to debug the program. It is meant to be enabled after a problem is occurring, by a programmer, to help see why the code is acting the way it is. It is not meant to explain why an external error has occurred; that is provided by CFHT_LOGONLY.

CFHT_TIMING

This is a message normally not meant for users to see. Two elapsed time values will be placed at the end of the log message, the first of which is the elapsed time in seconds since the last call to cfht_log() or cfht_logv() with the CFHT_LOG_ID type, and the second is the elapsed time in seconds since the last call to cfht_log() with the CFHT_TIMING type. Note that if any intervening library routines also have calls of this type in them, then unexpected (smaller) values may result for the second time.

There will also be some special network logging types in the network version.

Colors

Return Value

Errors

Environment Variables

CFHTERROR

When set to "Off" or some other recognizably false value, CFHT_ERROR, CFHT_ERRNO, and CFHT_WARN messages will not be displayed or logged. When unset or "On" errors and warnings will be both displayed and logged.

CFHTWARN

When set to "Off" or some other recognizably false value, CFHT_WARN messages will not be displayed or logged. When unset or "On" warnings will be both displayed and logged.

CFHTNODISP

When set to "On" or some other recognizably true value, no CFHT_STATUS messages will be displayed but they will continue to be logged. This is used by controllers to suppress handler messages. When unset or "Off" these messages will be displayed and logged.

CFHTDEBUG

When set to "On" or some other recognizably true value, CFHT_DEBUG messages from CFHT_MAIN callers will be logged. When unset or "Off" these messages will be ignored.

CFHTLIB

When set to "On", CFHT_DEBUG messages from all libraries will be logged. When unset or "Off" these messages will be ignored.

CFHTLIBxxx

When set to "On" the CFHT_DEBUG messages for library xxx will be logged. When unset or "Off" these messages will be ignored.

CFHTLOGU

This variable should always be set to the file specification for the display file. It is usually set to the named pipe aimed at the feedback window (.,session.np). For debugging it can be pointed at any file, to which messages will be appended. When unset "display" messages are ignored.

CFHTLOGS

This variable should always be set to the file specification for the system log file. It is usually set to the named pipe aimed at the "roll file" (/tmp/pipes/syslog.np). For debugging it can be pointed at any file, to which messages will be appended. When unset "log" messages are ignored.

When both CFHTLOGU and CFHTLOGS are unset, the display output (i.e., CFHTLOGU output) is written to stderr. In addition, if any debugging variables are set (i.e., CFHTDEBUG, CFHTLIB, or CFHTLIBxxx is "On"), the affected CFHT_DEBUG messages plus all CFHT_LOGONLY from the affected modules will also appear on stderr.

The CFHTLOGU and CFHTLOGS variables apply to the old, non-network logging mechanism. I don’t know yet how network logging works. (What is the way one gets reasonable local debugging support under network logging? Now one can set CFHTLOGU or CFHTLOGS to a log file or just never set them to anything.)

Example

cfht_log(CFHT_MAIN, CFHT_LOG_ID, tcs);

.

.

.

cfht_log(CFHT_MAIN, CFHT_STATUS, Dome opening complete);

would display something like:

tcs: Dome opening complete.

and would log something like:

username 10:29:14.21, (status) - tcs: Dome opening complete.

See Also

Warnings

Table of Contents

• Name
• Synopsis
• Description
• Colors
• Return Value
• Errors
• Environment Variables
• Example
• See Also
• Warnings