PDReadLog(3)
PDReadLog, PDLocalReadLog, PDLocalWriteLog - reads/writes printer log entries
As shipped in IRIX 6.5.5. Unchanged since IRIX 6.5.
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); DESCRIPTION PDReadLog 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; 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 VALUE PDReadLog 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. 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. 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 ALSO libpod(3), time(2), ctime(3)