home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / PDReadLog.z / PDReadLog
Encoding:
Text File  |  1998-10-30  |  12.1 KB  |  265 lines
  1.  
  2.  
  3.  
  4. PPPPDDDDRRRReeeeaaaaddddLLLLoooogggg((((3333))))                     IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                      PPPPDDDDRRRReeeeaaaaddddLLLLoooogggg((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      PDReadLog, PDLocalReadLog, PDLocalWriteLog - reads/writes printer log
  10.      entries
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ppppoooodddd....hhhh>>>>
  14.  
  15.      iiiinnnntttt PPPPDDDDRRRReeeeaaaaddddLLLLoooogggg((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr____nnnnaaaammmmeeee,,,,
  16.                    iiiinnnntttt nnnnuuuummmm____eeeennnnttttrrrriiiieeeessss,,,,
  17.                    PPPPDDDDLLLLooooggggSSSSttttrrrruuuucccctttt ********lllloooogggg____eeeennnnttttrrrriiiieeeesssspppp,,,,
  18.                    ttttiiiimmmmeeee____tttt ****mmmmoooodddd____ttttiiiimmmmeeeepppp))));;;;
  19.  
  20.      iiiinnnntttt PPPPDDDDLLLLooooccccaaaallllRRRReeeeaaaaddddLLLLoooogggg((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr____nnnnaaaammmmeeee,,,,
  21.                         iiiinnnntttt nnnnuuuummmm____eeeennnnttttrrrriiiieeeessss,,,,
  22.                         PPPPDDDDLLLLooooggggSSSSttttrrrruuuucccctttt ********lllloooogggg____eeeennnnttttrrrriiiieeeesssspppp,,,,
  23.                         ttttiiiimmmmeeee____tttt ****mmmmoooodddd____ttttiiiimmmmeeeepppp))));;;;
  24.  
  25.      iiiinnnntttt PPPPDDDDLLLLooooccccaaaallllWWWWrrrriiiitttteeeeLLLLoooogggg((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****pppprrrriiiinnnntttteeeerrrr____nnnnaaaammmmeeee,,,,
  26.                          ccccoooonnnnsssstttt cccchhhhaaaarrrr ****jjjjoooobbbb____iiiidddd,,,,
  27.                          ccccoooonnnnsssstttt cccchhhhaaaarrrr ****uuuusssseeeerrrrnnnnaaaammmmeeee,,,,
  28.                          PPPPDDDDMMMMeeeessssssssaaaaggggeeeeSSSSttttrrrruuuucccctttt ****lllloooogggg____mmmmssssgggg))));;;;
  29.  
  30. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  31.      _P_D_R_e_a_d_L_o_g and _P_D_L_o_c_a_l_R_e_a_d_L_o_g attempt to read _n_u_m__e_n_t_r_i_e_s entries from the
  32.      specified printer's log file. The functions fill an array of _P_D_L_o_g_S_t_r_u_c_t
  33.      structures, one for each log entry. _l_o_g__e_n_t_r_i_e_s_p is set to point to this
  34.      array of log entries. The log entries are read starting with the last
  35.      entry and proceeding back in time toward the beginning of the log file.
  36.      The first element in the returned _l_o_g__e_n_t_r_i_e_s_p array represents the most
  37.      recent entry in the log file. If _n_u_m__e_n_t_r_i_e_s is specified as PPPPDDDD____LLLLOOOOGGGG____AAAALLLLLLLL,
  38.      all entries in the log file will be read.  _m_o_d__t_i_m_e_p is set to the time
  39.      the printer log information was last modified (see _t_i_m_e(_2)).
  40.  
  41.      _P_D_L_o_c_a_l_W_r_i_t_e_L_o_g appends the log entry to the end of the specified
  42.      printer's log file. If the _j_o_b__i_d and _u_s_e_r_n_a_m_e are not known, they may be
  43.      specified as NNNNUUUULLLLLLLL. A time stamp is automatically generated for the log
  44.      entry.
  45.  
  46.      The local functions are designed for use with local printers only. Refer
  47.      to the _l_i_b_p_o_d(_3) man page for more information.
  48.  
  49.      The _P_D_L_o_g_S_t_r_u_c_t structure is defined as follows.
  50.  
  51.           typedef struct _pdLogStruct {
  52.               time_t time_stamp;      /* Log entry time stamp */
  53.               char *job_id;           /* Job ID */
  54.               char *username;         /* Job owner's user name */
  55.               PDMessageStruct entry;  /* Log entry */
  56.           } PDLogStruct;
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PPPPDDDDRRRReeeeaaaaddddLLLLoooogggg((((3333))))                     IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                      PPPPDDDDRRRReeeeaaaaddddLLLLoooogggg((((3333))))
  71.  
  72.  
  73.  
  74.      _t_i_m_e__s_t_a_m_p          Time stamp string indicating when the log entry was
  75.                          recorded. This is the time as returned by time(2).
  76.                          This value can be converted into a time string using
  77.                          the ctime(3) function.
  78.  
  79.      _j_o_b__i_d              Print job ID assigned by the printer spooling system.
  80.                          This field may be NNNNUUUULLLLLLLL if no job ID was specified
  81.                          when the log entry was written.
  82.  
  83.      _u_s_e_r_n_a_m_e            User name of the print job owner.  This field may be
  84.                          NNNNUUUULLLLLLLL if no username was specified when the log entry
  85.                          was written.
  86.  
  87.      _e_n_t_r_y               Log entry message.
  88.  
  89.      The _P_D_M_e_s_s_a_g_e_S_t_r_u_c_t is defined as follows.
  90.  
  91.           typedef struct _pdMessageStruct {
  92.               int message_code;
  93.               char message_text[PD_STR_MAX];
  94.           } PDMessageStruct;
  95.  
  96.  
  97.      _m_e_s_s_a_g_e__c_o_d_e        Error, warning or information message code ID (see
  98.                          _p_o_d._h).
  99.  
  100.      _m_e_s_s_a_g_e__t_e_x_t        Text for the message truncated to a length of
  101.                          PD_STR_MAX-1.
  102.  
  103. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  104.      _P_D_R_e_a_d_L_o_g and _P_D_L_o_c_a_l_R_e_a_d_L_o_g return the number of log file entries
  105.      actually read if the function call was successful.  _P_D_L_o_c_a_l_W_r_i_t_e_L_o_g
  106.      returns 0 if the call was successful. All functions return -1 and set
  107.      _P_D_e_r_r_n_o if an execution error has occurred.
  108.  
  109. EEEEXXXXEEEECCCCUUUUTTTTIIIIOOOONNNN EEEERRRRRRRROOOORRRR CCCCOOOODDDDEEEESSSS
  110.      _P_D_L_o_c_a_l_R_e_a_d_L_o_g and _P_D_R_e_a_d_L_o_g will fail under the following circumstances.
  111.  
  112.      PD_LIBERR_BAD_PNAME      A NULL or empty printer name string has been
  113.                               specified.
  114.  
  115.      PD_LIBERR_BAD_NENTRIES   An invalid number of log entries has been
  116.                               specified for reading.
  117.  
  118.      PD_LIBERR_LOG_READ       The log file could not be opened for reading or
  119.                               an error occurred while reading the file.
  120.  
  121.      In addtion, _P_D_R_e_a_d_L_o_g will fail under the following circumstance.
  122.  
  123.      PD_LIBERR_NO_PRINTER     The specified printer has not been registered
  124.                               with the printer spooling system and is,
  125.                               therefore, inaccessible.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PPPPDDDDRRRReeeeaaaaddddLLLLoooogggg((((3333))))                     IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                      PPPPDDDDRRRReeeeaaaaddddLLLLoooogggg((((3333))))
  137.  
  138.  
  139.  
  140.      PD_LIBERR_BAD_HOSTNAME   The network address of the specified hostname
  141.                               could not be found.
  142.  
  143.      PD_LIBERR_NETWORK        For an unknown reason, a network connection
  144.                               could not be made with the remote printer host.
  145.  
  146.  
  147.      PD_LIBERR_NET_TIMEOUT    A timeout occurred while attempting to
  148.                               communicate with the remote printer host.
  149.  
  150.      PD_LIBERR_NET_INTR       The program has been interrupted while
  151.                               attempting to communicate with the remote
  152.                               printer host.
  153.  
  154.      PD_LIBERR_NET_NOTREG     The podd daemon is not registered on the remote
  155.                               printer host.
  156.  
  157.      PD_LIBERR_NET_PMAP       The port mapper daemon failed on the remote
  158.                               printer host.
  159.  
  160.      PD_LIBERR_NET_NOPROC     The client has called a libpod function that is
  161.                               not supported by the podd daemon on the remote
  162.                               printer host.
  163.  
  164.      PD_LIBERR_NET_CLNTXDR    The libpod library XDR routines and the kernel's
  165.                               XDR routines are incompatible.
  166.  
  167.      PD_LIBERR_NET_SVCXDR     The podd daemon XDR routines and the remote
  168.                               printer host's kernel XDR routines are
  169.                               incompatible.
  170.  
  171.      PD_LIBERR_NET_RPCMATCH   The version of RPC software on the client is
  172.                               incompatible with the version on the remote
  173.                               printer host.
  174.  
  175.      PD_LIBERR_NET_PROCMATCH  The version of the specified libpod function on
  176.                               the client is incompatible with the version on
  177.                               the remote printer host.
  178.  
  179.      _P_D_L_o_c_a_l_W_r_i_t_e_L_o_g will fail under the following circumstances.
  180.  
  181.      PD_LIBERR_BAD_STRUCT     A NULL structure pointer has been specified.
  182.  
  183.      PD_LIBERR_BAD_PNAME      A NULL or empty printer name string has been
  184.                               specified.
  185.  
  186.      PD_LIBERR_LOG_WRITE      The log file could not be opened for writing or
  187.                               an error occurred while writing the file.
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PPPPDDDDRRRReeeeaaaaddddLLLLoooogggg((((3333))))                     IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                      PPPPDDDDRRRReeeeaaaaddddLLLLoooogggg((((3333))))
  203.  
  204.  
  205.  
  206. WARNINGS
  207.      1.   Upon successful execution, the _P_D_R_e_a_d_L_o_g and _P_D_L_o_c_a_l_R_e_a_d_L_o_g
  208.           functions sets _l_o_g__e_n_t_r_i_e_s_p to point to an array of log file
  209.           entries.  The storage for this array will be reallocated with
  210.           subsequent calls to these functions. To preserve the array of log
  211.           entries across subsequent calls, they should be copied to user-
  212.           allocated storage.
  213.  
  214.      2.   The function _P_D_R_e_a_d_L_o_g calls the _l_i_b_s_p_o_o_l function _S_L_G_e_t_P_r_i_n_t_e_r_I_n_f_o.
  215.           This _l_i_b_s_p_o_o_l function is not reentrant. This means that any pointer
  216.           returned by a previous call to _S_L_G_e_t_P_r_i_n_t_e_r_I_n_f_o will be invalid
  217.           after a call to _P_D_R_e_a_d_L_o_g.
  218.  
  219. NNNNOOOOTTTTEEEE
  220.      Since the POD files are owned by the lp account, super-user or lp account
  221.      privilege is required to successfully call the _P_D_L_o_c_a_l_W_r_i_t_e_L_o_g function.
  222.  
  223. FFFFIIIILLLLEEEESSSS
  224.      /var/spool/lp/pod/[printer name].log
  225.  
  226. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  227.      libpod(3), time(2), ctime(3)
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.