The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-LPR-1.007
River stage zero No dependents
++
/ Net::LPR

NAME

Net::LPR - Perl extension for printing to RFC1179-compliant print servers.

DESCRIPTION

This module implements a low-level interface into a line printer daemon connection. It implements all the commands listed in RFC 1179, including queue control commands and output file formatting commands.

COMMAND MODES

Some methods (see below) are only available in certain modes known as command modes. There are a series of command modes available that are reached by invoking certain methods. See the list here.

ROOT Command Mode

This command mode is entered after a connection has been established. The following methods are available only in this mode: print_waiting_jobs, send_jobs, get_queue_state, and remove_jobs.

JOB Command Mode

This command mode is entered via the send_jobs method. This mode is where commands regarding configuring a job to be printed can be executed. The following methods are available only in this mode: job_abort, and job_send_control_file. In addition, the job_send_data method is available in this mode.

DATA Command Mode

This command mode is used to send data. The job_send_data method is available in this mode, however only in its two-argument form. This mode will not be exited until all data for the job has been sent.

Some methods are available in all modes. These include connect, connected, disconnect, error, new_job, all the job_enable_*, job_get_*, job_mail_when_printed, job_mode_*, and job_set_* methods. NOTE: If you are disconnected for any reason, all jobs associated with the printer object are cleared and must be re-created.

NOTE: In order to be in a command mode, you must be connected. If you are disconnected, you must reconnect (thereby entering ROOT command mode) before sending any of these commands.

METHODS

Net::LPR is implemented with an object-oriented interface; as such, it is used by constructing objects and invoking methods. The following is the list of methods available.

Class Method: new

Example:

  use Net::LPR;
  
  my $lp = new Net::LPR (
    StrictRFCPorts => 1,
    RemoteServer => 'lp.foo.com',
    RemotePort => 515,
    PrintErrors => 0,
    RaiseErrors => 1,
  );

This class method is used to create an object that represents a remote print server. The object is returned as a scalar. It takes a series of key/value parameters that specify details about the remote printer. All the parameters are optional and have reasonable default values. Here's the list of valid parameters.

StrictRFCPorts

This paramter is a boolean. If true, the source port will be chosen from the range 721 through 731 as stated in RFC 1179. Note that on many UNIX systems, you need to be root to bind to ports below 1024. However some print servers will not accept a connection from a system unless the source port is in this range. If false, a source port is chosen via the OS's standard mechanism. Defaults to true.

RemoteServer

This parameter is the IP address or hostname of the remote print server. If not specified, it defaults to 127.0.0.1.

RemotePort

This parameter is the port number on the remote server to connect to. If not specified, it defaults to 515.

PrintErrors

This boolean parameter will tell Net::LPR to print any error messages to stderr. Defaults to false.

RaiseErrors

If true, any errors encountered will cause an exception to be thrown instead of the function returning a normal failure code. Defaults to false.

Instance Method: error

Example:

  print "The last error was: ".$lp->error()."\n";

This instance method returns the last error encountered for that object as a string. If no error has occured, the empty string is returned.

Instance Method: disconnect

Example:

  $lp->disconnect() or die "Can't disconnect: ".$lp->error();

This command disconnects from a remote printer and drops any current jobs. Returns true on success or undef on failure.

Instance Method: connect

Example:

  $lp->connect() or die "Can't connect: ".$lp->error();

If you're already connected to the printer, returns true immediately, otherwise attempts to connect to the remote printer. If the connection succeeds, Root command mode is entered and true is returned. In case of an error, undef is returned.

Instance Method: connected

Example:

  print "I am connected\n" if ($lp->connected());

Determines whether you are currently connected to the remote print server. Returns true if you are, or false if you aren't.

Instance Method: print_waiting_jobs

Example:

  $lp->print_waiting_jobs("my_lp_queue") or die "Can't send command:
".$lp->error();

Sends the "Print Any Waiting Jobs" command (RFC 1179 section 5.1), and subsequently disconnects from the printer. Accepts one argument, which is the name of the queue that is to begin printing. Returns true on success and undef on error. NOTE: To process any additional commands after this one, you must reconnect using the connect method above. This method is only available in the ROOT command mode.

Instance Method: send_jobs

Example:

  $lp->send_jobs("my_lp_queue");

Sends the "Receive A Printer Job" command (RFC 1179 section 5.2), and enters the JOB command mode. Accepts one argument, which is the name of the queue that is to receive the new job(s). Returns true on success and undef on error. This method is only available in the ROOT command mode.

Instance Method: get_queue_state

Example:

  $lp->get_queue_state("my_lp_queue");
  $lp->get_queue_state("my_lp_queue", 1);
  $lp->get_queue_state("my_lp_queue", 1, "dmlloyd", 302);

Sends the "Send Queue State (short)" or "Send Queue State (long)" command (RFC 1179 sections 5.3 and 5.4). This is similar to the lpq command. Accepts one or more arguments. The first argument is the name of the queue you are interested in. The optional second argument is a flag, where a true value is used to get the "long" form of the queue state, and false is for the "short" form. This information may be ignored by a printer or printer daemon. The additional arguments are an optional list of items that you are interested in. If none are specified, a full list is generated. Returns true on success and undef on error. After this command is processed, the connection to the printer is closed. NOTE: To process any additional commands after this one, you must reconnect using the connect method above. This method is only available in the ROOT command mode.

Instance Method: remove_jobs

Example:

  $lp->remove_jobs("my_lp_queue", "dmlloyd");
  $lp->remove_jobs("my_lp_queue", "dmlloyd", 120);

Sends the "Remove Jobs" command (RFC 1179 section 5.5). This is similar to the lprm command. It takes two or more arguments. The first argument is the name of the queue the job should be removed from. The second argument is the "Agent", or user ID whose job is to be deleted. The optional remaining arguments are a list of job IDs or user IDs whose jobs are to be deleted. Only the user "root" can remove other people's jobs. If no jobs are listed, the currently active job is removed. Returns true on success and undef on error. After this command is processed, the connection to the printer is closed. NOTE: To process any additional commands after this one, you must reconnect using the connect method above. This method is only available in the ROOT command mode.

Instance Method: new_job

Example:

  my $jobkey = $lp->new_job();
  my $jobkey = $lp->new_job(102);
  my $jobkey = $lp->new_job(102, "fake.hostname.com");

This method creates a control file for a new job. It takes zero to two arguments. The first argument is the job ID number for this job. If one is not specified, or undef is given, a job number is chosen that is one higher than the previous job, modulus 1000. The third argument is the hostname field of the job name. If none is specified, the system hostname as returned by hostname() is used. Returns the new job key (used below) on success, or undef on failure.

Instance Method: job_get_data_filename

Example:

  print "The data file is ".$lp->job_get_data_filename($jobkey)."\n";

This method returns the name of the data file associated with the job key specified in the first argument. Returns the file name on success, or undef on error.

Instance Method: job_set_data_filename

Example:

  $lp->job_set_data_filename($jobkey, "MyDataFileName");

This method allows you to override the default RFC-compliant naming convention for the data file with any name of your choosing. RFC 1179 section 6.3 specifies that the data file should start with ASCII "dfA", followed by a three-digit job number, followed by the hostname of the originating server. Care should be taken when using this method, because creating a nonstandard file name might confuse less intelligent printers or print servers. Returns true on success and undef on error.

Instance Method: job_get_control_filename

Example:

  print "The control file is ".$lp->job_get_control_filename($jobkey)."\n";

This method returns the name of the control file associated with the job key specified in the first argument. Returns the file name on success, or undef on error.

Instance Method: job_set_control_filename

Example:

  $lp->job_set_control_filename($jobkey, "MyCtrlFileName");

This method allows you to override the default RFC-compliant naming convention for the control file with any name of your choosing. RFC 1179 section 6.2 specifies that the control file should start with ASCII "cfA", followed by a three-digit job number, followed by the hostname of the originating server. Care should be taken when using this method, because creating a nonstandard file name might confuse less intelligent printers or print servers. Returns true on success and undef on error.

Instance Method: job_set_banner_class

Example:

  $lp->job_set_banner_class($jobkey, "MyClass");
  $lp->job_set_banner_class($jobkey, "");

This method sets the class name to be printed on the banner page of the job specified in the first argumnet, as per RFC 1179 section 7.1. If the argument is an empty string, an RFC-compliant printer will use the host name on which the file is printed. Returns true on success and undef on error.

Instance Method: job_set_hostname

Example:

  $lp->job_set_hostname($jobkey, "my.host.name");

This method sets the name of the host which is to be treated as the source of the print job specified in the first argment, as specified in RFC 1179 section 7.2. If this command is not given, the hostname as returned by hostname() is returned. Returns true on success and undef on error.

Instance Method: job_set_banner_name

Example:

  $lp->job_set_banner_name($jobkey, "My_Print_Job_Name");

This method sets the job name to be printed on the banner page of the job associated with the job key in the first argument, as per RFC 1179 section 7.4. Returns true on success and undef on error.

Instance Method: job_enable_banner_page

Example:

  $lp->job_enable_banner_page($jobkey, "dmlloyd");
  $lp->job_enable_banner_page($jobkey, "");

This method causes the banner page to be printed, as per RFC 1179 section 7.5. The first argument is the job whose banner page should be printed. The second argument is the username for this job, or an empty string. Returns true on success and undef on failure.

Instance Method: job_mail_when_printed

Example:

  $lp->job_mail_when_printed($jobkey, "dmlloyd");

This method causes mail to be sent to the user given as the second argument at the host specified with the job_set_hostname method, as specified in RFC 1179 section 7.6. Returns true on success and undef on failure.

Instance Method: job_set_source_filename

Example:

  $lp->job_set_source_filename($jobkey, "output.ps");

This method specifies the name of the file from which the data file associated with the first argument was or will be contstructed, as per RFC 1179 section 7.7. Returns true on success and undef on failure.

Instance Method: job_set_user_id

Example:

  $lp->job_set_user_id($jobkey, "dmlloyd");

This method sets the user identification of the entity requesting the printing jo, as per RFC 1179 section 7.8. If this method is not called, it defaults to the user name associated with the calling user's effective UID. Returns true on success and undef on failure.

Example:

  $lp->job_set_symlink_data($jobkey, 6, 13024);

This method is used to record symbolic link data on a UNIX system so that changing a file's directory entry after a file is printed will not print the new file, as per RFC 1179 section 7.9. The first argument is the job associated with the file. The second argument is the device number. The third argument is the inode number. Returns true on success and undef on failure.

Example:

  $lp->job_unlink($jobkey);

This method is used to indicate that the data file associated with this job is no longer needed, as specified in RFC 1179 section 7.11. Returns true on success and undef on failure.

Instance Methods: job_set_troff_*_font

Example:

  $lp->job_set_troff_r_font($jobkey, $rfilename);
  $lp->job_set_troff_i_font($jobkey, $ifilename);
  $lp->job_set_troff_b_font($jobkey, $bfilename);
  $lp->job_set_troff_s_font($jobkey, $sfilename);

These methods specify the filenames to use for the various troff fonts.

Instance Methods: job_mode_*

Example:

  $lp->job_mode_cif($jobkey);
  $lp->job_mode_dvi($jobkey);
  $lp->job_mode_text($jobkey);
  $lp->job_mode_text($jobkey, 75);
  $lp->job_mode_text($jobkey, 75, 8);
  $lp->job_mode_text($jobkey, 75, 8, 1);
  $lp->job_mode_text($jobkey, undef, undef, 1); # Print raw data
  $lp->job_mode_plot($jobkey);
  $lp->job_mode_ditroff($jobkey);
  $lp->job_mode_postscript($jobkey);
  $lp->job_mode_pr($jobkey);
  $lp->job_mode_pr($jobkey, "Title");
  $lp->job_mode_pr($jobkey, "Title", 75);
  $lp->job_mode_fortran($jobkey);
  $lp->job_mode_troff($jobkey);
  $lp->job_mode_raster($jobkey);

These methods specify the type of data inside the data file, as specifed in RFC 1179 sections 7.17 through 7.29. All the methods take one single argument, the job, except for job_mode_text and job_mode_pr. If none of these methods is called for a job, no output will be generated on the printer.

The optional second argument to job_mode_text is the line width, or undef to let the printer choose. The optional third argument is the indentation count, or undef to let the printer choose. The optional fourth argument is a boolean. If true, the printer will not strip out control charaters; in this way raw data can be sent to the printer.

The optional second argument to job_mode_pr is the job title. The optional third argument to job_mode_pr is the line width, or undef to let the printer choose.

This method returns true on success or undef on error.

Instance Method: job_send_control_file

Example:

  $lp->job_send_control_file($jobkey);

This method sends the control file, as constructed with the above methods, to the printer. Once the control file is sent, no further changes to the job can be made. This method can only be called in the JOB command mode. Returns true on success or undef on error.

Instance Method: job_send_data

Example:

  $lp->job_send_data($jobkey, $data);
  $lp->job_send_data($jobkey, $data, $totalsize); # only in JOB mode

This method sends data to the printer.

If the object is in JOB command mode, and the two-argument form is used, DATA command mode is entered and the printer continues to accept data until the connection is broken with the disconnect method, or by the Net::LPR object going out of scope or being destroyed. NOTE: Some printers may not accept the two-argument form, so it is recommended that you use the three-argument form to specify the length of your data.

If the object is in JOB command mode, and the three-argument form is used, the data is sent to the printer. If the length of data is less than the total size specified, DATA command mode is entered, and the printer will accept data until the total size has been satisfied, at which time JOB command mode will be re-entered.

If the object is in DATA mode, only the two-argument form is available. Passing the third argument in this mode will generate an error. In DATA mode, the data will be sent to the printer, and if the total size was specified, and the amount of data sent matches the total size, JOB command mode will be re-entered.

If you are sending multiple jobs to the same printer, you should disconnect and connect again after each job. This will ensure that the printer is in a consistant state.

You must be in JOB or DATA command mode to use this method. This method returns true on success or undef on error.

EXAMPLES

Here are some example scripts.

Example 1: Hello World

This example uses RaiseError to automatically die if an error occurs.

  #!/usr/bin/perl -w
  
  use strict;
  
  use Net::LPR;
  
  my $lp = new Net::LPR(
        StrictRFCPorts => 0,
        RemoteServer => 'localhost',
        RemotePort => 515,
        PrintErrors => 0,
        RaiseErrors => 1,
  );
  
  my $data = "Hello World";
  
  $lp->connect();
  
  my $jobkey = $lp->new_job();
  
  $lp->send_jobs('lp');
  $lp->job_mode_text($jobkey);
  $lp->job_send_control_file($jobkey);
  $lp->job_send_data($jobkey, $data, length($data));
  $lp->disconnect();

Example 2: Print a text file

This example does not automatically die when an error occurs; therefore we must check the return value of each method. Also, this example does not account for "stair-stepping" on UNIX platforms.

  #!/usr/bin/perl -w
  
  use strict;
  use vars '@ARGV';
  
  use Net::LPR;
  use IO::File;
  
  die "usage: $0 <filename> <printer> <queue>\n" if (@ARGV != 3);
  
  my $lp = new Net::LPR(
        StrictRFCPorts => 0,
        RemoteServer => $ARGV[1],
        RemotePort => 515,
        PrintErrors => 0,
        RaiseErrors => 0,
  ) or die "Can't create print context\n";
  
  my $fh = new IO::File $ARGV[0], O_RDONLY or die "Can't open $ARGV[0]: $!\n";
  my $size = ($fh->stat())[7]; # Hope file doesn't change while printing
  
  $lp->connect() or die "Can't connect to printer: ".$lp->error."\n";
  my $jobkey = $lp->new_job() or die "Can't create new job: ".$lp->error."\n";
  $lp->send_jobs('lp') or die "Can't send jobs: ".$lp->error."\n";
  # Can easily print postscript by changing method to job_mode_postscript
  $lp->job_mode_text($jobkey) or die "Can't set job mode to text: ".$lp->error."\n";
  $lp->job_send_control_file($jobkey) or die "Can't send control file: ".$lp->error."\n";
  $lp->job_send_data($jobkey, '', $size);
  
  while (my $line = $fh->getline()) {
        $lp->job_send_data($jobkey, $line);
  }
  
  $lp->disconnect();

BUGS

There are lots of bugs in the stuff I write. Don't hesitate to yell at me if you find one. If you can fix it and send me a diff, you'll be my hero, forever. Please use this form of the diff command:

  diff -u original/LPR.pm my_local/LPR.pm

and send me the output at the email address below.

AUTHOR

David M. Lloyd <dmlloyd@cpan.org>

SEE ALSO

For information on line printing, see lpr, lpq, lprm, lp, lpd, RFC1179.

For information on troff and troff fonts, see troff.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 42:

=back doesn't take any parameters, but you said =back 4

Around line 112:

=back doesn't take any parameters, but you said =back 4