PDReadLog(3) Impressario PDReadLog(3)NAME
PDReadLog, PDLocalReadLog, PDLocalWriteLog - reads/writes printer log
entries
SYNOPSIS
#include <pod.h>
int PDReadLog(const char *printer_name,
int num_entries,
PDLogStruct **log_entriesp,
time_t *mod_timep);
int PDLocalReadLog(const char *printer_name,
int num_entries,
PDLogStruct **log_entriesp,
time_t *mod_timep);
int PDLocalWriteLog(const char *printer_name,
const char *job_id,
const char *username,
PDMessageStruct *log_msg);
DESCRIPTIONPDReadLog and PDLocalReadLog attempt to read num_entries entries from the
specified printer's log file. The functions fill an array of PDLogStruct
structures, one for each log entry. log_entriesp is set to point to this
array of log entries. The log entries are read starting with the last
entry and proceeding back in time toward the beginning of the log file.
The first element in the returned log_entriesp array represents the most
recent entry in the log file. If num_entries is specified as PD_LOG_ALL,
all entries in the log file will be read. mod_timep is set to the time
the printer log information was last modified (see time(2)).
PDLocalWriteLog appends the log entry to the end of the specified
printer's log file. If the job_id and username are not known, they may be
specified as NULL. A time stamp is automatically generated for the log
entry.
The local functions are designed for use with local printers only. Refer
to the libpod(3) man page for more information.
The PDLogStruct structure is defined as follows.
typedef struct _pdLogStruct {
time_t time_stamp; /* Log entry time stamp */
char *job_id; /* Job ID */
char *username; /* Job owner's user name */
PDMessageStruct entry; /* Log entry */
} PDLogStruct;
Page 1
PDReadLog(3) Impressario PDReadLog(3)
time_stamp Time stamp string indicating when the log entry was
recorded. This is the time as returned by time(2).
This value can be converted into a time string using
the ctime(3) function.
job_id Print job ID assigned by the printer spooling system.
This field may be NULL if no job ID was specified
when the log entry was written.
username User name of the print job owner. This field may be
NULL if no username was specified when the log entry
was written.
entry Log entry message.
The PDMessageStruct is defined as follows.
typedef struct _pdMessageStruct {
int message_code;
char message_text[PD_STR_MAX];
} PDMessageStruct;
message_code Error, warning or information message code ID (see
pod.h).
message_text Text for the message truncated to a length of
PD_STR_MAX-1.
RETURN VALUEPDReadLog and PDLocalReadLog return the number of log file entries
actually read if the function call was successful. PDLocalWriteLog
returns 0 if the call was successful. All functions return -1 and set
PDerrno if an execution error has occurred.
EXECUTION ERROR CODES
PDLocalReadLog and PDReadLog will fail under the following circumstances.
PD_LIBERR_BAD_PNAME A NULL or empty printer name string has been
specified.
PD_LIBERR_BAD_NENTRIES An invalid number of log entries has been
specified for reading.
PD_LIBERR_LOG_READ The log file could not be opened for reading or
an error occurred while reading the file.
In addtion, PDReadLog will fail under the following circumstance.
PD_LIBERR_NO_PRINTER The specified printer has not been registered
with the printer spooling system and is,
therefore, inaccessible.
Page 2
PDReadLog(3) Impressario PDReadLog(3)
PD_LIBERR_BAD_HOSTNAME The network address of the specified hostname
could not be found.
PD_LIBERR_NETWORK For an unknown reason, a network connection
could not be made with the remote printer host.
PD_LIBERR_NET_TIMEOUT A timeout occurred while attempting to
communicate with the remote printer host.
PD_LIBERR_NET_INTR The program has been interrupted while
attempting to communicate with the remote
printer host.
PD_LIBERR_NET_NOTREG The podd daemon is not registered on the remote
printer host.
PD_LIBERR_NET_PMAP The port mapper daemon failed on the remote
printer host.
PD_LIBERR_NET_NOPROC The client has called a libpod function that is
not supported by the podd daemon on the remote
printer host.
PD_LIBERR_NET_CLNTXDR The libpod library XDR routines and the kernel's
XDR routines are incompatible.
PD_LIBERR_NET_SVCXDR The podd daemon XDR routines and the remote
printer host's kernel XDR routines are
incompatible.
PD_LIBERR_NET_RPCMATCH The version of RPC software on the client is
incompatible with the version on the remote
printer host.
PD_LIBERR_NET_PROCMATCH The version of the specified libpod function on
the client is incompatible with the version on
the remote printer host.
PDLocalWriteLog will fail under the following circumstances.
PD_LIBERR_BAD_STRUCT A NULL structure pointer has been specified.
PD_LIBERR_BAD_PNAME A NULL or empty printer name string has been
specified.
PD_LIBERR_LOG_WRITE The log file could not be opened for writing or
an error occurred while writing the file.
Page 3
PDReadLog(3) Impressario PDReadLog(3)WARNINGS
1. Upon successful execution, the PDReadLog and PDLocalReadLog
functions sets log_entriesp to point to an array of log file
entries. The storage for this array will be reallocated with
subsequent calls to these functions. To preserve the array of log
entries across subsequent calls, they should be copied to user-
allocated storage.
2. The function PDReadLog calls the libspool function SLGetPrinterInfo.
This libspool function is not reentrant. This means that any pointer
returned by a previous call to SLGetPrinterInfo will be invalid
after a call to PDReadLog.
NOTE
Since the POD files are owned by the lp account, super-user or lp account
privilege is required to successfully call the PDLocalWriteLog function.
FILES
/var/spool/lp/pod/[printer name].log
SEE ALSOlibpod(3), time(2), ctime(3)
Page 4
