diff options
Diffstat (limited to 'usr/src/man/man3papi')
| -rw-r--r-- | usr/src/man/man3papi/Makefile | 175 | ||||
| -rw-r--r-- | usr/src/man/man3papi/papiAttributeListAddValue.3papi | 732 | ||||
| -rw-r--r-- | usr/src/man/man3papi/papiJobSubmit.3papi | 771 | ||||
| -rw-r--r-- | usr/src/man/man3papi/papiLibrarySupportedCall.3papi | 79 | ||||
| -rw-r--r-- | usr/src/man/man3papi/papiPrintersList.3papi | 570 | ||||
| -rw-r--r-- | usr/src/man/man3papi/papiServiceCreate.3papi | 334 | ||||
| -rw-r--r-- | usr/src/man/man3papi/papiStatusString.3papi | 88 |
7 files changed, 2749 insertions, 0 deletions
diff --git a/usr/src/man/man3papi/Makefile b/usr/src/man/man3papi/Makefile new file mode 100644 index 0000000000..d34f1c17d2 --- /dev/null +++ b/usr/src/man/man3papi/Makefile @@ -0,0 +1,175 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 3papi + +MANFILES = papiAttributeListAddValue.3papi \ + papiJobSubmit.3papi \ + papiLibrarySupportedCall.3papi \ + papiPrintersList.3papi \ + papiServiceCreate.3papi \ + papiStatusString.3papi + +MANSOFILES = papiAttributeListAddBoolean.3papi \ + papiAttributeListAddCollection.3papi \ + papiAttributeListAddDatetime.3papi \ + papiAttributeListAddInteger.3papi \ + papiAttributeListAddMetadata.3papi \ + papiAttributeListAddRange.3papi \ + papiAttributeListAddResolution.3papi \ + papiAttributeListAddString.3papi \ + papiAttributeListDelete.3papi \ + papiAttributeListFind.3papi \ + papiAttributeListFree.3papi \ + papiAttributeListFromString.3papi \ + papiAttributeListGetBoolean.3papi \ + papiAttributeListGetCollection.3papi \ + papiAttributeListGetDatetime.3papi \ + papiAttributeListGetInteger.3papi \ + papiAttributeListGetMetadata.3papi \ + papiAttributeListGetNext.3papi \ + papiAttributeListGetRange.3papi \ + papiAttributeListGetResolution.3papi \ + papiAttributeListGetString.3papi \ + papiAttributeListGetValue.3papi \ + papiAttributeListToString.3papi \ + papiJobCancel.3papi \ + papiJobFree.3papi \ + papiJobGetAttributeList.3papi \ + papiJobGetId.3papi \ + papiJobGetJobTicket.3papi \ + papiJobGetPrinterName.3papi \ + papiJobHold.3papi \ + papiJobListFree.3papi \ + papiJobModify.3papi \ + papiJobMove.3papi \ + papiJobPromote.3papi \ + papiJobQuery.3papi \ + papiJobRelease.3papi \ + papiJobRestart.3papi \ + papiJobStreamClose.3papi \ + papiJobStreamOpen.3papi \ + papiJobStreamWrite.3papi \ + papiJobSubmitByReference.3papi \ + papiJobValidate.3papi \ + papiLibrarySupportedCalls.3papi \ + papiPrinterAdd.3papi \ + papiPrinterDisable.3papi \ + papiPrinterEnable.3papi \ + papiPrinterFree.3papi \ + papiPrinterGetAttributeList.3papi \ + papiPrinterListFree.3papi \ + papiPrinterListJobs.3papi \ + papiPrinterModify.3papi \ + papiPrinterPause.3papi \ + papiPrinterPurgeJobs.3papi \ + papiPrinterQuery.3papi \ + papiPrinterRemove.3papi \ + papiPrinterResume.3papi \ + papiServiceDestroy.3papi \ + papiServiceGetAppData.3papi \ + papiServiceGetAttributeList.3papi \ + papiServiceGetEncryption.3papi \ + papiServiceGetPassword.3papi \ + papiServiceGetServiceName.3papi \ + papiServiceGetStatusMessage.3papi \ + papiServiceGetUserName.3papi \ + papiServiceSetAppData.3papi \ + papiServiceSetAuthCB.3papi \ + papiServiceSetEncryption.3papi \ + papiServiceSetPassword.3papi \ + papiServiceSetUserName.3papi + +MANFILES += $(MANSOFILES) + +papiAttributeListAddBoolean.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListAddCollection.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListAddDatetime.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListAddInteger.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListAddMetadata.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListAddRange.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListAddResolution.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListAddString.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListDelete.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListFind.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListFree.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListFromString.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListGetBoolean.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListGetCollection.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListGetDatetime.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListGetInteger.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListGetMetadata.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListGetNext.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListGetRange.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListGetResolution.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListGetString.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListGetValue.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi +papiAttributeListToString.3papi := SOSRC = man3papi/papiAttributeListAddValue.3papi + +papiJobCancel.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobFree.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobGetAttributeList.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobGetId.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobGetJobTicket.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobGetPrinterName.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobHold.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobListFree.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobModify.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobMove.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobPromote.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobQuery.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobRelease.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobRestart.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobStreamClose.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobStreamOpen.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobStreamWrite.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobSubmitByReference.3papi := SOSRC = man3papi/papiJobSubmit.3papi +papiJobValidate.3papi := SOSRC = man3papi/papiJobSubmit.3papi + +papiLibrarySupportedCalls.3papi := SOSRC = man3papi/papiLibrarySupportedCall.3papi + +papiPrinterAdd.3papi := SOSRC = man3papi/papiPrintersList.3papi +papiPrinterDisable.3papi := SOSRC = man3papi/papiPrintersList.3papi +papiPrinterEnable.3papi := SOSRC = man3papi/papiPrintersList.3papi +papiPrinterFree.3papi := SOSRC = man3papi/papiPrintersList.3papi +papiPrinterGetAttributeList.3papi := SOSRC = man3papi/papiPrintersList.3papi +papiPrinterListFree.3papi := SOSRC = man3papi/papiPrintersList.3papi +papiPrinterListJobs.3papi := SOSRC = man3papi/papiPrintersList.3papi +papiPrinterModify.3papi := SOSRC = man3papi/papiPrintersList.3papi +papiPrinterPause.3papi := SOSRC = man3papi/papiPrintersList.3papi +papiPrinterPurgeJobs.3papi := SOSRC = man3papi/papiPrintersList.3papi +papiPrinterQuery.3papi := SOSRC = man3papi/papiPrintersList.3papi +papiPrinterRemove.3papi := SOSRC = man3papi/papiPrintersList.3papi +papiPrinterResume.3papi := SOSRC = man3papi/papiPrintersList.3papi + +papiServiceDestroy.3papi := SOSRC = man3papi/papiServiceCreate.3papi +papiServiceGetAppData.3papi := SOSRC = man3papi/papiServiceCreate.3papi +papiServiceGetAttributeList.3papi := SOSRC = man3papi/papiServiceCreate.3papi +papiServiceGetEncryption.3papi := SOSRC = man3papi/papiServiceCreate.3papi +papiServiceGetPassword.3papi := SOSRC = man3papi/papiServiceCreate.3papi +papiServiceGetServiceName.3papi := SOSRC = man3papi/papiServiceCreate.3papi +papiServiceGetStatusMessage.3papi := SOSRC = man3papi/papiServiceCreate.3papi +papiServiceGetUserName.3papi := SOSRC = man3papi/papiServiceCreate.3papi +papiServiceSetAppData.3papi := SOSRC = man3papi/papiServiceCreate.3papi +papiServiceSetAuthCB.3papi := SOSRC = man3papi/papiServiceCreate.3papi +papiServiceSetEncryption.3papi := SOSRC = man3papi/papiServiceCreate.3papi +papiServiceSetPassword.3papi := SOSRC = man3papi/papiServiceCreate.3papi +papiServiceSetUserName.3papi := SOSRC = man3papi/papiServiceCreate.3papi + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) diff --git a/usr/src/man/man3papi/papiAttributeListAddValue.3papi b/usr/src/man/man3papi/papiAttributeListAddValue.3papi new file mode 100644 index 0000000000..09b700b3ef --- /dev/null +++ b/usr/src/man/man3papi/papiAttributeListAddValue.3papi @@ -0,0 +1,732 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" 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. +.\" 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. +.\" 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] +.TH papiAttributeListAddValue 3PAPI "17 Jan 2007" "SunOS 5.11" "PAPI Library Functions" +.SH NAME +papiAttributeListAddValue, papiAttributeListAddBoolean, +papiAttributeListAddCollection, papiAttributeListAddDatetime, +papiAttributeListAddInteger, papiAttributeListAddMetadata, +papiAttributeListAddRange, papiAttributeListAddResolution, +papiAttributeListAddString, papiAttributeListDelete, papiAttributeListGetValue, +papiAttributeListGetNext, papiAttributeListFind, papiAttributeListGetBoolean, +papiAttributeListGetCollection, papiAttributeListGetDatetime, +papiAttributeListGetInteger, papiAttributeListGetMetadata, +papiAttributeListGetRange, papiAttributeListGetResolution, +papiAttributeListGetString, papiAttributeListFromString, +papiAttributeListToString, papiAttributeListFree \- manage PAPI attribute lists +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpapi\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <papi.h> + +\fBpapi_status_t\fR \fBpapiAttributeListAddValue\fR(\fBpapi_attribute_t ***\fR\fIattrs\fR, + \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBpapi_attribute_value_type_t\fR \fItype\fR, + \fBpapi_attribute_value_t *\fR\fIvalue\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListAddString\fR(\fBpapi_attribute_t ***\fR\fIattrs\fR, + \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBchar *\fR\fIstring\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListAddInteger\fR(\fBpapi_attribute_t ***\fR\fIattrs\fR, + \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBint\fR \fIinteger\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListAddBoolean\fR(\fBpapi_attribute_t ***\fR\fIattrs\fR, + \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBchar\fR \fIboolean\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListAddRange\fR(\fBpapi_attribute_t ***\fR\fIattrs\fR, + \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBint\fR \fIlower\fR, \fBint\fR \fIupper\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListAddResolution\fR(\fBpapi_attribute_t ***\fR\fIattrs\fR, + \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBint\fR \fIxres\fR, \fBint\fR \fIyres\fR, + \fBpapi_resolution_unit_t\fR \fIunits\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListAddDatetime\fR(\fBpapi_attribute_t ***\fR\fIattrs\fR, + \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBtime_t\fR \fIdatetime\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListAddCollection\fR(\fBpapi_attribute_t ***\fR\fIattrs\fR, + \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBpapi_attribute_t **\fR\fIcollection\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListAddMetadata\fR(\fBpapi_attribute_t ***\fR\fIattrs\fR, + \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBpapi_metadata_t\fR \fImetadata\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListDelete\fR(\fBpapi_attribute_t ***\fR\fIattributes\fR, + \fBchar *\fR\fIname\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListGetValue\fR(\fBpapi_attribute_t **\fR\fIlist\fR, + \fBvoid **\fR\fIiterator\fR, \fBchar *\fR\fIname\fR, \fBpapi_attribute_value_type_t\fR \fItype\fR, + \fBpapi_attribute_value_t **\fR\fIvalue\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListGetString\fR(\fBpapi_attribute_t **\fR\fIlist\fR, + \fBvoid **\fR\fIiterator\fR, \fBchar *\fR\fIname\fR, \fBchar **\fR\fIvptr\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListGetInteger\fR(\fBpapi_attribute_t **\fR\fIlist\fR, + \fBvoid **\fR\fIiterator\fR, \fBchar *\fR\fIname\fR, \fBint *\fR\fIvptr\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListGetBoolean\fR(\fBpapi_attribute_t **\fR\fIlist\fR, + \fBvoid **\fR\fIiterator\fR, \fBchar *\fR\fIname\fR, \fBchar *\fR\fIvptr\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListGetRange\fR(\fBpapi_attribute_t **\fR\fIlist\fR, + \fBvoid **\fR\fIiterator\fR, \fBchar *\fR\fIname\fR, \fBint *\fR\fImin\fR, \fBint *\fR\fImax\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListGetResolution\fR(\fBpapi_attribute_t **\fR\fIlist\fR, + \fBvoid **\fR\fIiterator\fR, \fBchar *\fR\fIname\fR, \fBint *\fR\fIx\fR, \fBint *\fR\fIy\fR, + \fBpapi_resolution_unit_t *\fR\fIunits\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListGetDatetime\fR(\fBpapi_attribute_t **\fR\fIlist\fR, + \fBvoid **\fR\fIiterator\fR, \fBchar *\fR\fIname\fR, \fBtime_t *\fR\fIdt\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListGetCollection\fR(\fBpapi_attribute_t **\fR\fIlist\fR, + \fBvoid **\fR\fIiterator\fR, \fBchar *\fR\fIname\fR, \fBpapi_attribute_t ***\fR\fIcollection\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListGetMetadata\fR(\fBpapi_attribute_t **\fR\fIlist\fR, + \fBvoid **\fR\fIiterator\fR, \fBchar *\fR\fIname\fR, \fBpapi_metadata_t *\fR\fIvptr\fR); +.fi + +.LP +.nf +\fBpapi_attribute_t *\fR\fBpapiAttributeListFind\fR(\fBpapi_attribute_t **\fR\fIlist\fR, + \fBchar *\fR\fIname\fR); +.fi + +.LP +.nf +\fBpapi_attribute_t *\fR\fBpapiAttributeListGetNext\fR(\fBpapi_attribute_t **\fR\fIlist\fR, + \fBvoid **\fR\fIiterator\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpapiAttributeListFree\fR(\fBpapi_attribute_t **\fR\fIattributes\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListFromString\fR(\fBpapi_attribute_t ***\fR\fIattrs\fR, + \fBint\fR \fIflags\fR, \fBchar *\fR\fIstring\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiAttributeListToString\fR(\fBpapi_attribute_t **\fR\fIattrs\fR, + \fBchar *\fR\fIdelim\fR, \fBchar *\fR\fIbuffer\fR, \fBsize_t\fR \fIbuflen\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIattrs\fR\fR +.ad +.RS 14n +.rt +address of array of pointers to attributes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIattributes\fR\fR +.ad +.RS 14n +.rt +a list of attributes (of type \fBpapi_attribute_t **\fR) contained in a +collection. Lists can be hierarchical. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIboolean\fR\fR +.ad +.RS 14n +.rt +boolean value (\fBPAPI_TRUE\fR or \fBPAPI_FALSE)\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuffer\fR\fR +.ad +.RS 14n +.rt +buffer to fill +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuflen\fR\fR +.ad +.RS 14n +.rt +length of supplied buffer +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIcollection\fR\fR +.ad +.RS 14n +.rt +list of attributes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdatetime\fR\fR +.ad +.RS 14n +.rt +attribute time value specified in \fBtime_t\fR representation +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdelim\fR\fR +.ad +.RS 14n +.rt +delimiter used in construction of a string representation of an attribute list +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdt\fR\fR +.ad +.RS 14n +.rt +date and time represented as a \fBtime_t\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 14n +.rt +Specify bit fields defining how actions will be performed: +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_ATTR_REPLACE\fR\fR +.ad +.sp .6 +.RS 4n +Free any existing value(s) and replace it with the supplied value(s). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_ATTR_APPEND\fR\fR +.ad +.sp .6 +.RS 4n +Add the supplied value to the attribute. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_ATTR_EXCL\fR\fR +.ad +.sp .6 +.RS 4n +Add the supplied value to the attribute, if the attribute was not previously +defined. +.RE + +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIinteger\fR\fR +.ad +.RS 14n +.rt +integer value +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIiterator\fR\fR +.ad +.RS 14n +.rt +iterator for enumerating multiple values of multi-value attributes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlist\fR\fR +.ad +.RS 14n +.rt +array of pointers to attributes (attribute list) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIlower\fR\fR +.ad +.RS 14n +.rt +lower bound for a range of integer +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImax\fR\fR +.ad +.RS 14n +.rt +maximum value in a range +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImetadata\fR\fR +.ad +.RS 14n +.rt +pseudo-values for specialized attributes \fBPAPI_UNSUPPORTED\fR, +\fBPAPI_DEFAULT\fR, \fBPAPI_UNKNOWN\fR, \fBPAPI_NO_VALUE\fR, +\fBPAPI_NOT_SETTABLE\fR, \fBPAPI_DELETE\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImin\fR\fR +.ad +.RS 14n +.rt +minimum value in a range +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 14n +.rt +attribute name +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstring\fR\fR +.ad +.RS 14n +.rt +string value +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype\fR\fR +.ad +.RS 14n +.rt +attribute type (\fBPAPI_STRING\fR, \fBPAPI_INTEGER\fR, \fBPAPI_BOOLEAN\fR, +\fBPAPI_RANGE\fR, \fBPAPI_RESOLUTION\fR, \fBPAPI_DATETIME\fR, +\fBPAPI_COLLECTION\fR, \fBPAPI_METADATA\fR) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIunits\fR\fR +.ad +.RS 14n +.rt +resolution unit of measure (\fBPAPI_RES_PER_INCH\fR or \fBPAPI_RES_PER_CM\fR) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIupper\fR\fR +.ad +.RS 14n +.rt +upper bound for a range of integer +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvalue\fR\fR +.ad +.RS 14n +.rt +attribute value +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIvptr\fR\fR +.ad +.RS 14n +.rt +pointer to arbitrary data +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIx\fR\fR +.ad +.RS 14n +.rt +horizontal (x) resolution +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIxres\fR\fR +.ad +.RS 14n +.rt +horizontal (x) component of a resolution +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIy\fR\fR +.ad +.RS 14n +.rt +vertical (y) resolution +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIyres\fR\fR +.ad +.RS 14n +.rt +vertical (y) component of a resolution +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpapiAttributeListAdd*()\fR functions add new attributes and/or values to +the attribute list passed in. If necessary, the attribute list passed in is +expanded to contain a new attribute pointer for any new attributes added to the +list. The list is null-terminated. Space for the new attributes and values is +allocated and the name and value are copied into this allocated space. +.sp +.LP +If \fBPAPI_ATTR_REPLACE\fR is specified in flags, any existing attribute values +are freed and replaced with the supplied value. +.sp +.LP +If \fBPAPI_ATTR_APPEND\fR is specified, the supplied value is appended to the +attribute's list of values. +.sp +.LP +If \fBPAPI_ATTR_EXCL\fR is specified, the operation succeeds only if the +attribute was not previously defined. +.sp +.LP +The \fBpapiAttributeListGet*()\fR functions retrieve an attribute value from an +attribute list. If the attribute is a multi-valued attribute, the first call to +retrieve a value should pass in an iterator and attribute name. Subsequent +calls to retrieve additional values should pass in the iterator and a null +value for the attribute name. If a single-valued attribute is to be retrieved, +\fINULL\fR can be used in place of the iterator. +.sp +.LP +Upon successful completion of a get operation, the value passed in (string, +integer, boolean, ...) is changed to the value from the attribute list. If the +operation fails for any reason (type mismatch, not found, ...), the value +passed in remains untouched. +.sp +.LP +The resulting value returned from a get operation is returned from the +attribute list's allocated memory. It is not guaranteed to be available after +the attribute list has been freed. +.sp +.LP +The \fBpapiAttributeListDelete()\fR function removes an attribute from a +supplied list. +.sp +.LP +The \fBpapiAttributeListFind()\fR function allows an application to retrieve an +entire attribute structure from the passed-in attribute list. +.sp +.LP +The \fBpapiAttributeListGetNext()\fR function allows an application to walk +through an attribute list returning subsequent attributes from the list. With +the first call, the iterator should be initialized to \fINULL\fR and subsequent +calls should use \fINULL\fR for the list argument. +.sp +.LP +The \fBpapiAttributeListFree()\fR function deallocates all memory associated +with an attribute list, including values that might have been retrieved +previously using \fBpapiAttributeListGet*()\fR calls. +.sp +.LP +The \fBpapiAttributeListFromString()\fR function takes in a string +representation of a set of attributes, parses the string and adds the +attributes to the passed in attribute list using the flags to determine how to +add them. String values are specified with "key=value". Integer values are +specified with "key=number". Boolean values are specified with either +"key=(true|false)" or "[no]key". Multiple attributes can be specified in the +string by separating them with a whitespace character. +.sp +.LP +The \fBpapiAttributeListToString()\fR function converts an attribute list to a +string representation that can be displayed to a user. The delimiter value is +placed between attributes in the string. +.SH RETURN VALUES +.sp +.LP +These functions return \fBPAPI_OK\fR upon successful completion and one of the +following on failure: +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_BAD_ARGUMENT\fR\fR +.ad +.RS 24n +.rt +The supplied arguments were not valid. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_CONFLICT\fR\fR +.ad +.RS 24n +.rt +There was an attribute type mismatch. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_NOT_FOUND\fR\fR +.ad +.RS 24n +.rt +The requested attribute could not be found. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_NOT_POSSIBLE\fR\fR +.ad +.RS 24n +.rt +The requested operation could not be performed due to buffer overflow. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_TEMPORARY_ERROR\fR\fR +.ad +.RS 24n +.rt +Memory could not be allocated to add to the attribute list. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRThe following example manipulates a PAPI attribute list. +.sp +.in +2 +.nf +/* + * program to manipulate a PAPI attribute list + */ +#include <stdio.h> +#include <papi.h> + +/*ARGSUSED*/ +int +main(int ac, char *av[]) +{ + char buf[BUFSIZ]; + papi_status_t status; + papi_attribute_t **list = NULL; + void *iter = NULL; + char *string = NULL; + int32_t integer = 0; + + /* build an attribute list */ + (void) papiAttributeListAddString(&list, PAPI_ATTR_EXCL, + "job-title", "example"); + (void) papiAttributeListAddInteger(&list, PAPI_ATTR_EXCL, + "copies", 1); + (void) papiAttributeListFromString(&list, PAPI_ATTR_REPLACE, av[1]); + status = papiAttributeListAddString(&list, PAPI_ATTR_EXCL, + "document-format", "text/plain"); + if (status != PAPI_OK) + printf("failed to set document-format to text/plain: %s\en", + papiStatusString(status)); + + /* dump the list */ + status = papiAttributeListToString(list, "\en\et", buf, sizeof (buf)); + if (status == PAPI_OK) + printf("Attributes: %s\en", buf); + else + printf("Attribute list to big to dump\en"); + + + /* retreive various elements */ + integer = 12; + (void) papiAttributeListGetInteger(list, NULL, "copies", &integer); + printf("copies: %d\en", integer); + + string = NULL; + for (status = papiAttributeListGetString(list, &oter, + "job-files", &string); + status == PAPI_OK; + status = papiAttributeListGetString(list, &iter, NULL, &string)) + printf("file: %s\en", string); + + papiAttributeListFree(list); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityVolatile +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpapi\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3papi/papiJobSubmit.3papi b/usr/src/man/man3papi/papiJobSubmit.3papi new file mode 100644 index 0000000000..76ad3facfc --- /dev/null +++ b/usr/src/man/man3papi/papiJobSubmit.3papi @@ -0,0 +1,771 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" 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. +.\" 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. +.\" 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] +.TH papiJobSubmit 3PAPI "17 Jan 2007" "SunOS 5.11" "PAPI Library Functions" +.SH NAME +papiJobSubmit, papiJobSubmitByReference, papiJobValidate, papiJobStreamOpen, +papiJobStreamWrite, papiJobStreamClose, papiJobQuery, papiJobModify, +papiJobMove, papiJobCancel, papiJobHold, papiJobRelease, papiJobRestart, +papiJobPromote, papiJobGetAttributeList, papiJobGetPrinterName, papiJobGetId, +papiJobGetJobTicket, papiJobFree, papiJobListFree \- job object manipulation +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpapi\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <papi.h> + +\fBpapi_status_t\fR \fBpapiJobSubmit\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIprinter\fR, \fBpapi_attribute_t **\fR\fIjob_attributes\fR, + \fBpapi_job_ticket_t *\fR\fIjob_ticket\fR, \fBchar **\fR\fIfiles\fR, + \fBpapi_job_t *\fR\fIjob\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiJobSubmitByReference\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIprinter\fR, \fBpapi_attribute_t **\fR\fIjob_attributes\fR, + \fBpapi_job_ticket_t *\fR\fIjob_ticket\fR, \fBchar **\fR\fIfiles\fR, + \fBpapi_job_t *\fR\fIjob\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiJobValidate\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIprinter\fR, \fBpapi_attribute_t **\fR\fIjob_attributes\fR, + \fBpapi_job_ticket_t *\fR\fIjob_ticket\fR, \fBchar **\fR\fIfiles\fR, + \fBpapi_job_t *\fR\fIjob\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiJobStreamOpen\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIprinter\fR, \fBpapi_attribute_t **\fR\fIjob_attributes\fR, + \fBpapi_job_ticket_t *\fR\fIjob_ticket\fR, \fBpapi_stream_t *\fR\fIstream\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiJobStreamWrite\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBpapi_stream_t\fR \fIstream\fR, \fBvoid *\fR\fIbuffer\fR, \fBsize_t\fR \fIbuflen\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiJobStreamClose\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBpapi_stream_t\fR \fIstream\fR, \fBpapi_job_t *\fR\fIjob\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiJobQuery\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIprinter\fR, \fBint32_t\fR \fIjob_id\fR, \fBchar **\fR\fIrequested_attrs\fR, + \fBpapi_job_t *\fR\fIjob\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiJobModify\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIprinter\fR, \fBint32_t\fR \fIjob_id\fR, + \fBpapi_attribute_t **\fR\fIattributes\fR, \fBpapi_job_t *\fR\fIjob\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiJobMove\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIprinter\fR, \fBint32_t\fR \fIjob_id\fR, \fBchar *\fR\fIdestination\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiJobCancel\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIprinter\fR, \fBint32_t\fR \fIjob_id\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiJobHold\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIprinter\fR, \fBint32_t\fR \fIjob_id\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiJobRelease\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIprinter\fR, \fBint32_t\fR \fIjob_id\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiJobRestart\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIprinter\fR, \fBint32_t\fR \fIjob_id\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiJobPromote\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIprinter\fR, \fBint32_t\fR \fIjob_id\fR); +.fi + +.LP +.nf +\fBpapi_attribute_t **\fR\fBpapiJobGetAttributeList\fR(\fBpapi_job_t\fR \fIjob\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBpapiJobGetPrinterName\fR(\fBpapi_job_t\fR \fIjob\fR); +.fi + +.LP +.nf +\fBint32_t\fR \fBpapiJobGetId\fR(\fBpapi_job_t\fR \fIjob\fR); +.fi + +.LP +.nf +\fBpapi_job_ticket_t *\fR\fBpapiJobGetJobTicket\fR(\fBpapi_job_t\fR \fIjob\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpapiJobFree\fR(\fBpapi_job_t\fR \fIjob\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpapiJobListFree\fR(\fBpapi_job_t *\fR\fIjobs\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIattributes\fR\fR +.ad +.RS 19n +.rt +a set of attributes to be applied to a printer object +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbuffer\fR\fR +.ad +.RS 19n +.rt +a buffer of data to be written to the job stream +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIbufflen\fR\fR +.ad +.RS 19n +.rt +the size of the supplied buffer +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIdestination\fR\fR +.ad +.RS 19n +.rt +the name of the printer where a print job should be relocated, which must +reside within the same print services as the job is currently queued +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfiles\fR\fR +.ad +.RS 19n +.rt +files to use during job submission +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 19n +.rt +a pointer to a handle to be used for all PAPI operations that is created by +calling \fBpapiServiceCreate()\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIjob\fR\fR +.ad +.RS 19n +.rt +a pointer to a printer object (initialized to NULL) to be filled in by +\fBpapiJobQuery()\fR, \fBpapiJobSubmit()\fR, \fBpapiJobSubmitByReference()\fR, +\fBpapiJobValidate()\fR, \fBpapiJobStreamClose()\fR, and \fBpapiJobModify()\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIjob_attributes\fR\fR +.ad +.RS 19n +.rt +attributes to apply during job creation or modification +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIjob_id\fR\fR +.ad +.RS 19n +.rt +ID number of the job reported on or manipulated +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIjob_ticket\fR\fR +.ad +.RS 19n +.rt +unused +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIjobs\fR\fR +.ad +.RS 19n +.rt +a list of job objects returned by \fBpapiPrinterListJobs()\fR or +\fBpapiPrinterPurgeJobs()\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprinter\fR\fR +.ad +.RS 19n +.rt +name of the printer where the job is or should reside +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrequested_attrs\fR\fR +.ad +.RS 19n +.rt +a null-terminated array of pointers to attribute names requested during job +enumeration (\fBpapiPrinterListJobs()\fR) or job query (\fBpapiJobQuery()\fR) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIstream\fR\fR +.ad +.RS 19n +.rt +a communication endpoint for sending print job data +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpapiJobSubmit()\fR function creates a print job containing the passed in +files with the supplied attributes. When the function returns, the data in the +passed files will have been copied by the print service. A job object is +returned that reflects the state of the job. +.sp +.LP +The \fBpapiJobSubmitByReference()\fR function creates a print job containing +the passed in files with the supplied attributes. When the function returns, +the data in the passed files might have been copied by the print service. A job +object is returned that reflects the state of the job. +.sp +.LP +The \fBpapiJobStreamOpen()\fR, \fBpapiJobStreamWrite()\fR, +\fBpapiJobStreamClose()\fR functions create a print job by opening a stream, +writing to the stream, and closing it. +.sp +.LP +The \fBpapiJobValidate()\fR function validates that the supplied attributes and +files will result in a valid print job. +.sp +.LP +The \fBpapiJobQuery()\fR function retrieves job information from the print +service. +.sp +.LP +The \fBpapiJobModify()\fR function modifies a queued job according to the +attribute list passed into the call. A job object is returned that reflects +the state of the job after the modification has been applied. +.sp +.LP +The \fBpapiJobMove()\fR function moves a job from its current queue to the +named destination within the same print service. +.sp +.LP +The \fBpapiJobCancel()\fR function removes a job from the queue. +.sp +.LP +The \fBpapiJobHold()\fR and \fBpapiJobRelease()\fR functions set the job state +to "held" or "idle" to indicate whether the job is eligible for processing. +.sp +.LP +The \fBpapiJobRestart()\fR function restarts processing of a currently queued +print job. +.sp +.LP +The \fBpapiJobGetAttributeList()\fR function returns a list of attributes +describing the job. This list can be searched and/or enumerated using +\fBpapiAttributeList*()\fR calls. See \fBpapiAttributeListAddValue\fR(3PAPI). +.sp +.LP +The \fBpapiJobGetPrinterName()\fR function returns the name of the queue where +the job is currently queued. +.sp +.LP +The \fBpapiJobGetId()\fR function returns a job identifier number from the job +object passed in. +.sp +.LP +The \fBpapiJobPromote()\fR function moves a job to the head of the print queue. +.sp +.LP +The \fBpapiJobGetJobTicket()\fR function retrieves a pointer to a job ticket +associated with the job object. +.sp +.LP +The \fBpapiJobFree()\fR and \fBpapiJobListFree()\fR functions deallocate memory +allocated for the return of printer object(s) from functions that return +printer objects. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, all \fBpapiJob*()\fR functions that return a value +return \fBPAPI_OK\fR. Otherwise, they return an appropriate \fBpapi_status_t\fR +indicating the type of failure. +.sp +.LP +Upon successful completion, \fBpapiJobGetAttributeList()\fR returns a pointer +to the requested data. Otherwise, it returns \fINULL\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fREnumerate all jobs in a queue +.sp +.in +2 +.nf +/* + * program to enumerate queued jobs using PAPI interfaces. + */ +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +#include <libintl.h> +#include <pwd.h> +#include <papi.h> + +static int +authCB(papi_service_t svc, void *app_data) +{ + char prompt[BUFSIZ]; + char *user, *svc_name, *passphrase; + + /* get the name of the service we are contacting */ + if ((svc_name = papiServiceGetServiceName(svc)) == NULL) + return (-1); + + /* find out who we are supposed to be */ + if ((user = papiServiceGetUserName(svc)) == NULL) { + struct passwd *pw; + + if ((pw = getpwuid(getuid())) != NULL) + user = pw->pw_name; + else + user = "nobody"; + } + + /* build the prompt string */ + snprintf(prompt, sizeof (prompt), + gettext("passphrase for %s to access %s: "), user, + svc_name); + + /* ask for the passphrase */ + if ((passphrase = getpassphrase(prompt)) != NULL) + papiServiceSetPassword(svc, passphrase); + + return (0); +} + +/*ARGSUSED*/ +int +main(int ac, char *av[]) +{ + papi_status_t status; + papi_service_t svc = NULL; + papi_job_t *jobs = NULL; + char *svc_name = NULL; + char *pname = "unknown"; + int c; + + while ((c = getopt(ac, av, "s:p:")) != EOF) + switch (c) { + case 's': + svc_name = optarg; + break; + case 'p': + pname = optarg; + break; + } + + status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB, + PAPI_ENCRYPT_NEVER, NULL); + + if (status != PAPI_OK) { + printf("papiServiceCreate(%s): %s\n", svc_name ? svc_name : + "NULL", papiStatusString(status)); + papiServiceDestroy(svc); + exit(1); + } + + status = papiPrinterListJobs(svc, pname, NULL, 0, 0, &jobs); + if (status != PAPI_OK) { + printf("papiPrinterListJobs(%s): %s\n", pname, + papiStatusString(status)); + papiServiceDestroy(svc); + exit(1); + } + + if (jobs != NULL) { + int i; + + for (i = 0; jobs[i] != NULL; i++) { + papi_attribute_t **list = papiJobGetAttributeList(jobs[i]); + + if (list != NULL) { + char *name = "unknown"; + int32_t id = 0; + char *buffer = NULL; + size_t size = 0; + + (void) papiAttributeListGetString(list, NULL, + "printer-name", &name); + (void) papiAttributeListGetInteger(list, NULL, + "job-id", &id); + while (papiAttributeListToString(list, "\n\t", buffer, + size) != PAPI_OK) + buffer = realloc(buffer, size += BUFSIZ); + + printf("%s-%d:\n\t%s\n", name, id, buffer); + free(buffer); + } + } + papiJobListFree(jobs); + } + + papiServiceDestroy(svc); + + exit(0); +} +.fi +.in -2 + +.LP +\fBExample 2 \fRDump all job attributes. +.sp +.in +2 +.nf +/* + * program to dump a queued job's attributes using PAPI interfaces. + */ +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +#include <libintl.h> +#include <pwd.h> +#include <papi.h> + +static int +authCB(papi_service_t svc, void *app_data) +{ + char prompt[BUFSIZ]; + char *user, *svc_name, *passphrase; + + /* get the name of the service we are contacting */ + if ((svc_name = papiServiceGetServiceName(svc)) == NULL) + return (-1); + + /* find out who we are supposed to be */ + if ((user = papiServiceGetUserName(svc)) == NULL) { + struct passwd *pw; + + if ((pw = getpwuid(getuid())) != NULL) + user = pw->pw_name; + else + user = "nobody"; + } + + /* build the prompt string */ + snprintf(prompt, sizeof (prompt), + gettext("passphrase for %s to access %s: "), user, + svc_name); + + /* ask for the passphrase */ + if ((passphrase = getpassphrase(prompt)) != NULL) + papiServiceSetPassword(svc, passphrase); + + return (0); +} + +/*ARGSUSED*/ +int +main(int ac, char *av[]) +{ + papi_status_t status; + papi_service_t svc = NULL; + papi_job_t job = NULL; + char *svc_name = NULL; + char *pname = "unknown"; + int id = 0; + int c; + + while ((c = getopt(ac, av, "s:p:j:")) != EOF) + switch (c) { + case 's': + svc_name = optarg; + break; + case 'p': + pname = optarg; + break; + case 'j': + id = atoi(optarg); + break; + } + + status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB, + PAPI_ENCRYPT_NEVER, NULL); + + if (status != PAPI_OK) { + printf("papiServiceCreate(%s): %s\n", svc_name ? svc_name : + "NULL", papiStatusString(status)); + papiServiceDestroy(svc); + exit(1); + } + + status = papiJobQuery(svc, pname, id, NULL, &job); + if ((status == PAPI_OK) && (job != NULL)) { + papi_attribute_t **list = papiJobGetAttributeList(job); + + if (list != NULL) { + char *name = "unknown"; + int32_t id = 0; + char *buffer = NULL; + size_t size = 0; + + (void) papiAttributeListGetString(list, NULL, + "printer-name", &name); + (void) papiAttributeListGetInteger(list, NULL, + "job-id", &id); + while (papiAttributeListToString(list, "\n\t", buffer, size) + != PAPI_OK) + buffer = realloc(buffer, size += BUFSIZ); + + printf("%s-%d:\n\t%s\n", name, id, buffer); + free(buffer); + } + } else + printf("papiJobQuery(%s-%d): %s\n", pname, id, + papiStatusString(status)); + + papiJobFree(job); + papiServiceDestroy(svc); + + exit(0); +} +.fi +.in -2 + +.LP +\fBExample 3 \fRSubmit a job (stream). +.sp +.in +2 +.nf +/* + * program to submit a job from standard input. + */ +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +#include <libintl.h> +#include <pwd.h> +#include <papi.h> + +static int +authCB(papi_service_t svc, void *app_data) +{ + char prompt[BUFSIZ]; + char *user, *svc_name, *passphrase; + + /* get the name of the service we are contacting */ + if ((svc_name = papiServiceGetServiceName(svc)) == NULL) + return (-1); + + /* find out who we are supposed to be */ + if ((user = papiServiceGetUserName(svc)) == NULL) { + struct passwd *pw; + + if ((pw = getpwuid(getuid())) != NULL) + user = pw->pw_name; + else + user = "nobody"; + } + + /* build the prompt string */ + snprintf(prompt, sizeof (prompt), + gettext("passphrase for %s to access %s: "), user, + svc_name); + + /* ask for the passphrase */ + if ((passphrase = getpassphrase(prompt)) != NULL) + papiServiceSetPassword(svc, passphrase); + + return (0); +} + +/*ARGSUSED*/ +int +main(int ac, char *av[]) +{ + papi_status_t status; + papi_service_t svc = NULL; + papi_stream_t stream = NULL; + papi_job_t job = NULL; + papi_attribute_t **attrs = NULL; + char *svc_name = NULL; + char *pname = "unknown"; + int id = 0; + int c; + int rc; + char buf[BUFSIZ]; + + while ((c = getopt(ac, av, "s:p:")) != EOF) + switch (c) { + case 's': + svc_name = optarg; + break; + case 'p': + pname = optarg; + break; + } + + status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB, + PAPI_ENCRYPT_NEVER, NULL); + + if (status != PAPI_OK) { + printf("papiServiceCreate(%s): %s\n", svc_name ? svc_name : + "NULL", papiStatusString(status)); + papiServiceDestroy(svc); + exit(1); + } + + papiAttributeListAddInteger(&attrs, PAPI_ATTR_EXCL, "copies", 1); + papiAttributeListAddString(&attrs, PAPI_ATTR_EXCL, + "document-format", "application/octet-stream"); + papiAttributeListAddString(&attrs, PAPI_ATTR_EXCL, + "job-title", "Standard Input"); + + status = papiJobStreamOpen(svc, pname, attrs, NULL, &stream); + while ((status == PAPI_OK) && ((rc = read(0, buf, + sizeof (buf))) > 0)) + status = papiJobStreamWrite(svc, stream, buf, rc); + + if (status == PAPI_OK) + status = papiJobStreamClose(svc, stream, &job); + + + if ((status == PAPI_OK) && (job != NULL)) { + papi_attribute_t **list = papiJobGetAttributeList(job); + + if (list != NULL) { + char *name = "unknown"; + int32_t id = 0; + char *buffer = NULL; + size_t size = 0; + + (void) papiAttributeListGetString(list, NULL, + "printer-name", &name); + (void) papiAttributeListGetInteger(list, NULL, + "job-id", &id); + while (papiAttributeListToString(list, "\n\t", buffer, size) + != PAPI_OK) + buffer = realloc(buffer, size += BUFSIZ); + + printf("%s-%d:\n\t%s\n", name, id, buffer); + free(buffer); + } + } else + printf("papiJobStream*(%s-%d): %s\n", pname, id, + papiStatusString(status)); + + papiJobFree(job); + papiServiceDestroy(svc); + + exit(0); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityVolatile +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpapi\fR(3LIB), \fBpapiAttributeListAddValue\fR(3PAPI), +\fBattributes\fR(5) diff --git a/usr/src/man/man3papi/papiLibrarySupportedCall.3papi b/usr/src/man/man3papi/papiLibrarySupportedCall.3papi new file mode 100644 index 0000000000..df2710027c --- /dev/null +++ b/usr/src/man/man3papi/papiLibrarySupportedCall.3papi @@ -0,0 +1,79 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" 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. +.\" 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. +.\" 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] +.TH papiLibrarySupportedCall 3PAPI "17 Jan 2007" "SunOS 5.11" "PAPI Library Functions" +.SH NAME +papiLibrarySupportedCall, papiLibrarySupportedCalls \- determine if a PAPI +function returns valid data +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpapi\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <papi.h> + +\fBchar\fR \fBpapiLibrarySupportedCall\fR(\fBconst char *\fR\fIname\fR); +.fi + +.LP +.nf +\fBchar **\fR\fBpapiLibrarySupportedCalls\fR(\fBvoid\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 8n +.rt +the name of a PAPI function +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpapiLibrarySupportedCall()\fR function queries to determine if a +particular PAPI function returns valid data other than +\fBPAPI_OPERATION_NOT_SUPPORTED\fR. +.sp +.LP +The \fBpapiLibrarySupportedCalls()\fR function enumerates all PAPI functions +that return valid data other than \fBPAPI_OPERATION_NOT_SUPPORTED\fR. +.SH RETURN VALUES +.sp +.LP +The \fBpapiLibrarySupportedCall()\fR function returns \fBPAPI_TRUE\fR if the +specified PAPI function returns valid data other than +\fBPAPI_OPERATION_NOT_SUPPORTED\fR. Otherwise, \fBPAPI_FALSE\fR is returned. +.sp +.LP +The \fBpapiLibrarySupportedCalls()\fR function returns a null-terminated array +of strings listing all of the PAPI functions that return valid data other than +\fBPAPI_OPERATION_NOT_SUPPORTED\fR. Otherwise, \fINULL\fR is returned. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityVolatile +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpapi\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3papi/papiPrintersList.3papi b/usr/src/man/man3papi/papiPrintersList.3papi new file mode 100644 index 0000000000..cc0e2c1741 --- /dev/null +++ b/usr/src/man/man3papi/papiPrintersList.3papi @@ -0,0 +1,570 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" 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. +.\" 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. +.\" 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] +.TH papiPrintersList 3PAPI "17 Jan 2007" "SunOS 5.11" "PAPI Library Functions" +.SH NAME +papiPrintersList, papiPrinterQuery, papiPrinterAdd, papiPrinterModify, +papiPrinterRemove, papiPrinterDisable, papiPrinterEnable, papiPrinterPause, +papiPrinterResume, papiPrinterPurgeJobs, papiPrinterListJobs, +papiPrinterGetAttributeList, papiPrinterFree, papiPrinterListFree \- print +object manipulation +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpapi\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <papi.h> + +\fBpapi_status_t\fR \fBpapiPrintersList\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar **\fR\fIrequested_attrs\fR, \fBpapi_filter_t *\fR\fIfilter\fR, + \fBpapi_printer_t **\fR\fIprinters\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiPrinterQuery\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR, + \fBchar **\fR\fIrequested_attrs\fR, \fBpapi_attribute_t **\fR\fIjob_attributes\fR, + \fBpapi_printer_t *\fR\fIprinter\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiPrinterAdd\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR, + \fBpapi_attribute_t **\fR\fIattributes\fR, \fBpapi_printer_t *\fR\fIprinter\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiPrinterModify\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR, + \fBpapi_attribute_t **\fR\fIattributes\fR, \fBpapi_printer_t *\fR\fIprinter\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiPrinterRemove\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiPrinterDisable\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR, + \fBchar *\fR\fImessage\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiPrinterEnable\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiPrinterPause\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR, + \fBchar *\fR\fImessage\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiPrinterResume\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiPrinterPurgeJobs\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR, + \fBpapi_job_t **\fR\fIjobs\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiPrinterListJobs\fR(\fBpapi_service_t\fR \fIhandle\fR, \fBchar *\fR\fIname\fR, + \fBchar **\fR\fIrequested_attrs\fR, \fBint\fR \fItype_mask\fR, \fBint\fR \fImax_num_jobs\fR, + \fBpapi_job_t **\fR\fIjobs\fR); +.fi + +.LP +.nf +\fBpapi_attribute_t **\fR\fBpapiPrinterGetAttributeList\fR(\fBpapi_printer_t\fR \fIprinter\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpapiPrinterFree\fR(\fBpapi_printer_t\fR \fIprinter\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpapiPrinterListFree\fR(\fBpapi_printer_t *\fR\fIprinters\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIattributes\fR\fR +.ad +.RS 19n +.rt +a set of attributes to be applied to a printer object +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIfilter\fR\fR +.ad +.RS 19n +.rt +a filter to be applied during printer enumeration +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 19n +.rt +a pointer to a handle to be used for all PAPI operations, created by calling +\fBpapiServiceCreate()\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIjob_attributes\fR\fR +.ad +.RS 19n +.rt +unused +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIjobs\fR\fR +.ad +.RS 19n +.rt +a pointer to a list to return job objects (initialized to \fINULL\fR) +enumerated by \fBpapiPrinterGetJobs()\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImax_num_jobs\fR\fR +.ad +.RS 19n +.rt +the maximum number of jobs to return from a \fBpapiPrinterGetJobs()\fR request +.RE + +.sp +.ne 2 +.mk +.na +\fB\fImessage\fR\fR +.ad +.RS 19n +.rt +a message to be associated with a printer while disabled or paused +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIname\fR\fR +.ad +.RS 19n +.rt +the name of the printer object being operated on +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprinter\fR\fR +.ad +.RS 19n +.rt +a pointer to a printer object (initialized to \fINULL\fR) to be filled in by +\fBpapiPrinterQuery()\fR, \fBpapiPrinterAdd()\fR, and \fBpapiPrinterModify()\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIprinters\fR\fR +.ad +.RS 19n +.rt +a pointer to a list to return printer objects (initialized to \fINULL\fR) +enumerated by \fBpapiPrintersList()\fR +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIrequested_attrs\fR\fR +.ad +.RS 19n +.rt +a null-terminated array of pointers to attribute names requested during printer +enumeration (\fBpapiPrintersList()\fR), printer query +(\fBpapiPrinterQuery()\fR), or job enumeration (\fBpapiPrinterListJobs()\fR) +.RE + +.sp +.ne 2 +.mk +.na +\fB\fItype_mask\fR\fR +.ad +.RS 19n +.rt +a bit field indicating which type of jobs to return \fBPAPI_LIST_JOBS_OTHERS\fR +include jobs submitted by others. The default is to report only on your own +jobs +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_LIST_JOBS_COMPLETED\fR\fR +.ad +.sp .6 +.RS 4n +include completed jobs +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_LIST_JOBS_NOT_COMPLETED\fR\fR +.ad +.sp .6 +.RS 4n +include jobs not complete +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_LIST_JOBS_ALL\fR\fR +.ad +.sp .6 +.RS 4n +report on all jobs +.RE + +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpapiPrintersList()\fR function retrieves the requested attributes from +the print service(s) for all available printers. Because the Solaris +implementation is name service-enabled, applications should retrieve only the +\fBprinter-name\fR and \fBprinter-uri-supported\fR attributes using this +function, thereby reducing the overhead involved in generating a printer list. +Further integration of printer state and capabilities can be performed with +\fBpapiPrinterQuery()\fR. +.sp +.LP +The \fBpapiPrinterAdd()\fR, \fBpapiPrinterModify()\fR, and +\fBpapiPrinterRemove()\fR functions allow for creation, modification, and +removal of print queues. Print queues are added or modified according to the +attribute list passed into the call. A printer object is returned that reflects +the configuration of the printer after the addition or modification has been +applied. At this time, they provide only minimal functionality and only for +the LP print service. +.sp +.LP +The \fBpapiPrinterDisable()\fR and \fBpapiPrinterEnable()\fR functions allow +applications to turn off and on queueing (accepting print requests) for a print +queue. The \fBpapiPrinterEnable()\fR and \fBpapiPrinterDisable()\fR functions +allow applications to turn on and off print job processing for a print queue. +.sp +.LP +The \fBpapiPrinterPause()\fR function stops queueing of print jobs on the named +print queue. +.sp +.LP +The \fBpapiPrinterResume()\fR function resumes queueing of print jobs on the +named print queue. +.sp +.LP +The \fBpapiPrinterPurgeJobs()\fR function allows applications to delete all +print jobs that it has privilege to remove. A list of cancelled jobs is +returned in the jobs argument. +.sp +.LP +The \fBpapiPrinterListJobs()\fR function enumerates print jobs on a particular +queue. \fBpapiPrinterGetAttributeList()\fR retrieves an attribute list from a +printer object. +.sp +.LP +The \fBpapiPrinterGetAttributeList()\fR function retrieves an attribute list +from a printer object returned from \fBpapiPrinterQuery()\fR, +\fBpapiPrintersList()\fR, \fBpapiPrinterModify()\fR, and +\fBpapiPrinterAdd()\fR. This attribute list can be searched for various +information about the printer object. +.sp +.LP +The \fBpapiPrinterFree()\fR and \fBpapiPrinterListFree()\fR functions +deallocate memory allocated for the return of printer object(s) from functions +that return printer objects. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, all functions that return a value return +\fBPAPI_OK\fR. Otherwise, they return an appropriate \fBpapi_status_t()\fR +indicating the type of failure. +.sp +.LP +Upon successful completion, \fBpapiPrinterGetAttributeList()\fR returns a +pointer to the requested data. Otherwise, it returns \fINULL\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fREnumerate all available printers. +.sp +.in +2 +.nf +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +#include <libintl.h> +#include <pwd.h> +#include <papi.h> + +static int +authCB(papi_service_t svc, void *app_data) +{ + char prompt[BUFSIZ]; + char *user, *svc_name, *passphrase; + + /* get the name of the service we are contacting */ + if ((svc_name = papiServiceGetServiceName(svc)) == NULL) + return (-1); + + /* find out who we are supposed to be */ + if ((user = papiServiceGetUserName(svc)) == NULL) { + struct passwd *pw; + + if ((pw = getpwuid(getuid())) != NULL) + user = pw->pw_name; + else + user = "nobody"; + } + + /* build the prompt string */ + snprintf(prompt, sizeof (prompt), + gettext("passphrase for %s to access %s: "), user, + svc_name); + + /* ask for the passphrase */ + if ((passphrase = getpassphrase(prompt)) != NULL) + papiServiceSetPassword(svc, passphrase); + + return (0); +} + +/*ARGSUSED*/ +int +main(int ac, char *av[]) +{ + papi_status_t status; + papi_service_t svc = NULL; + papi_printer_t *printers = NULL; + char *attrs[] = { "printer-name", "printer-uri-supported", NULL }; + char *svc_name = NULL; + int c; + + while ((c = getopt(ac, av, "s:")) != EOF) + switch (c) { + case 's': + svc_name = optarg; + break; + } + + status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB, + PAPI_ENCRYPT_NEVER, NULL); + + if (status != PAPI_OK) { + printf("papiServiceCreate(%s): %s\en", svc_name ? svc_name : + "NULL", papiStatusString(status)); + papiServiceDestroy(svc); + exit(1); + } + + status = papiPrintersList(svc, attrs, NULL, &printers); + if (status != PAPI_OK) { + printf("papiPrintersList(%s): %s\en", svc_name ? svc_name : + "NULL", papiStatusString(status)); + papiServiceDestroy(svc); + exit(1); + } + + if (printers != NULL) { + int i; + + for (i = 0; printers[i] != NULL; i++) { + papi_attribute_t **list = + papiPrinterGetAttributeList(printers[i]); + + if (list != NULL) { + char *name = "unknown"; + char *uri = "unknown"; + + (void) papiAttributeListGetString(list, NULL, + "printer-name", &name); + + (void) papiAttributeListGetString(list, NULL, + "printer-uri-supported", &uri); + printf("%s is %s\n", name, uri); + } + } + papiPrinterListFree(printers); + } + + papiServiceDestroy(svc); + + exit(0); +} +.fi +.in -2 + +.LP +\fBExample 2 \fRDump all printer attributes. +.sp +.in +2 +.nf +/* + * program to query a printer for it's attributes via PAPI + */ +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +#include <libintl.h> +#include <pwd.h> +#include <papi.h> + +static int +authCB(papi_service_t svc, void *app_data) +{ + char prompt[BUFSIZ]; + char *user, *svc_name, *passphrase; + + /* get the name of the service we are contacting */ + if ((svc_name = papiServiceGetServiceName(svc)) == NULL) + return (-1); + + /* find out who we are supposed to be */ + if ((user = papiServiceGetUserName(svc)) == NULL) { + struct passwd *pw; + + if ((pw = getpwuid(getuid())) != NULL) + user = pw->pw_name; + else + user = "nobody"; + } + + /* build the prompt string */ + snprintf(prompt, sizeof (prompt), + gettext("passphrase for %s to access %s: "), user, + svc_name); + + /* ask for the passphrase */ + if ((passphrase = getpassphrase(prompt)) != NULL) + papiServiceSetPassword(svc, passphrase); + + return (0); +} + +/*ARGSUSED*/ +int +main(int ac, char *av[]) +{ + papi_status_t status; + papi_service_t svc = NULL; + papi_printer_t printer = NULL; + char *svc_name = NULL; + char *pname = "unknown"; + int c; + + while ((c = getopt(ac, av, "s:p:")) != EOF) + switch (c) { + case 's': + svc_name = optarg; + break; + case 'p': + pname = optarg; + break; + } + + status = papiServiceCreate(&svc, svc_name, NULL, NULL, authCB, + PAPI_ENCRYPT_NEVER, NULL); + + if (status != PAPI_OK) { + printf("papiServiceCreate(%s): %s\en", svc_name ? svc_name : + "NULL", papiStatusString(status)); + papiServiceDestroy(svc); + exit(1); + } + + status = papiPrinterQuery(svc, pname, NULL, NULL, &printer); + if ((status == PAPI_OK) && (printer != NULL)) { + papi_attribute_t **list = papiPrinterGetAttributeList(printer); + char *buffer = NULL; + size_t size = 0; + + while (papiAttributeListToString(list, "\en\et", buffer, size) + != PAPI_OK) + buffer = realloc(buffer, size += BUFSIZ); + + printf("%s:\en\et%s\en", pname, buffer); + } else + printf("papiPrinterQuery(%s): %s\en", pname, + papiStatusString(status)); + + papiPrinterFree(printer); + papiServiceDestroy(svc); + + exit(0); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityVolatile +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpapi\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3papi/papiServiceCreate.3papi b/usr/src/man/man3papi/papiServiceCreate.3papi new file mode 100644 index 0000000000..916ddf6e42 --- /dev/null +++ b/usr/src/man/man3papi/papiServiceCreate.3papi @@ -0,0 +1,334 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" 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. +.\" 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. +.\" 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] +.TH papiServiceCreate 3PAPI "17 Jan 2007" "SunOS 5.11" "PAPI Library Functions" +.SH NAME +papiServiceCreate, papiServiceDestroy, papiServiceSetUserName, +papiServiceSetPassword, papiServiceSetEncryption, papiServiceSetAuthCB, +papiServiceSetAppData, papiServiceGetServiceName, papiServiceGetUserName, +papiServiceGetPassword, papiServiceGetEncryption, papiServiceGetAppData, +papiServiceGetAttributeList, papiServiceGetStatusMessage \- service context +manipulation +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpapi\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <papi.h> + +\fBpapi_status_t\fR \fBpapiServiceCreate\fR(\fBpapi_service_t *\fR\fIhandle\fR, + \fBchar *\fR\fIservice_name,\fR \fBchar *\fR\fIuser_name,\fR \fBchar *\fR\fIpassword\fR, + \fBint\fR (\fB*\fR\fIauthCB\fR)(\fBpapi_service_t\fR \fIsvc\fR, \fBvoid *\fR\fIapp_data\fR), + \fBpapi_encryption_t\fR \fIencryption\fR, \fBvoid *\fR\fIapp_data\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBpapiServiceDestroy\fR(\fBpapi_service_t\fR \fIhandle\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiServiceSetUserName\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIuser_name\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiServiceSetPassword\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBchar *\fR\fIpassword\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiServiceSetEncryption\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBpapi_encryption_t\fR \fIencryption\fR); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiServiceSetAuthCB\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBint\fR (\fB*\fR\fIauthCB\fR)(\fBpapi_service_t\fR \fIs\fR, \fBvoid *\fR\fIapp_data\fR)); +.fi + +.LP +.nf +\fBpapi_status_t\fR \fBpapiServiceSetAppData\fR(\fBpapi_service_t\fR \fIhandle\fR, + \fBvoid *\fR\fIapp_data\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBpapiServiceGetServiceName\fR(\fBpapi_service_t\fR \fIhandle\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBpapiServiceGetUserName\fR(\fBpapi_service_t\fR \fIhandle\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBpapiServiceGetPassword\fR(\fBpapi_service_t\fR \fIhandle\fR); +.fi + +.LP +.nf +\fBpapi_encryption_t\fR \fBpapiServiceGetEncryption\fR(\fBpapi_service_t\fR \fIhandle\fR); +.fi + +.LP +.nf +\fBvoid *\fR\fBpapiServiceGetAppData\fR(\fBpapi_service_t\fR \fIhandle\fR); +.fi + +.LP +.nf +\fBpapi_attribute_t **\fR\fBpapiServiceGetAttributeList\fR(\fBpapi_service_t\fR \fIhandle\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBpapiServiceGetStatusMessage\fR(\fBpapi_service_t\fR \fIhandle\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIapp_data\fR\fR +.ad +.RS 16n +.rt +a set of additional data to be passed to the \fIauthCB\fR if/when it is called +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIauthCB\fR\fR +.ad +.RS 16n +.rt +a callback routine use to gather additional authentication information on +behalf of the print service +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIencryption\fR\fR +.ad +.RS 16n +.rt +whether or not encryption should be used for communication with the print +service, where applicable. If \fBPAPI_ENCRYPT_IF_REQUESTED\fR is specified, +encryption will be used if the print service requests it. If +\fBPAPI_ENCRYPT_NEVER\fR is specified, encryption will not be used while +communicating with the print service. If \fBPAPI_ENCRYPT_REQUIRED\fR or +\fBPAPI_ENCRYPT_ALWAYS\fR is specified, encryption will be required while +communicating with the print service +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIhandle\fR\fR +.ad +.RS 16n +.rt +a pointer to a handle to be used for all \fBlibpapi\fR operations. This handle +should be initialized to \fINULL\fR prior to creation +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpassword\fR\fR +.ad +.RS 16n +.rt +a plain text password to be used during any required user authentication with +the print service function set with \fBpapiServiceSetAuthCB()\fR. This provides +the callback function a means of interrogating the service context for user +information and setting a password. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIs\fR\fR +.ad +.RS 16n +.rt +the service context passed into the the authentication callback +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIservice_name\fR\fR +.ad +.RS 16n +.rt +the name of a print service to contact. This can be \fINULL\fR, a print +service name like "lpsched", a resolvable printer name, or a \fBprinter-uri\fR +like \fBipp://server/printers/queue\fR. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIsvc\fR\fR +.ad +.RS 16n +.rt +a handle (service context) used by subsequent PAPI calls to keep/pass +information across PAPI calls. It generally contains connection, state, and +authentication information. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIuser_name\fR\fR +.ad +.RS 16n +.rt +the name of the user to act on behalf of while contacting the print service. +If a value of \fINULL\fR is used, the user name associated with the current +processes UID will be used. Specifying a user name might require further +authentication with the print service. +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpapiServiceCreate()\fR function creates a service context for use in +subsequent calls to \fBlibpapi\fR functions. The context is returned in the +handle argument. This context must be destroyed using +\fBpapiServiceDestroy()\fR even if the \fBpapiServiceCreate()\fR call failed. +.sp +.LP +The \fBpapiServiceSet*()\fR functions modifies the requested value in the +service context passed in. It is recommended that these functions be avoided +in favor of supplying the information when the context is created. +.sp +.LP +The \fBpapiServiceGetStatusMessage()\fR function retrieves a detailed error +message associated with the service context. This message will apply to the +last failed operation. +.sp +.LP +The remaining \fBpapiServiceGet*()\fR functions return the requested +information associated with the service context. A value of \fINULL\fR +indicates that the requested value was not initialized or is unavailable. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpapiServiceCreate()\fR and the +\fBpapiServiceSet*()\fR functions return \fBPAPI_OK\fR. Otherwise, they return +an appropriate \fBpapi_status_t\fR indicating the type of failure. +.sp +.LP +Upon successful completion, the \fBpapiServiceGet*()\fR functions return a +pointer to the requested data. Otherwise, they return \fINULL\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fRCreate a PAPI service context. +.sp +.in +2 +.nf +/* + * program to create a PAPI service context. + */ +#include <stdio.h> +#include <papi.h> + +static int +authCB(papi_service_t svc, void *app_data) +{ + char prompt[BUFSIZ]; + char *user, *svc_name, *passphrase; + + /* get the name of the service we are contacting */ + if ((svc_name = papiServiceGetServiceName(svc)) == NULL) + return (-1); + + /* find out who we are supposed to be */ + if ((user = papiServiceGetUserName(svc)) == NULL) { + struct passwd *pw; + + if ((pw = getpwuid(getuid())) != NULL) + user = pw->pw_name; + else + user = "nobody"; + } + + /* build the prompt string */ + snprintf(prompt, sizeof (prompt), + gettext("passphrase for %s to access %s: "), user, + svc_name); + + /* ask for the passphrase */ + if ((passphrase = getpassphrase(prompt)) != NULL) + papiServiceSetPassword(svc, passphrase); + + return (0); +} + +/*ARGSUSED*/ +int +main(int ac, char *av[]) +{ + char buf[BUFSIZ]; + papi_status_t status; + papi_service_t *svc = NULL; + + status = papiServiceCreate(&svc, av[1], NULL, NULL, authCB, + PAPI_ENCRYPT_NEVER, NULL); + + if (status != PAPI_OK) { + /* do something */ + } else + printf("Failed(%s): %s: %s\en", av[1], papiStatusString(status), + papiStatusMessage(svc)); + + papiServiceDestroy(svc); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityVolatile +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpapi\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3papi/papiStatusString.3papi b/usr/src/man/man3papi/papiStatusString.3papi new file mode 100644 index 0000000000..a3f35b59fd --- /dev/null +++ b/usr/src/man/man3papi/papiStatusString.3papi @@ -0,0 +1,88 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" 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. +.\" 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. +.\" 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] +.TH papiStatusString 3PAPI "17 Jan 2007" "SunOS 5.11" "PAPI Library Functions" +.SH NAME +papiStatusString \- return the string equivalent of a papi_status_t +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lpapi\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <papi.h> + +\fBchar *\fR\fBpapiStatusString\fR(\fBpapi_status_t\fR \fIstatus\fR); +.fi + +.SH PARAMETERS +.sp +.ne 2 +.mk +.na +\fB\fIstatus\fR\fR +.ad +.RS 10n +.rt +a \fBpapi_status_t\fR returned from most \fBpapi*()\fR functions +.RE + +.SH DESCRIPTION +.sp +.LP +The \fBpapiStatusString()\fR function takes a \fIstatus\fR value and returns a +localized human-readable version of the supplied status. +.SH RETURN VALUES +.sp +.LP +The \fBpapiStatusString()\fR function always returns a text string. +.SH ERRORS +.sp +.LP +None. +.SH EXAMPLES +.LP +\fBExample 1 \fRPrint status. +.sp +.in +2 +.nf +#include <stdio.h> +#include <papi.h> + +/*ARGSUSED*/ +int +main(int ac, char *av[]) +{ + + printf("status: %s\en", papiStatusString(PAPI_OK)); + printf("status: %s\en", papiStatusString(PAPI_DEVICE_ERROR)); + printf("status: %s\en", papiStatusString(PAPI_DOCUMENT_ACCESS_ERROR)); + + exit(0); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityVolatile +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibpapi\fR(3LIB), \fBattributes\fR(5) |