| blob | bf3377968d3a9c1bbb16b632b99ad0c457c36fba |
1 '\" te
2 .\" Copyright 1989 AT&T Copyright (c) 1997 Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH LPFORMS 1M "Apr 3, 1997"
7 .SH NAME
8 lpforms \- administer forms used with the LP print service
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBlpforms\fR \fB-f\fR \fIform-name\fR \fIoption\fR
13 .fi
15 .LP
16 .nf
17 \fBlpforms\fR \fB-f\fR \fIform-name\fR \fB-A\fR \fIalert-type\fR [\fB-P\fR \fIpaper-name\fR [\fB-d\fR]]
18 [\fB-Q\fR \fIrequests\fR] [\fB-W\fR \fIminutes\fR]
19 .fi
21 .SH DESCRIPTION
22 .sp
23 .LP
24 The \fBlpforms\fR command administers the use of preprinted forms, such as
25 company letterhead paper, with the LP print service. A form is specified by its
26 \fIform-name\fR. Users may specify a form when submitting a print request (see
27 \fBlp\fR(1)). The argument \fBall\fR can be used instead of \fIform-name\fR
28 with either of the command lines shown above. The first command line allows
29 the administrator to add, change, and delete forms, to list the attributes of
30 an existing form, and to allow and deny users access to particular forms. The
31 second command line is used to establish the method by which the administrator
32 is alerted that the form \fIform-name\fR must be mounted on a printer.
33 .SH OPTIONS
34 .sp
35 .LP
36 The following options are supported:
37 .sp
38 .ne 2
39 .na
40 \fB\fB-f\fR \fIform-name\fR\fR
41 .ad
42 .RS 16n
43 Specify a form.
44 .RE
46 .sp
47 .LP
48 The first form of \fBlpforms\fR requires that one of the following
49 \fIoption\fRs (\fB\(mi\fR, \fB-l\fR, \fB-F\fR, \fB-x\fR) must be used:
50 .sp
51 .ne 2
52 .na
53 \fB\fB-F\fR \fIpathname\fR\fR
54 .ad
55 .RS 15n
56 To add or change form \fIform-name\fR, as specified by the information in
57 \fIpathname\fR.
58 .RE
60 .sp
61 .ne 2
62 .na
63 \fB\fB\(mi\fR\fR
64 .ad
65 .RS 15n
66 To add or change form \fIform-name\fR, as specified by the information from
67 standard input.
68 .RE
70 .sp
71 .ne 2
72 .na
73 \fB\fB-l\fR\fR
74 .ad
75 .RS 15n
76 To list the attributes of form \fIform-name\fR.
77 .RE
79 .sp
80 .ne 2
81 .na
82 \fB\fB-x\fR\fR
83 .ad
84 .RS 15n
85 To delete form \fIform-name\fR (this option must be used separately; it may not
86 be used with any other option).
87 .RE
89 .sp
90 .LP
91 The second form of the \fBlpforms\fR command requires the \fB-A\fR
92 \fIalert-type\fR option. The other options are optional.
93 .sp
94 .ne 2
95 .na
96 \fB\fB-A\fR \fIalert-type\fR\fR
97 .ad
98 .RS 24n
99 Defines an alert to mount the form when there are queued jobs which need it.
100 .RE
102 .sp
103 .ne 2
104 .na
105 \fB\fB-P\fR \fIpaper-name\fR [ \fB-d\fR ]\fR
106 .ad
107 .RS 24n
108 Specify the paper name when creating the form. If \fB-d\fR is specified, this
109 paper is the default.
110 .RE
112 .sp
113 .ne 2
114 .na
115 \fB\fB-Q\fR \fIrequests\fR\fR
116 .ad
117 .RS 24n
118 An alert will be sent when a certain number of print requests that need the
119 form are waiting.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fB-W\fR \fIminutes\fR\fR
126 .ad
127 .RS 24n
128 An alert will be sent at intervals specified by minutes.
129 .RE
131 .SH USAGE
132 .SS "Adding or Changing a Form"
133 .sp
134 .LP
135 The \fB-F\fR \fIpathname\fR option is used to add a new form, \fIform-name\fR,
136 to the LP print service, or to change the attributes of an existing form. The
137 form description is taken from \fIpathname\fR if the \fB-F\fR option is given,
138 or from the standard input if the \fB\(mi\fR option is used. One of these two
139 options must be used to define or change a form.
140 .sp
141 .LP
142 \fIpathname\fR is the path name of a file that contains all or any subset of
143 the following information about the form.
144 .sp
145 .in +2
146 .nf
147 \fBPage length\fR: \fIscaled-decimal-number1\fR
148 \fBPage width\fR: \fIscaled-decimal-number2\fR
149 \fBNumber of pages\fR: \fIinteger\fR
150 \fBLine pitch\fR: \fIscaled-decimal-number3\fR
151 \fBCharacter pitch\fR: \fIscaled-decimal-number4\fR
152 \fBCharacter set choice\fR: \fIcharacter-set/print-wheel\fR [\fBmandatory\fR]
153 \fBRibbon color\fR: \fIribbon-color\fR
154 \fBComment:\fR
155 \fIcomment\fR
156 \fBAlignment pattern\fR: [\fIcontent-type\fR]
157 \fIcontent\fR
158 .fi
159 .in -2
160 .sp
162 .sp
163 .LP
164 The term ``scaled-decimal-number'' refers to a non-negative number used to
165 indicate a unit of size. The type of unit is shown by a ``trailing'' letter
166 attached to the number. Three types of scaled decimal numbers can be used with
167 the LP print service: numbers that show sizes in centimeters (marked with a
168 trailing \fBc\fR); numbers that show sizes in inches (marked with a trailing
169 \fBi\fR); and numbers that show sizes in units appropriate to use (without a
170 trailing letter); lines, characters, lines per inch, or characters per inch.
171 .sp
172 .LP
173 Except for the last two lines, the above lines may appear in any order. The
174 \fBComment:\fR and \fIcomment\fR items must appear in consecutive order but may
175 appear before the other items, and the \fBAlignment pattern:\fR and the
176 \fIcontent\fR items must appear in consecutive order at the end of the file.
177 Also, the \fIcomment\fR item may not contain a line that begins with any of the
178 key phrases above, unless the key phrase is preceded with a \fB>\fR sign. Any
179 leading > sign found in the \fIcomment\fR will be removed when the comment is
180 displayed. There is no case distinction among the key phrases.
181 .sp
182 .LP
183 When this command is issued, the form specified by \fIform-name\fR is added to
184 the list of forms. If the form already exists, its description is changed to
185 reflect the new information. Once added, a form is available for use in a print
186 request, except where access to the form has been restricted, as described
187 under the \fB-u\fR option. A form may also be allowed to be used on certain
188 printers only.
189 .sp
190 .LP
191 A description of each form attribute is below:
192 .sp
193 .ne 2
194 .na
195 \fB\fBPage length\fR and \fBPage Width\fR\fR
196 .ad
197 .sp .6
198 .RS 4n
199 Before printing the content of a print request needing this form, the generic
200 interface program provided with the LP print service will initialize the
201 physical printer to handle pages \fIscaled-decimal-number1\fR long, and
202 \fIscaled-decimal-number2\fR wide using the printer type as a key into the
203 \fBterminfo\fR(4) database. The page length and page width will also be passed,
204 if possible, to each filter used in a request needing this form.
205 .RE
207 .sp
208 .ne 2
209 .na
210 \fB\fBNumber of pages\fR\fR
211 .ad
212 .sp .6
213 .RS 4n
214 Each time the alignment pattern is printed, the LP print service will attempt
215 to truncate the \fIcontent\fR to a single form by, if possible, passing to each
216 filter the page subset of 1-\fIinteger\fR.
217 .RE
219 .sp
220 .ne 2
221 .na
222 \fB\fBLine pitch\fR and \fBCharacter pitch\fR\fR
223 .ad
224 .sp .6
225 .RS 4n
226 Before printing the content of a print request needing this form, the interface
227 program provided with the LP print service will initialize the physical
228 printer to handle these pitches, using the printer type as a key into the
229 \fBterminfo\fR(4) database. Also, the pitches will be passed, if possible, to
230 each filter used in a request needing this form. \fIscaled-decimal-number3\fR
231 is in lines-per-centimeter if a \fBc\fR is appended, and lines-per-inch
232 otherwise; similarly, \fIscaled-decimal-number4\fR is in
233 characters-per-centimeter if a \fBc\fR is appended, and characters-per-inch
234 otherwise. The character pitch can also be given as \fBelite\fR (12
235 characters-per-inch), \fBpica\fR (10 characters-per-inch), or \fBcompressed\fR
236 (as many characters-per-inch as possible).
237 .RE
239 .sp
240 .ne 2
241 .na
242 \fB\fBCharacter set choice\fR\fR
243 .ad
244 .sp .6
245 .RS 4n
246 When the LP print service alerts an administrator to mount this form, it will
247 also mention that the print wheel \fIprint-wheel\fR should be used on those
248 printers that take print wheels. If printing with this form is to be done on a
249 printer that has selectable or loadable character sets instead of print wheels,
250 the interface programs provided with the LP print service will automatically
251 select or load the correct character set. If \fBmandatory\fR is appended, a
252 user is not allowed to select a different character set for use with the form;
253 otherwise, the character set or print wheel named is a suggestion and a default
254 only.
255 .RE
257 .sp
258 .ne 2
259 .na
260 \fB\fBRibbon color\fR\fR
261 .ad
262 .sp .6
263 .RS 4n
264 When the LP print service alerts an administrator to mount this form, it will
265 also mention that the color of the ribbon should be \fIribbon-color\fR.
266 .RE
268 .sp
269 .ne 2
270 .na
271 \fB\fBComment\fR\fR
272 .ad
273 .sp .6
274 .RS 4n
275 The LP print service will display the \fIcomment\fR unaltered when a user asks
276 about this form (see \fBlpstat\fR(1)).
277 .RE
279 .sp
280 .ne 2
281 .na
282 \fB\fBAlignment pattern\fR\fR
283 .ad
284 .sp .6
285 .RS 4n
286 When mounting this form, an administrator can ask for the \fIcontent\fR to be
287 printed repeatedly, as an aid in correctly positioning the preprinted form. The
288 optional \fIcontent-type\fR defines the type of printer for which \fIcontent\fR
289 had been generated. If \fIcontent-type\fR is not given, \fBsimple\fR is
290 assumed. Note that the \fIcontent\fR is stored as given, and will be readable
291 only by the user \fBlp\fR.
292 .RE
294 .sp
295 .LP
296 When an existing form is changed with this command, items missing in the new
297 information are left as they were. When a new form is added with this command,
298 missing items will get the following defaults:
299 .sp
300 .in +2
301 .nf
302 Page Length: \fB66\fR
303 Page Width: \fB80\fR
304 Number of Pages: \fB1\fR
305 Line Pitch: \fB6\fR
306 Character Pitch: \fB10\fR
307 Character Set Choice: \fBany\fR
308 Ribbon Color: \fBany\fR
309 .fi
310 .in -2
311 .sp
313 .SS "Deleting a Form"
314 .sp
315 .LP
316 LP print service" The \fB-x\fR option is used to delete the form
317 \fIform-name\fR from the LP print service.
318 .SS "Listing Form Attributes"
319 .sp
320 .LP
321 The \fB-l\fR option is used to list the attributes of the existing form
322 \fIform-name\fR. The attributes listed are those described under \fBAdding and
323 Changing a Form,\fR above. Because of the potentially sensitive nature of the
324 alignment pattern, only the administrator can examine the form with this
325 command. Other people may use the \fBlpstat\fR(1) command to examine the
326 non-sensitive part of the form description.
327 .SS "Allowing and Denying Access to a Form"
328 .sp
329 .LP
330 The \fB-u\fR option, followed by the argument \fBallow:\fR\fIlogin-ID-list\fR
331 or \fB\fR\fB-u\fR \fBdeny:\fR\fIlogin-ID-list\fR lets you determine which users
332 will be allowed to specify a particular form with a print request. This option
333 can be used with the \fB-F\fR or \fB\(mi\fR option, each of which is described
334 above under \fBAdding or Changing a Form\fR.
335 .sp
336 .LP
337 The \fIlogin-ID-list\fR argument may include any or all of the following
338 constructs:
339 .sp
340 .ne 2
341 .na
342 \fB\fIlogin-ID\fR\fR
343 .ad
344 .RS 24n
345 A user on any system
346 .RE
348 .sp
349 .ne 2
350 .na
351 \fB\fIsystem_name\fR\fB!\fR\fIlogin-ID\fR\fR
352 .ad
353 .RS 24n
354 A user on system \fIsystem_name\fR
355 .RE
357 .sp
358 .ne 2
359 .na
360 \fB\fIsystem_name\fR\fB!all\fR\fR
361 .ad
362 .RS 24n
363 All users on system \fIsystem_name\fR
364 .RE
366 .sp
367 .ne 2
368 .na
369 \fB\fBall!\fR\fIlogin-ID\fR\fR
370 .ad
371 .RS 24n
372 A user on all systems
373 .RE
375 .sp
376 .ne 2
377 .na
378 \fB\fBall\fR\fR
379 .ad
380 .RS 24n
381 All users on all systems
382 .RE
384 .sp
385 .LP
386 The LP print service keeps two lists of users for each form: an ``allow-list''
387 of people allowed to use the form, and a ``deny-list'' of people that may not
388 use the form. With the \fB\fR\fB-u\fR \fBallow\fR option, the users listed are
389 added to the allow-list and removed from the deny-list. With the \fB\fR\fB-u\fR
390 \fBdeny\fR option, the users listed are added to the deny-list and removed
391 from the allow-list. (Both forms of the \fB-u\fR option can be run together
392 with the \fB-F\fR or the \fB\(mi\fR option.)
393 .sp
394 .LP
395 If the allow-list is not empty, only the users in the list are allowed access
396 to the form, regardless of the content of the deny-list. If the allow-list is
397 empty but the deny-list is not, the users in the deny-list may not use the
398 form, (but all others may use it). All users can be denied access to a form by
399 specifying \fB\fR\fB-f\fR \fBdeny:all\fR. All users can be allowed access to a
400 form by specifying \fB\fR\fB-f\fR \fBallow:all\fR. (This is the default.)
401 .SS "Setting an Alert to Mount a Form"
402 .sp
403 .LP
404 The \fB\fR\fB-f\fR \fIform-name\fR option is used with the \fB\fR\fB-A\fR
405 \fIalert-type\fR option to define an alert to mount the form when there are
406 queued jobs which need it. If this option is not used to arrange alerting for a
407 form, no alert will be sent for that form.
408 .sp
409 .LP
410 The method by which the alert is sent depends on the value of the
411 \fIalert-type\fR argument specified with the \fB-A\fR option. The
412 \fIalert-types\fR are:
413 .sp
414 .ne 2
415 .na
416 \fB\fBmail\fR\fR
417 .ad
418 .RS 17n
419 Send the alert message using the \fBmail\fR command to the administrator.
420 .RE
422 .sp
423 .ne 2
424 .na
425 \fB\fBwrite\fR\fR
426 .ad
427 .RS 17n
428 Write the message, using the \fBwrite\fR command, to the terminal on which the
429 administrator is logged in. If the administrator is logged in on several
430 terminals, one is arbitrarily chosen.
431 .RE
433 .sp
434 .ne 2
435 .na
436 \fB\fBquiet\fR\fR
437 .ad
438 .RS 17n
439 Do not send messages for the current condition. An administrator can use this
440 option to temporarily stop receiving further messages about a known problem.
441 Once the form \fIform-name\fR has been mounted and subsequently unmounted,
442 messages will again be sent when the number of print requests reaches the
443 threshold specified by the \fB-Q\fR option.
444 .RE
446 .sp
447 .ne 2
448 .na
449 \fB\fBshowfault\fR\fR
450 .ad
451 .RS 17n
452 Attempt to execute a form alert handler on each system that has a print job for
453 that form in the queue. The fault handler is \fB/etc/lp/alerts/form\fR. It is
454 invoked with three parameters: \fIform_name\fR, \fBdate\fR, \fIfile_name\fR.
455 \fIfile_name\fR is the name of a file containing the form alert message.
456 .RE
458 .sp
459 .ne 2
460 .na
461 \fB\fBnone\fR\fR
462 .ad
463 .RS 17n
464 Do not send messages until the \fB-A\fR option is given again with a different
465 \fIalert-type\fR (other than \fBquiet\fR).
466 .RE
468 .sp
469 .ne 2
470 .na
471 \fB\fIshell-command\fR\fR
472 .ad
473 .RS 17n
474 Run the \fIshell-command\fR each time the alert needs to be sent. The shell
475 command should expect the message in standard input. If there are blank spaces
476 embedded in the command, enclose the command in quotes. Note that the
477 \fBmail\fR and \fBwrite\fR values for this option are equivalent to the values
478 \fBmail\fR \fIlogin-ID\fR and \fBwrite\fR \fIlogin-ID\fR respectively, where
479 \fIlogin-ID\fR is the current name for the administrator. This will be the
480 login name of the person submitting this command unless he or she has used the
481 \fBsu\fR command to change to another login-ID. If the \fBsu\fR command has
482 been used to change the user ID, then the \fIuser-name\fR for the new ID is
483 used.
484 .RE
486 .sp
487 .ne 2
488 .na
489 \fB\fBlist\fR\fR
490 .ad
491 .RS 17n
492 Display the type of the alert for the form on standard output. No change is
493 made to the alert.
494 .RE
496 .sp
497 .LP
498 The message sent appears as follows:
499 .sp
500 .in +2
501 .nf
502 The form \fIform-name\fR needs to be mounted
503 on the printer(s):\fIprinter\fR (\fIinteger1\fR \fBrequests)\fR.
504 \fIinteger2\fR print requests await this form.
505 Use the \fIribbon-color\fR ribbon.
506 Use the \fIprint-wheel\fR print wheel, if appropriate.
507 .fi
508 .in -2
509 .sp
511 .sp
512 .LP
513 The printers listed are those that the administrator has specified as
514 candidates for this form. The number \fIinteger1\fR listed next to each printer
515 is the number of requests eligible for the printer. The number \fIinteger2\fR
516 shown after the list of printers is the total number of requests awaiting the
517 form. It will be less than the sum of the other numbers if some requests can be
518 handled by more than one printer. The \fIribbon-color\fR and \fIprint-wheel\fR
519 are those specified in the form description. The last line in the message is
520 always sent, even if none of the printers listed use print wheels, because the
521 administrator may choose to mount the form on a printer that does use a print
522 wheel.
523 .sp
524 .LP
525 Where any color ribbon or any print wheel can be used, the statements above
526 will read:
527 .sp
528 .in +2
529 .nf
530 \fBUse any ribbon.\fR
531 \fBUse any print-wheel.\fR
532 .fi
533 .in -2
534 .sp
536 .sp
537 .LP
538 If \fIform-name\fR is \fBany\fR, the \fIalert-type\fR defined in this command
539 applies to any form for which an alert has not yet been defined. If
540 \fIform-name\fR is \fBall\fR, the \fIalert-type\fR defined in this command
541 applies to all forms.
542 .sp
543 .LP
544 If the \fB-W\fR \fIminutes\fR option is not given, the default procedure is
545 that only one message will be sent per need to mount the form. Not specifying
546 the \fB-W\fR option is equivalent to specifying \fB\fR\fB-W\fR \fBonce\fR or
547 \fB-W\fR \fB0\fR. If \fIminutes\fR is a number greater than \fB0\fR, an alert
548 will be sent at intervals specified by \fIminutes\fR.
549 .sp
550 .LP
551 If the \fB-Q\fR \fIrequests\fR option is also given, the alert will be sent
552 when a certain number (specified by the argument \fIrequests\fR) of print
553 requests that need the form are waiting. If the \fB-Q\fR option is not given,
554 or the value of \fIrequests\fR is \fB1\fR or \fBany\fR (which are both the
555 default), a message is sent as soon as anyone submits a print request for the
556 form when it is not mounted.
557 .SS "Listing the Current Alert"
558 .sp
559 .LP
560 The \fB-f\fR option, followed by the \fB-A\fR option and the argument
561 \fBlist\fR is used to list the \fIalert-type\fR that has been defined for the
562 specified form \fIform-name\fR. No change is made to the alert. If
563 \fIform-name\fR is recognized by the LP print service, one of the following
564 lines is sent to the standard output, depending on the type of alert for the
565 form.
566 .sp
567 .ne 2
568 .na
569 \fB\(mi\fR
570 .ad
571 .RS 8n
572 \fBWhen\fR \fIrequests\fR \fBrequests are queued:\fR \fBalert
573 with\fR\fIshell-command\fR \fBevery\fR \fIminutes\fR \fBminutes\fR
574 .RE
576 .sp
577 .ne 2
578 .na
579 \fB\(mi\fR
580 .ad
581 .RS 8n
582 \fBWhen\fR \fIrequests\fR \fBrequests are queued:\fR \fBwrite to\fR
583 \fIuser-name\fR \fBevery\fR \fIminutes\fR \fBminutes\fR
584 .RE
586 .sp
587 .ne 2
588 .na
589 \fB\(mi\fR
590 .ad
591 .RS 8n
592 \fBWhen\fR \fIrequests\fR \fBrequests are queued:\fR \fBmail to\fR
593 \fIuser-name\fR \fBevery\fR \fIminutes\fR \fBminutes\fR
594 .RE
596 .sp
597 .ne 2
598 .na
599 \fB\(mi\fR
600 .ad
601 .RS 8n
602 \fBNo alert\fR
603 .RE
605 .sp
606 .LP
607 The phrase \fBevery\fR \fIminutes\fR \fBminutes\fR is replaced with \fBonce\fR
608 if \fIminutes\fR (\fB-W\fR\fI\fR\fIminutes\fR) is 0.
609 .SS "Terminating an Active Alert"
610 .sp
611 .LP
612 The \fB-A\fR \fBquiet\fR option is used to stop messages for the current
613 condition. An administrator can use this option to temporarily stop receiving
614 further messages about a known problem. Once the form has been mounted and then
615 unmounted, messages will again be sent when the number of print requests
616 reaches the threshold \fIrequests\fR.
617 .SS "Removing an Alert Definition"
618 .sp
619 .LP
620 No messages will be sent after the \fB-A\fR \fBnone\fR option is used until the
621 \fB-A\fR option is given again with a different \fIalert-type\fR. This can be
622 used to permanently stop further messages from being sent as any existing
623 alert definition for the form will be removed.
624 .SS "Large File Behavior"
625 .sp
626 .LP
627 See \fBlargefile\fR(5) for the description of the behavior of \fBlpforms\fR
628 when encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
629 .SH EXIT STATUS
630 .sp
631 .LP
632 The following exit values are returned:
633 .sp
634 .ne 2
635 .na
636 \fB\fB0\fR\fR
637 .ad
638 .RS 12n
639 Successful completion.
640 .RE
642 .sp
643 .ne 2
644 .na
645 \fBnon-zero\fR
646 .ad
647 .RS 12n
648 An error occurred.
649 .RE
651 .SH FILES
652 .sp
653 .ne 2
654 .na
655 \fB\fB/etc/lp/alerts/form\fR\fR
656 .ad
657 .RS 23n
658 Fault handler for \fBlpform\fR.
659 .RE
661 .SH SEE ALSO
662 .sp
663 .LP
664 \fBlp\fR(1), \fBlpstat\fR(1), \fBlpadmin\fR(1M), \fBterminfo\fR(4),
665 \fBattributes\fR(5), \fBlargefile\fR(5)
666 .sp
667 .LP
668 \fI\fR