From: Michael R Sweet Date: Thu, 12 Sep 2024 17:23:50 +0000 (-0400) Subject: Merge ipptool fixes and improvements, update man pages. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2dad30d9476b19279702aafcbb754fc613ab014a;p=thirdparty%2Fcups.git Merge ipptool fixes and improvements, update man pages. --- diff --git a/doc/help/man-ipptool.html b/doc/help/man-ipptool.html index 6dcc34b072..03503ed6e2 100644 --- a/doc/help/man-ipptool.html +++ b/doc/help/man-ipptool.html @@ -14,8 +14,8 @@ [ --help ] [ ---ippserver -filename +--ippfile +FILENAME ] [ --stop-after-include-error ] [ @@ -25,54 +25,57 @@ ] [ -6 ] [ +-c +] [ -C ] [ --E +-d +NAME=VALUE ] [ --I +-E ] [ --L +-f +FILENAME ] [ --P -filename.plist +-h ] [ --S +-i +SECONDS ] [ --T -seconds +-I ] [ --V -version +-j ] [ --X +-L ] [ --c +-n +REPEAT-COUNT ] [ --d -name=value +-P +FILENAME.plist ] [ --f -filename +-q ] [ --h +-R ] [ --i -seconds +-S ] [ --j +-t ] [ --n -repeat-count +-T +SECONDS ] [ --q +-v ] [ --t +-V +VERSION ] [ --v ] -printer-uri -testfile +-X +] +PRINTER-URI +TESTFILE [ ... -testfile +TESTFILE ]

Description

@@ -83,7 +86,7 @@ and tests and/or displays the results. Each named testfile defines one or more requests, including the expected response status, attributes, and values. -Output is either a plain text, formatted text, CSV, or XML report on the standard output, with a non-zero exit status indicating that one or more tests have failed. +Output is either a plain text, formatted text, CSV, JSON, or XML report on the standard output, with a non-zero exit status indicating that one or more tests have failed. The testfile format is described in @@ -97,10 +100,11 @@ format is described in

--help
Shows program help.

-

--ippserver filename
-Specifies that the test results should be written to the named -ippserver -attributes file. +

--ippfile FILENAME
+Specifies that the test results should be written to the named IPP file. +These files can be used with programs like +ippeveprinter(1). +

--stop-after-include-error
Tells @@ -123,63 +127,39 @@ must connect to the printer or server using IPv4. Specifies that ipptool must connect to the printer or server using IPv6. +

+

-c
+Specifies that CSV (comma-separated values) output is desired instead of the plain text output.

-C
Specifies that requests should be sent using the HTTP/1.1 "Transfer-Encoding: chunked" header, which is required for conformance by all versions of IPP. The default is to use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files.

-

-E
-Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header. -

-

-I
-Specifies that -ipptool -will continue past errors. -

-

-L
-Specifies that requests should be sent using the HTTP/1.0 "Content-Length:" header, which is required for conformance by all versions of IPP. -The default is to use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files. -

-

-P filename.plist -
-Specifies that the test results should be written to the named XML (Apple plist) file in addition to the regular test report (-t). -This option is incompatible with the -i (interval) and -n (repeat-count) options. -

-

-S
-Forces (dedicated) TLS encryption when connecting to the server. -

-

-T seconds -
-Specifies a timeout for IPP requests in seconds. -

-

-V version -
-Specifies the default IPP version to use: 1.0, 1.1, 2.0, 2.1, or 2.2. If not specified, version 1.1 is used. -

-

-X
-Specifies that XML (Apple plist) output is desired instead of the plain text report. -This option is incompatible with the -i (interval) and -n (repeat-count) options. -

-

-c
-Specifies that CSV (comma-separated values) output is desired instead of the plain text output. -

-

-d name=value +

-d NAME=VALUE
Defines the named variable.

-

-f filename +

-E
+Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header. +

+

-f FILENAME
Defines the default request filename for tests.

-h
Validate HTTP response headers.

-

-i seconds +

-i SECONDS
Specifies that the (last) testfile should be repeated at the specified interval. -This option is incompatible with the -X (XML plist output) option. +This option is incompatible with the --ippfile (IPP file output) and -P or -X (XML plist output) options. +

+

-I
+Specifies that +ipptool +will continue past errors.

-j
Specifies that @@ -189,22 +169,46 @@ will produce JSON output.

-l
Specifies that plain text output is desired.

-

-n repeat-count +

-L
+Specifies that requests should be sent using the HTTP/1.0 "Content-Length:" header, which is required for conformance by all versions of IPP. +The default is to use "Transfer-Encoding: chunked" for requests with attached files and "Content-Length:" for requests without attached files. +

+

-n REPEAT-COUNT
Specifies that the (last) testfile should be repeated the specified number of times. -This option is incompatible with the -X (XML plist output) option. +This option is incompatible with the --ippfile (IPP file output) and -P or -X (XML plist output) options. +

+

-P FILENAME.plist +
+Specifies that the test results should be written to the named XML (Apple plist) file in addition to the regular test report (-t). +This option is incompatible with the -i (interval) and -n (repeat-count) options.

-q
Be quiet and produce no output. +

+

-S
+Forces (dedicated) TLS encryption when connecting to the server.

-t
Specifies that CUPS test report output is desired instead of the plain text output. +

+

-T SECONDS +
+Specifies a timeout for IPP requests in SECONDS.

-v
Specifies that all request and response attributes should be output in CUPS test mode (-t). -This is the default for XML output. +This is the default for CSV, JSON, and XML output. +

+

-V VERSION +
+Specifies the default IPP version to use: 1.0, 1.1, 2.0, 2.1, or 2.2. If not specified, version 1.1 is used. +

+

-X
+Specifies that XML (Apple plist) output is desired instead of the plain text report. +This option is incompatible with the -i (interval) and -n (repeat-count) options.

Exit Status

The @@ -212,39 +216,66 @@ This is the default for XML output. program returns 0 if all tests were successful and 1 otherwise.

Files

-

The following standard files are available: +

The following standard test files are available: +

+ 
+    cancel-current-job.test           - Cancel the current job
+    create-job.test                   - Create a job and send a document
+    create-job-sheets.test            - "" with banner
+    create-job-timeout.test           - "" with timeout
+    create-printer-subscription.test  - Create a printer subscription
+    cups-create-local-printer.test    - Create a local print queue
+    fax-job.test                      - Fax a file (for fax queues)
+    get-completed-jobs.test           - Get a list of completed jobs
+    get-job-attributes.test           - Get attributes for a job
+    get-job-template-attributes.test  - Get job ticket attributes for a printer
+    get-jobs.test                     - Get a list of not-completed jobs
+    get-notifications.test            - Get notifications for a subscription
+    get-printer-attributes.test       - Get attributes for a printer
+    get-printer-attributes-suite.test - Test Get-Printer-Attributes conformance
+    get-printers.test                 - Get a list of printers
+    get-subscriptions.test            - Get a list of subscriptions
+    identify-printer.test             - Identify a printer
+    identify-printer-display.test     - Identify a printer via the display
+    ipp-1.1.test                      - Run IPP/1.1 conformance tests
+    ipp-2.0.test                      - Run IPP/2.0 conformance tests
+    ipp-2.1.test                      - Run IPP/2.1 conformance tests
+    ipp-2.2.test                      - Run IPP/2.2 conformance tests
+    print-job.test                    - Print a file
+    print-job-and-wait.test           - Print a file and wait for completion
+    print-job-deflate.test            - Print a file with deflate compression
+    print-job-gzip.test               - Print a file with gzip compression
+    print-job-hold.test               - Print a file and hold
+    print-job-letter.test             - Print a file on US Letter media
+    print-job-manual.test             - Print a file with manual feed
+    print-job-media-col.test          - Print a file using "media-col"
+    print-job-media-needed.test       - Print a file and test for "media-needed"
+    print-job-password.test           - Print a file with a password/PIN
+    print-job-raster.test             - Print a generated raster file
+    print-uri.test                    - Print a URI/URL
+    set-attrs-hold.test               - Test setting job-hold-until to hold a job
+    validate-job.test                 - Validate a job ticket
+
+

The following standard document files are available: 

-    color.jpg
-    create-printer-subscription.test
-    document-a4.pdf
-    document-a4.ps
-    document-letter.pdf
-    document-letter.ps
-    get-completed-jobs.test
-    get-jobs.test
-    get-notifications.test
-    get-printer-attributes.test
-    get-subscriptions.test
-    gray.jpg
-    ipp-1.1.test
-    ipp-2.0.test
-    ipp-2.1.test
-    ipp-2.2.test
-    ipp-everywhere.test
-    onepage-a4.pdf
-    onepage-a4.ps
-    onepage-letter.pdf
-    onepage-letter.ps
-    print-job.test
-    print-job-deflate.test
-    print-job-gzip.test
-    testfile.jpg
-    testfile.pcl
-    testfile.pdf
-    testfile.ps
-    testfile.txt
-    validate-job.test
+    color.jpg                         - A color photo of a flower
+    document-a4.pdf                   - A 4-page A4 PDF document
+    document-a4.ps                    - A 4-page A4 PostScript document
+    document-letter.pdf               - A 4-page US Letter PDF document
+    document-letter.ps                - A 4-page US Letter PostScript document
+    gray.jpg                          - A grayscale photo of an Alcatraz doorway
+    onepage-a4-300-black-1.pwg        - A one page A4 PWG Raster document
+    onepage-a4.pdf                    - A one page A4 PDF document
+    onepage-a4.ps                     - A one page A4 PostScript document
+    onepage-letter-300-black-1.pwg    - A one page US Letter PWG Raster document
+    onepage-letter.pdf                - A one page US Letter PDF document
+    onepage-letter.ps                 - A one page US Letter PostScript document
+    testfile.jpg                      - A color photo collage
+    testfile.pcl                      - A HP-PCL homage to "The Shining"
+    testfile.pdf                      - A historical CUPS PDF document
+    testfile.ps                       - A historical CUPS PostScript document
+    testfile.txt                      - A plain text homage to "The Shining"

Conforming To

The @@ -267,10 +298,10 @@ program is unique to CUPS and conforms to the Internet Printing Protocol up to v

ipptoolfile(5), IANA IPP Registry (https://www.iana.org/assignments/ipp-registrations), -PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp) -RFC 8011 (https://datatracker.ietf.org/doc/html/rfc8011), +PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp), +RFC 8011 (https://datatracker.ietf.org/doc/html/rfc8011)

Copyright

-

Copyright © 2020-2024 by OpenPrinting. +

Copyright © 2021-2024 by OpenPrinting. diff --git a/doc/help/man-ipptoolfile.html b/doc/help/man-ipptoolfile.html index 5caaf56b9a..94b6f983bf 100644 --- a/doc/help/man-ipptoolfile.html +++ b/doc/help/man-ipptoolfile.html @@ -172,7 +172,11 @@ Specifies the default IPP version number to use for the tests that follow.

ATTR out-of-band-tag attribute-name

-

ATTR tag attribute-name value(s)
+

ATTR tag attribute-name value[,...,value]
+

+

ATTR tag attribute-name "value"[,...,"value"]
+

+

ATTR tag attribute-name <hex-value>[,...,<hex-value>]
Adds an attribute to the test request. Out-of-band tags (admin-define, delete-attribute, no-value, not-settable, unknown, unsupported) have no value. Values for other tags are delimited by the comma (",") character - escape commas using the "\" character. @@ -193,7 +197,6 @@ Uses the specified compression on the document data following the attributes in

DELAY seconds[,repeat-seconds]
Specifies a delay in seconds before this test will be run. If two values are specified, the second value is used as the delay between repeated tests. -A default repeat interval of 5 seconds is used if this directive is not provided.

DISPLAY attribute-name
Specifies that value of the named attribute should be output as part of the @@ -213,6 +216,12 @@ Specifies that the response must/may include the named attribute and that all oc

FILE filename
Specifies a file to include at the end of the request. This is typically used when sending a test print file. +

+

GENERATE-FILE { parameters }
+Specifies that +ipptool +should generate PWG or Apple raster data for the printer. +See the "GENERATE-FILE PARAMETERS" section for information on the parameters you can specify.

GROUP tag
Specifies the group tag for subsequent attributes in the request. @@ -338,11 +347,48 @@ Specifies that the current test should be repeated when the EXPECT

SAME-COUNT-AS attribute-name
Requires the EXPECT attribute to have the same number of values as the specified parallel attribute. +

+

SAVE-CONTENT filespec
+

+

SAVE-ALL-CONTENT filespec
+Saves all "http" or "https" URI values to the specified location. +The filespec value is a filename or directory path and can contain the special strings "%basename%" to insert the base filename from the URI, "%ext%" to insert the extension from the URI, and "%index%" to insert the value number starting at 1. +

+

WITH-ALL-CONTENT available
+

+

WITH-CONTENT available
+Requires that all URI values be accessible. +A "http" or "https" URI must respond to a GET request while a "ipp" or "ipps" URI must respond to a HEAD request. +

+

WITH-ALL-CONTENT valid
+

+

WITH-CONTENT valid
+Requires that all "http" and "https" URI values be accessible and provide valid content. +Currently +ipptool +is able to validate CSS, HTML, ICC, IPP, JPEG, PDF, PNG, and Apple .strings files. +

+

WITH-ALL-CONTENT valid-icon
+

+

WITH-CONTENT valid-icon
+Requires that all "http" and "https" URI values be accessible and provide valid PNG images for icons - 48x48, 128x128, or 512x512 in size with transparency.

WITH-ALL-HOSTNAMES "literal string"

WITH-ALL-HOSTNAMES "/regular expression/"
Requires that all URI values contain a matching hostname. +

+

WITH-ALL-MIME-TYPES mime/type[,...,mime/type]
+

+

WITH-MIME-TYPES mime/type[,...,mime/type]
+Requires that all URI values provide one of the listed MIME media types. +For non-content tests, the target Printer must respond to HTTP HEAD requests with the MIME media type that would be returned by a GET or POST requests. +For "http" and "https" content tests, +ipptool +sends a HTTP GET request. +For "ipp" and "ipps" content tests, +ipptool +sends an IPP Get-Printer-Attributes request.

WITH-ALL-RESOURCES "literal string"

@@ -374,6 +420,10 @@ Requires that all values of the EXPECT attribute match the bool

WITH-ALL-VALUES "/regular expression/"
Requires that all values of the EXPECT attribute match the regular expression, which must conform to the POSIX regular expression syntax. Comparisons are case-sensitive. +

+

WITH-ALL-VALUES-FROM attribute-name
+Requires that all value(s) of the EXPECT attribute matches the value(s) in the specified attribute. +For example, "EXPECT-ALL media-col-database/media-source WITH-ALL-VALUES-FROM media-source-supported" requires that all the "media-source" values are listed as a value of the "media-source-supported" attribute.

WITH-DISTINCT-VALUES
Requires that all values of the EXPECT attribute are unique. @@ -675,6 +725,12 @@ Inserts a single "$" character.

$ENV[name]
Inserts the value of the named environment variable, or an empty string if the environment variable is not defined. +

+

$basename
+Inserts the base filename (without directory path) of the path provided to +ipptool(8) + +with the -f option.

$date-current
Inserts the current date and time using the ISO-8601 format ("yyyy-mm-ddThh:mm:ssZ"). @@ -737,14 +793,131 @@ if any.

$user
Inserts the current user's login name.

+

Generate-File Parameters

+

The +GENERATE-FILE +directive dynamically generates raster pages for the destination printer. +Each page consists of a black border and the text "TEST-PAGE ####" repeated in the interior in several shades of gray and colors. +The following parameters are supported: +

+

COLORSPACE auto
+

+

COLORSPACE bi-level
+

+

COLORSPACE color
+

+

COLORSPACE monochrome
+

+

COLORSPACE colorspace_bits
+Specifies the output color space and bit depth. +"auto" chooses an available combination with preference for full color, "bi-level" chooses a B&W (bitmap) color space, "color" chooses a full color combination, and "monochrome" chooses a grayscale combination. +Otherwise, the value must be one of the registered IPP "pwg-raster-document-type-supported" keywords. +NOTE: The "device N" color spaces are not current supported. +

+

FORMAT image/pwg-raster
+

+

FORMAT image/urf
+Specifies the raster format to use, either "image/pwg-raster" (PWG Raster) or "image/urf" (Apple Raster). +The default is "image/urf" if supported, "image/pwg-raster" otherwise. +

+

MEDIA default
+

+

MEDIA ready
+

+

MEDIA media-size-name
+Specifies the output media size. +"default" uses the printer's default media size while "ready" uses the first ready (loaded) media reported by the printer. +Other media size names must conform the PWG self-describing media size format. +

+

NUM-COPIES copies
+Specifies the number of copies to produce. +The default is 1 copy. +

+

NUM-PAGES pages
+Specifies the number of pages to produce. +The default is 1 page for single-sided output and 2 pages for double-sided output. +

+

ORIENTATION landscape
+

+

ORIENTATION portrait
+

+

ORIENTATION reverse-landscape
+

+

ORIENTATION reverse-portrait
+Specifies the orientation of the output. +The default is "portrait". +

+

RESOLUTION default
+

+

RESOLUTION max
+

+

RESOLUTION min
+

+

RESOLUTION resolutiondpcm
+

+

RESOLUTION horzontalxverticaldpcm
+

+

RESOLUTION resolutiondpi
+

+

RESOLUTION horizontalxverticaldpi
+Specifies the output resolution using the printer's supported resolutions or as specified in dots per inch or dots per centimeter. +"default" uses the median resolution of the printer and is the default, "min" uses the lowest resolution of the printer, and "max" uses the highest resolution of the printer. +

+

SIDES one-sided
+

+

SIDES two-sided-long-edge
+

+

SIDES two-sided-short-edge
+Specifies whether to print on one or both sides of the media. +The default is "two-sided-long-edge" for portrait output and "two-sided-short-edge" for landscape output when supported by the printer, otherwise "one-sided" is used. +

+

Examples

+

Query the "foo-default" and "foo-supported" Printer Description attributes and validate that all of its values are 'bar', 'baz', or 'none': +

+ 
{
+  NAME "Validate 'foo' Attribute"
+  OPERATION Get-Printer-Attributes
+  GROUP operation-attributes-tag
+  ATTR charset attributes-charset utf-8
+  ATTR language attributes-natural-language en
+  ATTR uri printer-uri $uri
+  ATTR keyword requested-attributes foo-default,foo-supported
+  EXPECT foo-default OF-TYPE keyword IN-GROUP printer-attributes-tag
+      COUNT 1 WITH-VALUE "/^(bar|baz|none)$$/"
+  EXPECT foo-supported OF-TYPE keyword IN-GROUP printer-attributes-tag
+      WITH-ALL-VALUES "/^(bar|baz|none)$$/"
+}
+
+

Query the "media-col-ready" Printer Status attribute and validate that the collection values contain "media-size" and "media-source" member attributes: +

+ 
{
+  NAME "Validate 'foo' Attribute"
+  OPERATION Get-Printer-Attributes
+  GROUP operation-attributes-tag
+  ATTR charset attributes-charset utf-8
+  ATTR language attributes-natural-language en
+  ATTR uri printer-uri $uri
+  ATTR keyword requested-attributes media-col-ready
+  EXPECT media-col-ready OF-TYPE collection IN-GROUP printer-attributes-tag
+  EXPECT-ALL media-col-ready/media-size OF-TYPE collection COUNT 1
+  EXPECT-ALL media-col-ready/media-size/x-dimension OF-TYPE integer(1:MAX) COUNT 1
+  EXPECT-ALL media-col-ready/media-size/y-dimension OF-TYPE integer(0:MAX) COUNT 1
+  EXPECT-ALL media-col-ready/media-source OF-TYPE keyword|name COUNT 1
+}
+

See Also

-

ipptool(1), +

ipptool(1) -IANA IPP Registry (https://www.iana.org/assignments/ipp-registrations), -PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp), -RFC 8011 (https://datatracker.ietf.org/doc/html/rfc8011) +

+

IANA IPP Registry (https://www.iana.org/assignments/ipp-registrations) +

+

PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp) +

+

PWG 5101.1-2023: PWG Media Standardized Names v2.1 (https://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn21-20230915-5101.1.pdf) +

+

RFC 8011 (https://datatracker.ietf.org/doc/html/rfc8011)

Copyright

-

Copyright © 2020-2024 by OpenPrinting. +

Copyright © 2021-2024 by OpenPrinting. diff --git a/man/ipptool.1 b/man/ipptool.1 index b0a751a253..e46ecbc8d4 100644 --- a/man/ipptool.1 +++ b/man/ipptool.1 @@ -1,13 +1,13 @@ .\" .\" ipptool man page. .\" -.\" Copyright © 2020-2024 by OpenPrinting. +.\" Copyright © 2021-2024 by OpenPrinting. .\" Copyright © 2010-2019 by Apple Inc. .\" .\" Licensed under Apache License v2.0. See the file "LICENSE" for more .\" information. .\" -.TH ipptool 1 "CUPS" "2021-10-20" "OpenPrinting" +.TH ipptool 1 "CUPS" "2024-09-12" "OpenPrinting" .SH NAME ipptool \- perform internet printing protocol requests .SH SYNOPSIS @@ -15,8 +15,8 @@ ipptool \- perform internet printing protocol requests [ .B \-\-help ] [ -.B \-\-ippserver -.I filename +.B \-\-ippfile +.I FILENAME ] [ .B \-\-stop\-after\-include\-error ] [ @@ -26,54 +26,57 @@ ipptool \- perform internet printing protocol requests ] [ .B \-6 ] [ +.B \-c +] [ .B \-C ] [ -.B \-E +.B \-d +.I NAME=VALUE ] [ -.B \-I +.B \-E ] [ -.B \-L +.B \-f +.I FILENAME ] [ -.B \-P -.I filename.plist +.B \-h ] [ -.B \-S +.B \-i +.I SECONDS ] [ -.B \-T -.I seconds +.B \-I ] [ -.B \-V -.I version +.B \-j ] [ -.B \-X +.B \-L ] [ -.B \-c +.B \-n +.I REPEAT-COUNT ] [ -.B \-d -.I name=value +.B \-P +.I FILENAME.plist ] [ -.B \-f -.I filename +.B \-q ] [ -.B \-h +.B \-R ] [ -.B \-i -.I seconds +.B \-S ] [ -.B \-j +.B \-t ] [ -.B \-n -.I repeat-count +.B \-T +.I SECONDS ] [ -.B \-q +.B \-v ] [ -.B \-t +.B \-V +.I VERSION ] [ -.B \-v ] -.I printer-uri -.I testfile +.B \-X +] +.I PRINTER-URI +.I TESTFILE [ ... -.I testfile +.I TESTFILE ] .SH DESCRIPTION .B ipptool @@ -83,7 +86,7 @@ and tests and/or displays the results. Each named .I testfile defines one or more requests, including the expected response status, attributes, and values. -Output is either a plain text, formatted text, CSV, or XML report on the standard output, with a non-zero exit status indicating that one or more tests have failed. +Output is either a plain text, formatted text, CSV, JSON, or XML report on the standard output, with a non-zero exit status indicating that one or more tests have failed. The .I testfile format is described in @@ -95,10 +98,10 @@ The following options are recognized by .B \-\-help Shows program help. .TP 5 -\fB\-\-ippserver \fIfilename\fR -Specifies that the test results should be written to the named -.B ippserver -attributes file. +\fB\-\-ippfile \fIFILENAME\fR +Specifies that the test results should be written to the named IPP file. +These files can be used with programs like +.BR ippeveprinter (1). .TP 5 .B \-\-stop-after-include-error Tells @@ -122,56 +125,35 @@ Specifies that .B ipptool must connect to the printer or server using IPv6. .TP 5 +.B \-c +Specifies that CSV (comma\-separated values) output is desired instead of the plain text output. +.TP 5 .B \-C Specifies that requests should be sent using the HTTP/1.1 "Transfer\-Encoding: chunked" header, which is required for conformance by all versions of IPP. The default is to use "Transfer\-Encoding: chunked" for requests with attached files and "Content\-Length:" for requests without attached files. .TP 5 +.BI \-d \ NAME=VALUE +Defines the named variable. +.TP 5 .B \-E Forces TLS encryption when connecting to the server using the HTTP "Upgrade" header. .TP 5 -.B \-I -Specifies that -.B ipptool -will continue past errors. -.TP 5 -.B \-L -Specifies that requests should be sent using the HTTP/1.0 "Content\-Length:" header, which is required for conformance by all versions of IPP. -The default is to use "Transfer\-Encoding: chunked" for requests with attached files and "Content\-Length:" for requests without attached files. -.TP 5 -.BI \-P \ filename.plist -Specifies that the test results should be written to the named XML (Apple plist) file in addition to the regular test report (\fB\-t\fR). -This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat\-count) options. -.TP 5 -.B \-S -Forces (dedicated) TLS encryption when connecting to the server. -.TP 5 -.BI \-T \ seconds -Specifies a timeout for IPP requests in seconds. -.TP 5 -.BI \-V \ version -Specifies the default IPP version to use: 1.0, 1.1, 2.0, 2.1, or 2.2. If not specified, version 1.1 is used. -.TP 5 -.B \-X -Specifies that XML (Apple plist) output is desired instead of the plain text report. -This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat\-count) options. -.TP 5 -.B \-c -Specifies that CSV (comma\-separated values) output is desired instead of the plain text output. -.TP 5 -.BI \-d \ name=value -Defines the named variable. -.TP 5 -.BI \-f \ filename +.BI \-f \ FILENAME Defines the default request filename for tests. .TP 5 .B \-h Validate HTTP response headers. .TP 5 -.BI \-i \ seconds +.BI \-i \ SECONDS Specifies that the (last) .I testfile should be repeated at the specified interval. -This option is incompatible with the \fB\-X\fR (XML plist output) option. +This option is incompatible with the \fB\-\-ippfile\fR (IPP file output) and \fI\-P\fR or \fB\-X\fR (XML plist output) options. +.TP 5 +.B \-I +Specifies that +.B ipptool +will continue past errors. .TP 5 .B \-j Specifies that @@ -181,59 +163,108 @@ will produce JSON output. .B \-l Specifies that plain text output is desired. .TP 5 -.BI \-n \ repeat\-count +.B \-L +Specifies that requests should be sent using the HTTP/1.0 "Content\-Length:" header, which is required for conformance by all versions of IPP. +The default is to use "Transfer\-Encoding: chunked" for requests with attached files and "Content\-Length:" for requests without attached files. +.TP 5 +.BI \-n \ REPEAT\-COUNT Specifies that the (last) .I testfile should be repeated the specified number of times. -This option is incompatible with the \fI\-X\fR (XML plist output) option. +This option is incompatible with the \fI\-\-ippfile\fR (IPP file output) and \fI\-P\fR or \fI\-X\fR (XML plist output) options. +.TP 5 +.BI \-P \ FILENAME.plist +Specifies that the test results should be written to the named XML (Apple plist) file in addition to the regular test report (\fB\-t\fR). +This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat-count) options. .TP 5 .B \-q Be quiet and produce no output. .TP 5 +.B \-S +Forces (dedicated) TLS encryption when connecting to the server. +.TP 5 .B \-t Specifies that CUPS test report output is desired instead of the plain text output. .TP 5 +.BI \-T \ SECONDS +Specifies a timeout for IPP requests in SECONDS. +.TP 5 .B \-v Specifies that all request and response attributes should be output in CUPS test mode (\fB\-t\fR). -This is the default for XML output. +This is the default for CSV, JSON, and XML output. +.TP 5 +.BI \-V \ VERSION +Specifies the default IPP version to use: 1.0, 1.1, 2.0, 2.1, or 2.2. If not specified, version 1.1 is used. +.TP 5 +.B \-X +Specifies that XML (Apple plist) output is desired instead of the plain text report. +This option is incompatible with the \fB\-i\fR (interval) and \fB\-n\fR (repeat\-count) options. .SH EXIT STATUS The .B ipptool program returns 0 if all tests were successful and 1 otherwise. .SH FILES -The following standard files are available: +The following standard test files are available: +.nf + + cancel\-current\-job.test - Cancel the current job + create\-job.test - Create a job and send a document + create\-job\-sheets.test - "" with banner + create\-job\-timeout.test - "" with timeout + create\-printer\-subscription.test - Create a printer subscription + cups\-create\-local\-printer.test - Create a local print queue + fax\-job.test - Fax a file (for fax queues) + get\-completed\-jobs.test - Get a list of completed jobs + get\-job\-attributes.test - Get attributes for a job + get\-job\-template\-attributes.test - Get job ticket attributes for a printer + get\-jobs.test - Get a list of not-completed jobs + get\-notifications.test - Get notifications for a subscription + get\-printer\-attributes.test - Get attributes for a printer + get\-printer\-attributes\-suite.test - Test Get-Printer-Attributes conformance + get\-printers.test - Get a list of printers + get\-subscriptions.test - Get a list of subscriptions + identify\-printer.test - Identify a printer + identify\-printer\-display.test - Identify a printer via the display + ipp\-1.1.test - Run IPP/1.1 conformance tests + ipp\-2.0.test - Run IPP/2.0 conformance tests + ipp\-2.1.test - Run IPP/2.1 conformance tests + ipp\-2.2.test - Run IPP/2.2 conformance tests + print\-job.test - Print a file + print\-job\-and\-wait.test - Print a file and wait for completion + print\-job\-deflate.test - Print a file with deflate compression + print\-job\-gzip.test - Print a file with gzip compression + print\-job\-hold.test - Print a file and hold + print\-job\-letter.test - Print a file on US Letter media + print\-job\-manual.test - Print a file with manual feed + print\-job\-media\-col.test - Print a file using "media-col" + print\-job\-media\-needed.test - Print a file and test for "media-needed" + print\-job\-password.test - Print a file with a password/PIN + print\-job\-raster.test - Print a generated raster file + print\-uri.test - Print a URI/URL + set\-attrs\-hold.test - Test setting job-hold-until to hold a job + validate\-job.test - Validate a job ticket +.fi +.PP +The following standard document files are available: .nf - color.jpg - create\-printer\-subscription.test - document\-a4.pdf - document\-a4.ps - document\-letter.pdf - document\-letter.ps - get\-completed\-jobs.test - get\-jobs.test - get\-notifications.test - get\-printer\-attributes.test - get\-subscriptions.test - gray.jpg - ipp\-1.1.test - ipp\-2.0.test - ipp\-2.1.test - ipp\-2.2.test - ipp\-everywhere.test - onepage\-a4.pdf - onepage\-a4.ps - onepage\-letter.pdf - onepage\-letter.ps - print\-job.test - print\-job\-deflate.test - print\-job\-gzip.test - testfile.jpg - testfile.pcl - testfile.pdf - testfile.ps - testfile.txt - validate\-job.test + color.jpg - A color photo of a flower + document\-a4.pdf - A 4-page A4 PDF document + document\-a4.ps - A 4-page A4 PostScript document + document\-letter.pdf - A 4-page US Letter PDF document + document\-letter.ps - A 4-page US Letter PostScript document + gray.jpg - A grayscale photo of an Alcatraz doorway + onepage\-a4\-300\-black\-1.pwg - A one page A4 PWG Raster document + onepage\-a4.pdf - A one page A4 PDF document + onepage\-a4.ps - A one page A4 PostScript document + onepage\-letter\-300\-black\-1.pwg - A one page US Letter PWG Raster document + onepage\-letter.pdf - A one page US Letter PDF document + onepage\-letter.ps - A one page US Letter PostScript document + testfile.jpg - A color photo collage + testfile.pcl - A HP-PCL homage to "The Shining" + testfile.pdf - A historical CUPS PDF document + testfile.ps - A historical CUPS PostScript document + testfile.txt - A plain text homage to "The Shining" .fi .SH CONFORMING TO The @@ -255,7 +286,7 @@ Send email notifications to "user@example.com" when "myprinter" changes: .SH SEE ALSO .BR ipptoolfile (5), IANA IPP Registry (https://www.iana.org/assignments/ipp\-registrations), -PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp) -RFC 8011 (https://datatracker.ietf.org/doc/html/rfc8011), +PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp), +RFC 8011 (https://datatracker.ietf.org/doc/html/rfc8011) .SH COPYRIGHT -Copyright \[co] 2020-2024 by OpenPrinting. +Copyright \[co] 2021-2024 by OpenPrinting. diff --git a/man/ipptoolfile.5 b/man/ipptoolfile.5 index 30ae527b5d..1bf9e01825 100644 --- a/man/ipptoolfile.5 +++ b/man/ipptoolfile.5 @@ -1,13 +1,13 @@ .\" .\" ipptoolfile man page. .\" -.\" Copyright © 2020-2024 by OpenPrinting. +.\" Copyright © 2021-2024 by OpenPrinting. .\" Copyright © 2010-2021 by Apple Inc. .\" .\" Licensed under Apache License v2.0. See the file "LICENSE" for more .\" information. .\" -.TH ipptoolfile 5 "CUPS" "2021-09-20" "OpenPrinting" +.TH ipptoolfile 5 "CUPS" "2024-09-12" "OpenPrinting" .SH NAME ipptoolfile \- ipptool file format .SH DESCRIPTION @@ -164,7 +164,11 @@ The following directives are understood within a \fItest\fR: .TP 5 \fBATTR \fIout-of-band-tag attribute-name\fR .TP 5 -\fBATTR \fItag attribute-name value(s)\fR +\fBATTR \fItag attribute-name value[,...,value]\fR +.TP 5 +\fBATTR \fItag attribute-name "value"[,...,"value"]\fR +.TP 5 +\fBATTR \fItag attribute-name [,...,]\fR Adds an attribute to the test request. Out-of-band tags (admin-define, delete-attribute, no-value, not-settable, unknown, unsupported) have no value. Values for other tags are delimited by the comma (",") character - escape commas using the "\\" character. @@ -185,7 +189,6 @@ Uses the specified compression on the document data following the attributes in \fBDELAY \fIseconds\fR[\fI,repeat-seconds\fR] Specifies a delay in seconds before this test will be run. If two values are specified, the second value is used as the delay between repeated tests. -A default repeat interval of 5 seconds is used if this directive is not provided. .TP 5 \fBDISPLAY \fIattribute-name\fR Specifies that value of the named attribute should be output as part of the @@ -206,6 +209,12 @@ Specifies that the response must/may include the named attribute and that all oc \fBFILE filename\fR Specifies a file to include at the end of the request. This is typically used when sending a test print file. .TP 5 +\fBGENERATE\-FILE { \fIparameters\fB }\fR +Specifies that +.B ipptool +should generate PWG or Apple raster data for the printer. +See the "GENERATE\-FILE PARAMETERS" section for information on the parameters you can specify. +.TP 5 \fBGROUP tag\fR Specifies the group tag for subsequent attributes in the request. .TP 5 @@ -327,11 +336,48 @@ Specifies that the current test should be repeated when the \fBEXPECT\fR conditi \fBSAME\-COUNT\-AS \fIattribute-name\fR Requires the \fBEXPECT\fR attribute to have the same number of values as the specified parallel attribute. .TP 5 +\fBSAVE\-CONTENT \fIfilespec\fR +.TP 5 +\fBSAVE\-ALL\-CONTENT \fIfilespec\fR +Saves all "http" or "https" URI values to the specified location. +The filespec value is a filename or directory path and can contain the special strings "%basename%" to insert the base filename from the URI, "%ext%" to insert the extension from the URI, and "%index%" to insert the value number starting at 1. +.TP 5 +\fBWITH\-ALL\-CONTENT available\fR +.TP 5 +\fBWITH\-CONTENT available\fR +Requires that all URI values be accessible. +A "http" or "https" URI must respond to a GET request while a "ipp" or "ipps" URI must respond to a HEAD request. +.TP 5 +\fBWITH\-ALL\-CONTENT valid\fR +.TP 5 +\fBWITH\-CONTENT valid\fR +Requires that all "http" and "https" URI values be accessible and provide valid content. +Currently +.B ipptool +is able to validate CSS, HTML, ICC, IPP, JPEG, PDF, PNG, and Apple .strings files. +.TP 5 +\fBWITH\-ALL\-CONTENT valid-icon\fR +.TP 5 +\fBWITH\-CONTENT valid-icon\fR +Requires that all "http" and "https" URI values be accessible and provide valid PNG images for icons - 48x48, 128x128, or 512x512 in size with transparency. +.TP 5 \fBWITH\-ALL\-HOSTNAMES "\fIliteral string\fB"\fR .TP 5 \fBWITH\-ALL\-HOSTNAMES "/\fIregular expression\fB/"\fR Requires that all URI values contain a matching hostname. .TP 5 +\fBWITH\-ALL\-MIME\-TYPES \fImime/type[,...,mime/type]\fR +.TP 5 +\fBWITH\-MIME\-TYPES \fImime/type[,...,mime/type]\fR +Requires that all URI values provide one of the listed MIME media types. +For non-content tests, the target Printer must respond to HTTP HEAD requests with the MIME media type that would be returned by a GET or POST requests. +For "http" and "https" content tests, +.B ipptool +sends a HTTP GET request. +For "ipp" and "ipps" content tests, +.B ipptool +sends an IPP Get-Printer-Attributes request. +.TP 5 \fBWITH\-ALL\-RESOURCES "\fIliteral string\fB"\fR .TP 5 \fBWITH\-ALL\-RESOURCES "/\fIregular expression\fB/"\fR @@ -339,7 +385,7 @@ Requires that all URI values contain a matching resource (including leading /). .TP 5 \fBWITH\-ALL\-SCHEMES "\fIliteral string\fB"\fR .TP 5 -\fBWITH\-ALL-SCHEMES "/\fIregular expression\fB/"\fR +\fBWITH\-ALL\-SCHEMES "/\fIregular expression\fB/"\fR Requires that all URI values contain a matching scheme. .TP 5 \fBWITH\-ALL\-VALUES "\fIliteral string\fB"\fR @@ -363,6 +409,10 @@ Requires that all values of the \fBEXPECT\fR attribute match the boolean value g Requires that all values of the \fBEXPECT\fR attribute match the regular expression, which must conform to the POSIX regular expression syntax. Comparisons are case-sensitive. .TP 5 +\fBWITH\-ALL\-VALUES\-FROM \fIattribute-name\fR +Requires that all value(s) of the \fBEXPECT\fR attribute matches the value(s) in the specified attribute. +For example, "EXPECT-ALL media\-col\-database/media\-source WITH\-ALL\-VALUES\-FROM media\-source\-supported" requires that all the "media\-source" values are listed as a value of the "media\-source\-supported" attribute. +.TP 5 \fBWITH\-DISTINCT\-VALUES\fR Requires that all values of the \fBEXPECT\fR attribute are unique. Comparisons are case-sensitive. @@ -660,6 +710,11 @@ Inserts a single "$" character. \fB$ENV[\fIname\fB]\fR Inserts the value of the named environment variable, or an empty string if the environment variable is not defined. .TP 5 +\fB$basename\fR +Inserts the base filename (without directory path) of the path provided to +.BR ipptool (8) +with the \fI-f\fR option. +.TP 5 \fB$date-current\fR Inserts the current date and time using the ISO-8601 format ("yyyy-mm-ddThh:mm:ssZ"). .TP 5 @@ -712,10 +767,126 @@ if any. .TP 5 \fB$user\fR Inserts the current user's login name. +.SH GENERATE\-FILE PARAMETERS +The +.B GENERATE\-FILE +directive dynamically generates raster pages for the destination printer. +Each page consists of a black border and the text "TEST-PAGE ####" repeated in the interior in several shades of gray and colors. +The following parameters are supported: +.TP 5 +\fBCOLORSPACE auto\fR +.TP 5 +\fBCOLORSPACE bi-level\fR +.TP 5 +\fBCOLORSPACE color\fR +.TP 5 +\fBCOLORSPACE monochrome\fR +.TP 5 +\fBCOLORSPACE \fIcolorspace_bits\fR +Specifies the output color space and bit depth. +"auto" chooses an available combination with preference for full color, "bi-level" chooses a B&W (bitmap) color space, "color" chooses a full color combination, and "monochrome" chooses a grayscale combination. +Otherwise, the value must be one of the registered IPP "pwg-raster-document-type-supported" keywords. +\fINOTE:\fR The "device N" color spaces are not current supported. +.TP 5 +\fBFORMAT image/pwg-raster\fR +.TP 5 +\fBFORMAT image/urf\fR +Specifies the raster format to use, either "image/pwg-raster" (PWG Raster) or "image/urf" (Apple Raster). +The default is "image/urf" if supported, "image/pwg-raster" otherwise. +.TP 5 +\fBMEDIA default\fR +.TP 5 +\fBMEDIA ready\fR +.TP 5 +\fBMEDIA \fImedia-size-name\fR +Specifies the output media size. +"default" uses the printer's default media size while "ready" uses the first ready (loaded) media reported by the printer. +Other media size names must conform the PWG self-describing media size format. +.TP 5 +\fBNUM\-COPIES \fIcopies\fR +Specifies the number of copies to produce. +The default is 1 copy. +.TP 5 +\fBNUM\-PAGES \fIpages\fR +Specifies the number of pages to produce. +The default is 1 page for single-sided output and 2 pages for double-sided output. +.TP 5 +\fBORIENTATION landscape\fR +.TP 5 +\fBORIENTATION portrait\fR +.TP 5 +\fBORIENTATION reverse-landscape\fR +.TP 5 +\fBORIENTATION reverse-portrait\fR +Specifies the orientation of the output. +The default is "portrait". +.TP 5 +\fBRESOLUTION default\fR +.TP 5 +\fBRESOLUTION max\fR +.TP 5 +\fBRESOLUTION min\fR +.TP 5 +\fBRESOLUTION \fIresolution\fBdpcm\fR +.TP 5 +\fBRESOLUTION \fIhorzontal\fBx\fIvertical\fBdpcm\fR +.TP 5 +\fBRESOLUTION \fIresolution\fBdpi\fR +.TP 5 +\fBRESOLUTION \fIhorizontal\fBx\fIvertical\fBdpi\fR +Specifies the output resolution using the printer's supported resolutions or as specified in dots per inch or dots per centimeter. +"default" uses the median resolution of the printer and is the default, "min" uses the lowest resolution of the printer, and "max" uses the highest resolution of the printer. +.TP 5 +\fB SIDES one-sided\fR +.TP 5 +\fB SIDES two-sided-long-edge\fR +.TP 5 +\fB SIDES two-sided-short-edge\fR +Specifies whether to print on one or both sides of the media. +The default is "two-sided-long-edge" for portrait output and "two-sided-short-edge" for landscape output when supported by the printer, otherwise "one-sided" is used. +.SH EXAMPLES +Query the "foo-default" and "foo-supported" Printer Description attributes and validate that all of its values are 'bar', 'baz', or 'none': +.nf +{ + NAME "Validate 'foo' Attribute" + OPERATION Get-Printer-Attributes + GROUP operation-attributes-tag + ATTR charset attributes-charset utf-8 + ATTR language attributes-natural-language en + ATTR uri printer-uri $uri + ATTR keyword requested-attributes foo-default,foo-supported + EXPECT foo-default OF-TYPE keyword IN-GROUP printer-attributes-tag + COUNT 1 WITH-VALUE "/^(bar|baz|none)$$/" + EXPECT foo-supported OF-TYPE keyword IN-GROUP printer-attributes-tag + WITH-ALL-VALUES "/^(bar|baz|none)$$/" +} +.fi +Query the "media-col-ready" Printer Status attribute and validate that the collection values contain "media-size" and "media-source" member attributes: +.nf +{ + NAME "Validate 'foo' Attribute" + OPERATION Get-Printer-Attributes + GROUP operation-attributes-tag + ATTR charset attributes-charset utf-8 + ATTR language attributes-natural-language en + ATTR uri printer-uri $uri + ATTR keyword requested-attributes media-col-ready + EXPECT media-col-ready OF-TYPE collection IN-GROUP printer-attributes-tag + EXPECT-ALL media-col-ready/media-size OF-TYPE collection COUNT 1 + EXPECT-ALL media-col-ready/media-size/x-dimension OF-TYPE integer(1:MAX) COUNT 1 + EXPECT-ALL media-col-ready/media-size/y-dimension OF-TYPE integer(0:MAX) COUNT 1 + EXPECT-ALL media-col-ready/media-source OF-TYPE keyword|name COUNT 1 +} +.fi .SH SEE ALSO -.BR ipptool (1), -IANA IPP Registry (https://www.iana.org/assignments/ipp-registrations), -PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp), +.BR ipptool (1) +.PP +IANA IPP Registry (https://www.iana.org/assignments/ipp-registrations) +.PP +PWG Internet Printing Protocol Workgroup (https://www.pwg.org/ipp) +.PP +PWG 5101.1-2023: PWG Media Standardized Names v2.1 (https://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn21-20230915-5101.1.pdf) +.PP RFC 8011 (https://datatracker.ietf.org/doc/html/rfc8011) .SH COPYRIGHT -Copyright \[co] 2020-2024 by OpenPrinting. +Copyright \[co] 2021-2024 by OpenPrinting. diff --git a/tools/ipptool.c b/tools/ipptool.c index 918f162ce0..932d6a3a37 100644 --- a/tools/ipptool.c +++ b/tools/ipptool.c @@ -6632,7 +6632,8 @@ with_content( char scheme[256], // Scheme userpass[256], // Username:password (not used) host[256], // Hostname - resource[256]; // Resource path + resource[256], // Resource path + *resptr; // Pointer into resource int port; // Port number http_encryption_t encryption; // Encryption mode http_uri_status_t uri_status; // URI decoding status @@ -6652,6 +6653,9 @@ with_content( continue; } + if ((resptr = strchr(resource, '#')) != NULL) + *resptr = '\0'; // Strip HTML target ("...#target") + if (strcmp(scheme, "http") && strcmp(scheme, "https") && strcmp(scheme, "ipp") && strcmp(scheme, "ipps")) { add_stringf(errors, "Unsupported URI scheme for '%s'.", uri); @@ -6721,7 +6725,7 @@ with_content( if (status != HTTP_STATUS_OK) { - add_stringf(errors, "Got unexpected status %d for HEAD request to '%s'.", (int)status, uri); + add_stringf(errors, "Got unexpected status %d for GET request to '%s'.", (int)status, uri); ret = false; goto get_done; } @@ -6765,14 +6769,38 @@ with_content( } else if (!_cups_strcasecmp(content_type, "image/jpeg") || !_cups_strcasecmp(content_type, "image/png")) { + // Validate image content if (!valid_image(filename, &width, &height, &depth)) { - add_stringf(errors, "Unable to load image '%s'.", uri); + add_stringf(errors, "Unable to open image '%s'.", uri); ret = false; goto get_done; } } - else if (!_cups_strcasecmp(content_type, "application/pdf") || !_cups_strcasecmp(content_type, "application/ipp") || !_cups_strcasecmp(content_type, "application/vnd.iccprofile") || !_cups_strcasecmp(content_type, "text/css") || !_cups_strcasecmp(content_type, "text/html") || !_cups_strcasecmp(content_type, "text/strings")) + else if (!_cups_strcasecmp(content_type, "application/ipp")) + { + ipp_t *ipp = ippNew(); // IPP message + + if ((fd = open(filename, O_RDONLY | O_BINARY)) < 0) + { + add_stringf(errors, "Unable to open '%s': %s", uri, strerror(errno)); + ippDelete(ipp); + ret = false; + goto get_done; + } + else if (ippReadFile(fd, ipp) != IPP_STATE_DATA) + { + add_stringf(errors, "Unable to read '%s': %s", uri, cupsGetErrorString()); + ippDelete(ipp); + close(fd); + ret = false; + goto get_done; + } + + ippDelete(ipp); + close(fd); + } + else if (!_cups_strcasecmp(content_type, "application/pdf") || !_cups_strcasecmp(content_type, "application/vnd.iccprofile") || !_cups_strcasecmp(content_type, "text/css") || !_cups_strcasecmp(content_type, "text/html") || !_cups_strncasecmp(content_type, "text/html;", 10) || !_cups_strcasecmp(content_type, "text/strings")) { // Just require these files to be non-empty for now, might add more checks in the future... if (fileinfo.st_size == 0) @@ -6784,7 +6812,7 @@ with_content( } else { - add_stringf(errors, "Got unexpected Content-Type '%s' for HEAD request to '%s'.", content_type, uri); + add_stringf(errors, "Got unexpected Content-Type '%s' for GET request to '%s'.", content_type, uri); ret = false; goto get_done; }