Print this page
4023 - Typo in file(1) manpage and various others
Split |
Close |
Expand all |
Collapse all |
--- old/usr/src/man/man3papi/papiPrintersList.3papi
+++ new/usr/src/man/man3papi/papiPrintersList.3papi
1 1 '\" te
2 2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 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 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 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 PAPIPRINTERSLIST 3PAPI "Jan 17, 2007"
6 +.TH PAPIPRINTERSLIST 3PAPI "Sep 10, 2013"
7 7 .SH NAME
8 8 papiPrintersList, papiPrinterQuery, papiPrinterAdd, papiPrinterModify,
9 9 papiPrinterRemove, papiPrinterDisable, papiPrinterEnable, papiPrinterPause,
10 10 papiPrinterResume, papiPrinterPurgeJobs, papiPrinterListJobs,
11 11 papiPrinterGetAttributeList, papiPrinterFree, papiPrinterListFree \- print
12 12 object manipulation
13 13 .SH SYNOPSIS
14 14 .LP
15 15 .nf
16 16 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpapi\fR [ \fIlibrary\fR\&.\|.\|. ]
17 17 #include <papi.h>
18 18
19 19 \fBpapi_status_t\fR \fBpapiPrintersList\fR(\fBpapi_service_t\fR \fIhandle\fR,
20 20 \fBchar **\fR\fIrequested_attrs\fR, \fBpapi_filter_t *\fR\fIfilter\fR,
21 21 \fBpapi_printer_t **\fR\fIprinters\fR);
22 22 .fi
23 23
24 24 .LP
25 25 .nf
26 26 \fBpapi_status_t\fR \fBpapiPrinterQuery\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
27 27 \fBchar **\fR\fIrequested_attrs\fR, \fBpapi_attribute_t **\fR\fIjob_attributes\fR,
28 28 \fBpapi_printer_t *\fR\fIprinter\fR);
29 29 .fi
30 30
31 31 .LP
32 32 .nf
33 33 \fBpapi_status_t\fR \fBpapiPrinterAdd\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
34 34 \fBpapi_attribute_t **\fR\fIattributes\fR, \fBpapi_printer_t *\fR\fIprinter\fR);
35 35 .fi
36 36
37 37 .LP
38 38 .nf
39 39 \fBpapi_status_t\fR \fBpapiPrinterModify\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
40 40 \fBpapi_attribute_t **\fR\fIattributes\fR, \fBpapi_printer_t *\fR\fIprinter\fR);
41 41 .fi
42 42
43 43 .LP
44 44 .nf
45 45 \fBpapi_status_t\fR \fBpapiPrinterRemove\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR);
46 46 .fi
47 47
48 48 .LP
49 49 .nf
50 50 \fBpapi_status_t\fR \fBpapiPrinterDisable\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
51 51 \fBchar *\fR\fImessage\fR);
52 52 .fi
53 53
54 54 .LP
55 55 .nf
56 56 \fBpapi_status_t\fR \fBpapiPrinterEnable\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR);
57 57 .fi
58 58
59 59 .LP
60 60 .nf
61 61 \fBpapi_status_t\fR \fBpapiPrinterPause\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
62 62 \fBchar *\fR\fImessage\fR);
63 63 .fi
64 64
65 65 .LP
66 66 .nf
67 67 \fBpapi_status_t\fR \fBpapiPrinterResume\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR);
68 68 .fi
69 69
70 70 .LP
71 71 .nf
72 72 \fBpapi_status_t\fR \fBpapiPrinterPurgeJobs\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
73 73 \fBpapi_job_t **\fR\fIjobs\fR);
74 74 .fi
75 75
76 76 .LP
77 77 .nf
78 78 \fBpapi_status_t\fR \fBpapiPrinterListJobs\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR,
79 79 \fBchar **\fR\fIrequested_attrs\fR, \fBint\fR \fItype_mask\fR, \fBint\fR \fImax_num_jobs\fR,
80 80 \fBpapi_job_t **\fR\fIjobs\fR);
81 81 .fi
82 82
83 83 .LP
84 84 .nf
85 85 \fBpapi_attribute_t **\fR\fBpapiPrinterGetAttributeList\fR(\fBpapi_printer_t\fR \fIprinter\fR);
86 86 .fi
87 87
88 88 .LP
89 89 .nf
90 90 \fBvoid\fR \fBpapiPrinterFree\fR(\fBpapi_printer_t\fR \fIprinter\fR);
91 91 .fi
92 92
93 93 .LP
94 94 .nf
95 95 \fBvoid\fR \fBpapiPrinterListFree\fR(\fBpapi_printer_t *\fR\fIprinters\fR);
96 96 .fi
97 97
98 98 .SH PARAMETERS
99 99 .sp
100 100 .ne 2
101 101 .na
102 102 \fB\fIattributes\fR\fR
103 103 .ad
104 104 .RS 19n
105 105 a set of attributes to be applied to a printer object
106 106 .RE
107 107
108 108 .sp
109 109 .ne 2
110 110 .na
111 111 \fB\fIfilter\fR\fR
112 112 .ad
113 113 .RS 19n
114 114 a filter to be applied during printer enumeration
115 115 .RE
116 116
117 117 .sp
118 118 .ne 2
119 119 .na
120 120 \fB\fIhandle\fR\fR
121 121 .ad
122 122 .RS 19n
123 123 a pointer to a handle to be used for all PAPI operations, created by calling
124 124 \fBpapiServiceCreate()\fR
125 125 .RE
126 126
127 127 .sp
128 128 .ne 2
129 129 .na
130 130 \fB\fIjob_attributes\fR\fR
131 131 .ad
132 132 .RS 19n
133 133 unused
134 134 .RE
135 135
136 136 .sp
137 137 .ne 2
138 138 .na
139 139 \fB\fIjobs\fR\fR
140 140 .ad
141 141 .RS 19n
142 142 a pointer to a list to return job objects (initialized to \fINULL\fR)
143 143 enumerated by \fBpapiPrinterGetJobs()\fR
144 144 .RE
145 145
146 146 .sp
147 147 .ne 2
148 148 .na
149 149 \fB\fImax_num_jobs\fR\fR
150 150 .ad
151 151 .RS 19n
152 152 the maximum number of jobs to return from a \fBpapiPrinterGetJobs()\fR request
153 153 .RE
154 154
155 155 .sp
156 156 .ne 2
157 157 .na
158 158 \fB\fImessage\fR\fR
159 159 .ad
160 160 .RS 19n
161 161 a message to be associated with a printer while disabled or paused
162 162 .RE
163 163
164 164 .sp
165 165 .ne 2
166 166 .na
167 167 \fB\fIname\fR\fR
168 168 .ad
169 169 .RS 19n
170 170 the name of the printer object being operated on
171 171 .RE
172 172
173 173 .sp
174 174 .ne 2
175 175 .na
176 176 \fB\fIprinter\fR\fR
177 177 .ad
178 178 .RS 19n
179 179 a pointer to a printer object (initialized to \fINULL\fR) to be filled in by
180 180 \fBpapiPrinterQuery()\fR, \fBpapiPrinterAdd()\fR, and \fBpapiPrinterModify()\fR
181 181 .RE
182 182
183 183 .sp
184 184 .ne 2
185 185 .na
186 186 \fB\fIprinters\fR\fR
187 187 .ad
188 188 .RS 19n
189 189 a pointer to a list to return printer objects (initialized to \fINULL\fR)
190 190 enumerated by \fBpapiPrintersList()\fR
191 191 .RE
192 192
193 193 .sp
194 194 .ne 2
195 195 .na
196 196 \fB\fIrequested_attrs\fR\fR
197 197 .ad
198 198 .RS 19n
199 199 a null-terminated array of pointers to attribute names requested during printer
200 200 enumeration (\fBpapiPrintersList()\fR), printer query
201 201 (\fBpapiPrinterQuery()\fR), or job enumeration (\fBpapiPrinterListJobs()\fR)
202 202 .RE
203 203
204 204 .sp
205 205 .ne 2
206 206 .na
207 207 \fB\fItype_mask\fR\fR
208 208 .ad
209 209 .RS 19n
210 210 a bit field indicating which type of jobs to return \fBPAPI_LIST_JOBS_OTHERS\fR
211 211 include jobs submitted by others. The default is to report only on your own
212 212 jobs
213 213 .sp
214 214 .ne 2
215 215 .na
216 216 \fB\fBPAPI_LIST_JOBS_COMPLETED\fR\fR
217 217 .ad
218 218 .sp .6
219 219 .RS 4n
220 220 include completed jobs
221 221 .RE
222 222
223 223 .sp
224 224 .ne 2
225 225 .na
226 226 \fB\fBPAPI_LIST_JOBS_NOT_COMPLETED\fR\fR
227 227 .ad
228 228 .sp .6
229 229 .RS 4n
230 230 include jobs not complete
231 231 .RE
232 232
233 233 .sp
234 234 .ne 2
235 235 .na
236 236 \fB\fBPAPI_LIST_JOBS_ALL\fR\fR
237 237 .ad
238 238 .sp .6
239 239 .RS 4n
240 240 report on all jobs
241 241 .RE
242 242
243 243 .RE
244 244
245 245 .SH DESCRIPTION
246 246 .sp
247 247 .LP
248 248 The \fBpapiPrintersList()\fR function retrieves the requested attributes from
249 249 the print service(s) for all available printers. Because the Solaris
250 250 implementation is name service-enabled, applications should retrieve only the
251 251 \fBprinter-name\fR and \fBprinter-uri-supported\fR attributes using this
252 252 function, thereby reducing the overhead involved in generating a printer list.
253 253 Further integration of printer state and capabilities can be performed with
254 254 \fBpapiPrinterQuery()\fR.
255 255 .sp
256 256 .LP
257 257 The \fBpapiPrinterAdd()\fR, \fBpapiPrinterModify()\fR, and
258 258 \fBpapiPrinterRemove()\fR functions allow for creation, modification, and
259 259 removal of print queues. Print queues are added or modified according to the
260 260 attribute list passed into the call. A printer object is returned that reflects
261 261 the configuration of the printer after the addition or modification has been
262 262 applied. At this time, they provide only minimal functionality and only for
263 263 the LP print service.
264 264 .sp
265 265 .LP
266 266 The \fBpapiPrinterDisable()\fR and \fBpapiPrinterEnable()\fR functions allow
267 267 applications to turn off and on queueing (accepting print requests) for a print
268 268 queue. The \fBpapiPrinterEnable()\fR and \fBpapiPrinterDisable()\fR functions
269 269 allow applications to turn on and off print job processing for a print queue.
270 270 .sp
271 271 .LP
272 272 The \fBpapiPrinterPause()\fR function stops queueing of print jobs on the named
273 273 print queue.
274 274 .sp
275 275 .LP
276 276 The \fBpapiPrinterResume()\fR function resumes queueing of print jobs on the
277 277 named print queue.
278 278 .sp
279 279 .LP
280 280 The \fBpapiPrinterPurgeJobs()\fR function allows applications to delete all
281 281 print jobs that it has privilege to remove. A list of cancelled jobs is
282 282 returned in the jobs argument.
283 283 .sp
284 284 .LP
285 285 The \fBpapiPrinterListJobs()\fR function enumerates print jobs on a particular
286 286 queue. \fBpapiPrinterGetAttributeList()\fR retrieves an attribute list from a
287 287 printer object.
288 288 .sp
289 289 .LP
290 290 The \fBpapiPrinterGetAttributeList()\fR function retrieves an attribute list
291 291 from a printer object returned from \fBpapiPrinterQuery()\fR,
292 292 \fBpapiPrintersList()\fR, \fBpapiPrinterModify()\fR, and
293 293 \fBpapiPrinterAdd()\fR. This attribute list can be searched for various
294 294 information about the printer object.
295 295 .sp
296 296 .LP
297 297 The \fBpapiPrinterFree()\fR and \fBpapiPrinterListFree()\fR functions
298 298 deallocate memory allocated for the return of printer object(s) from functions
299 299 that return printer objects.
300 300 .SH RETURN VALUES
301 301 .sp
302 302 .LP
303 303 Upon successful completion, all functions that return a value return
304 304 \fBPAPI_OK\fR. Otherwise, they return an appropriate \fBpapi_status_t()\fR
305 305 indicating the type of failure.
306 306 .sp
307 307 .LP
308 308 Upon successful completion, \fBpapiPrinterGetAttributeList()\fR returns a
309 309 pointer to the requested data. Otherwise, it returns \fINULL\fR.
310 310 .SH EXAMPLES
311 311 .LP
312 312 \fBExample 1 \fREnumerate all available printers.
313 313 .sp
314 314 .in +2
315 315 .nf
316 316 #include <stdio.h>
317 317 #include <stdlib.h>
318 318 #include <unistd.h>
319 319 #include <libintl.h>
320 320 #include <pwd.h>
321 321 #include <papi.h>
322 322
323 323 static int
324 324 authCB(papi_service_t svc, void *app_data)
325 325 {
326 326 char prompt[BUFSIZ];
327 327 char *user, *svc_name, *passphrase;
328 328
329 329 /* get the name of the service we are contacting */
330 330 if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
331 331 return (-1);
332 332
333 333 /* find out who we are supposed to be */
334 334 if ((user = papiServiceGetUserName(svc)) == NULL) {
335 335 struct passwd *pw;
336 336
337 337 if ((pw = getpwuid(getuid())) != NULL)
338 338 user = pw->pw_name;
339 339 else
340 340 user = "nobody";
341 341 }
342 342
343 343 /* build the prompt string */
344 344 snprintf(prompt, sizeof (prompt),
345 345 gettext("passphrase for %s to access %s: "), user,
346 346 svc_name);
347 347
348 348 /* ask for the passphrase */
349 349 if ((passphrase = getpassphrase(prompt)) != NULL)
350 350 papiServiceSetPassword(svc, passphrase);
351 351
352 352 return (0);
353 353 }
354 354
355 355 /*ARGSUSED*/
356 356 int
357 357 main(int ac, char *av[])
358 358 {
359 359 papi_status_t status;
360 360 papi_service_t svc = NULL;
361 361 papi_printer_t *printers = NULL;
362 362 char *attrs[] = { "printer-name", "printer-uri-supported", NULL };
363 363 char *svc_name = NULL;
364 364 int c;
365 365
366 366 while ((c = getopt(ac, av, "s:")) != EOF)
367 367 switch (c) {
368 368 case 's':
369 369 svc_name = optarg;
370 370 break;
371 371 }
372 372
373 373 status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
374 374 PAPI_ENCRYPT_NEVER, NULL);
375 375
376 376 if (status != PAPI_OK) {
377 377 printf("papiServiceCreate(%s): %s\en", svc_name ? svc_name :
378 378 "NULL", papiStatusString(status));
379 379 papiServiceDestroy(svc);
380 380 exit(1);
381 381 }
382 382
383 383 status = papiPrintersList(svc, attrs, NULL, &printers);
384 384 if (status != PAPI_OK) {
385 385 printf("papiPrintersList(%s): %s\en", svc_name ? svc_name :
386 386 "NULL", papiStatusString(status));
387 387 papiServiceDestroy(svc);
388 388 exit(1);
389 389 }
390 390
391 391 if (printers != NULL) {
392 392 int i;
393 393
394 394 for (i = 0; printers[i] != NULL; i++) {
395 395 papi_attribute_t **list =
396 396 papiPrinterGetAttributeList(printers[i]);
↓ open down ↓ |
380 lines elided |
↑ open up ↑ |
397 397
398 398 if (list != NULL) {
399 399 char *name = "unknown";
400 400 char *uri = "unknown";
401 401
402 402 (void) papiAttributeListGetString(list, NULL,
403 403 "printer-name", &name);
404 404
405 405 (void) papiAttributeListGetString(list, NULL,
406 406 "printer-uri-supported", &uri);
407 - printf("%s is %s\n", name, uri);
407 + printf("%s is %s\en", name, uri);
408 408 }
409 409 }
410 410 papiPrinterListFree(printers);
411 411 }
412 412
413 413 papiServiceDestroy(svc);
414 414
415 415 exit(0);
416 416 }
417 417 .fi
418 418 .in -2
419 419
420 420 .LP
421 421 \fBExample 2 \fRDump all printer attributes.
422 422 .sp
423 423 .in +2
424 424 .nf
425 425 /*
426 426 * program to query a printer for it's attributes via PAPI
427 427 */
428 428 #include <stdio.h>
429 429 #include <stdlib.h>
430 430 #include <unistd.h>
431 431 #include <libintl.h>
432 432 #include <pwd.h>
433 433 #include <papi.h>
434 434
435 435 static int
436 436 authCB(papi_service_t svc, void *app_data)
437 437 {
438 438 char prompt[BUFSIZ];
439 439 char *user, *svc_name, *passphrase;
440 440
441 441 /* get the name of the service we are contacting */
442 442 if ((svc_name = papiServiceGetServiceName(svc)) == NULL)
443 443 return (-1);
444 444
445 445 /* find out who we are supposed to be */
446 446 if ((user = papiServiceGetUserName(svc)) == NULL) {
447 447 struct passwd *pw;
448 448
449 449 if ((pw = getpwuid(getuid())) != NULL)
450 450 user = pw->pw_name;
451 451 else
452 452 user = "nobody";
453 453 }
454 454
455 455 /* build the prompt string */
456 456 snprintf(prompt, sizeof (prompt),
457 457 gettext("passphrase for %s to access %s: "), user,
458 458 svc_name);
459 459
460 460 /* ask for the passphrase */
461 461 if ((passphrase = getpassphrase(prompt)) != NULL)
462 462 papiServiceSetPassword(svc, passphrase);
463 463
464 464 return (0);
465 465 }
466 466
467 467 /*ARGSUSED*/
468 468 int
469 469 main(int ac, char *av[])
470 470 {
471 471 papi_status_t status;
472 472 papi_service_t svc = NULL;
473 473 papi_printer_t printer = NULL;
474 474 char *svc_name = NULL;
475 475 char *pname = "unknown";
476 476 int c;
477 477
478 478 while ((c = getopt(ac, av, "s:p:")) != EOF)
479 479 switch (c) {
480 480 case 's':
481 481 svc_name = optarg;
482 482 break;
483 483 case 'p':
484 484 pname = optarg;
485 485 break;
486 486 }
487 487
488 488 status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB,
489 489 PAPI_ENCRYPT_NEVER, NULL);
490 490
491 491 if (status != PAPI_OK) {
492 492 printf("papiServiceCreate(%s): %s\en", svc_name ? svc_name :
493 493 "NULL", papiStatusString(status));
494 494 papiServiceDestroy(svc);
495 495 exit(1);
496 496 }
497 497
498 498 status = papiPrinterQuery(svc, pname, NULL, NULL, &printer);
499 499 if ((status == PAPI_OK) && (printer != NULL)) {
500 500 papi_attribute_t **list = papiPrinterGetAttributeList(printer);
501 501 char *buffer = NULL;
502 502 size_t size = 0;
503 503
504 504 while (papiAttributeListToString(list, "\en\et", buffer, size)
505 505 != PAPI_OK)
506 506 buffer = realloc(buffer, size += BUFSIZ);
507 507
508 508 printf("%s:\en\et%s\en", pname, buffer);
509 509 } else
510 510 printf("papiPrinterQuery(%s): %s\en", pname,
511 511 papiStatusString(status));
512 512
513 513 papiPrinterFree(printer);
514 514 papiServiceDestroy(svc);
515 515
516 516 exit(0);
517 517 }
518 518 .fi
519 519 .in -2
520 520
521 521 .SH ATTRIBUTES
522 522 .sp
523 523 .LP
524 524 See \fBattributes\fR(5) for descriptions of the following attributes:
525 525 .sp
526 526
527 527 .sp
528 528 .TS
529 529 box;
530 530 c | c
531 531 l | l .
532 532 ATTRIBUTE TYPE ATTRIBUTE VALUE
533 533 _
534 534 Interface Stability Volatile
535 535 _
536 536 MT-Level Safe
537 537 .TE
538 538
539 539 .SH SEE ALSO
540 540 .sp
541 541 .LP
542 542 \fBlibpapi\fR(3LIB), \fBattributes\fR(5)
↓ open down ↓ |
125 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX