doc/index.html

   1 <html>
   2   <head>
   3     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   4     <link rel='stylesheet' type='text/css' href='style.css'>
   5     <title>ZS3 - Amazon S3 and CloudFront from Common Lisp</title>
   6     </head>
   7   <body>
   8
   9 <div id='content'>
  10  <h2>ZS3 - Amazon S3 and CloudFront from Common Lisp</h2>
  11
  12  <p>ZS3 is a Common Lisp library for working with
  13    Amazon's <a href="http://aws.amazon.com/s3/">Simple Storage
  14    Service</a> (S3)
  15    and <a href="http://aws.amazon.com/cloudfront/">CloudFront content
  16    delivery service</a>. It is available under a BSD-style license;
  17    see <a href='LICENSE'>LICENSE</a> for details. Development of ZS3
  18    is hosted <a href="https://github.com/xach/zs3/">on GitHub</a>.
  19
  20 The latest version is 1.2.11, released on June 22nd, 2016.
  21
  22  <p>Download shortcut: <a href='http://www.xach.com/lisp/zs3.tgz'>http://www.xach.com/lisp/zs3.tgz</a>
  23
  24  <h2>Contents</h2>
  25
  26  <ul>
  27    <li> <a href='#installation'>Installation</a>
  28    <li> <a href='#overview'>Overview</a>
  29    <li> <a href='#example'>Example Use</a>
  30    <li> <a href='#limitations'>Limitations</a>
  31    <li> <a href='#dictionary'>The ZS3 Dictionary</a>
  32      <ul>
  33        <li> <a href='#credentials'>Credentials</a>
  34        <li> <a href='#responses'>Responses</a>
  35        <li> <a href='#bucket-ops'>Operations on Buckets</a>
  36        <li> <a href='#querying-buckets'>Querying Buckets</a>
  37        <li> <a href='#object-ops'>Operations on Objects</a>
  38        <li> <a href='#access-control'>Access Control</a>
  39        <li> <a href='#access-logging'>Access Logging</a>
  40        <li> <a href='#misc'>Miscellaneous Operations</a>
  41        <li> <a href='#utility'>Utility Functions</a>
  42        <li> <a href='#cloudfront'>CloudFront</a>
  43      </ul>
  44    <li> <a href='#references'>References</a>
  45    <li> <a href='#acknowledgements'>Acknowledgements</a>
  46    <li> <a href='#feedback'>Feedback</a>
  47  </ul>
  48
  49  <a name='installation'><h2>Installation</h2></a>
  50
  51  <p>ZS3 depends on the following libraries:
  52
  53    <ul>
  54      <li> <a href="http://common-lisp.net/project/cxml/">Closure XML</a>
  55      <li> <a href="http://weitz.de/drakma/">Drakma</a> <b>1.0.0 or newer</b>
  56      <li> <a href="http://method-combination.net/lisp/ironclad/">Ironclad</a>
  57      <li> <a href="http://files.b9.com/cl-base64/">cl-base64</a>
  58      <li> <a href="http://puri.b9.com/">Puri</a>
  59    </ul>
  60
  61  <p>The easiest way to install ZS3 and all its required libraries is
  62  with <A href="http://www.quicklisp.org/">Quicklisp</a>. After
  63  Quicklisp is installed, the following will fetch and load ZS3:
  64
  65 <pre>
  66     (ql:quickload "zs3")
  67 </pre>
  68
  69  <p>For more information about incorporating ASDF-using libraries like
  70    ZS3 into your own projects,
  71    see <a href="http://xach.livejournal.com/278047.html">this short
  72    tutorial</a>.
  73
  74
  75 <a name='overview'><h2>Overview</h2></a>
  76
  77  <p>ZS3 provides an interface to two separate, but related, Amazon
  78  services: <a href="http://aws.amazon.com/s3/">S3</a>
  79  and <a href="http://aws.amazon.com/cloudfront/">CloudFront</a>
  80
  81  <p>Using Amazon S3 involves working with two kinds of resources:
  82  buckets and objects.
  83
  84  <p>Buckets are containers, and are used to organize and manage
  85    objects. Buckets are identified by their name, which must be unique
  86    across all of S3. A user may have up to 100 buckets in S3.
  87
  88  <p>Objects are stored within buckets. Objects consist of arbitrary
  89    binary data, from 1 byte to 5 gigabytes. They are identified by a
  90    key, which must be unique within a bucket. Objects can also have
  91    associated S3-specific metadata and HTTP metadata.
  92
  93  <p>For full documentation of the Amazon S3 system, see
  94    the <a href="http://aws.amazon.com/documentation/s3/">Amazon
  95    S3 Documentation</a>. ZS3 uses the REST
  96    interface for all its operations.
  97
  98  <p>Using Amazon CloudFront involves working with
  99    distributions. Distributions are objects that associate an S3
 100    bucket with primary cloudfront.net hostname and zero or more
 101    arbitrary CNAMEs. S3 objects requested through a CloudFront
 102    distribution are distributed to and cached in multiple locations
 103    throughout the world, reducing latency and improving throughput,
 104    compared to direct S3 requests.
 105
 106  <p>For full documentation of the Amazon CloudFront system, see the
 107    <a href="http://aws.amazon.com/documentation/cloudfront/">Amazon
 108    CloudFront Documentation</a>.
 109
 110  <p>For help with using ZS3, please see
 111  the <a href="http://groups.google.com/group/zs3-devel">zs3-devel</a>
 112  mailing list.
 113
 114 <a name='example'><h2>Example Use</h2></a>
 115
 116 <p>
 117 <pre class='code'>
 118   * <b>(asdf:oos 'asdf:load-op '#:zs3)</b>
 119   => <i>lots of stuff</i>
 120
 121   * <b>(defpackage #:demo (:use #:cl #:zs3))</b>
 122   => #&lt;PACKAGE "DEMO"&gt;
 123
 124   * <b>(in-package #:demo)</b>
 125   => #&lt;PACKAGE "DEMO"&gt;
 126
 127   * <b>(setf <a href='#*credentials*'>*credentials*</a> (<a href='#file-credentials'>file-credentials</a> "~/.aws"))</b>
 128   => #&lt;FILE-CREDENTIALS {100482AF91}>
 129
 130   * <b>(<a href='#bucket-exists-p'>bucket-exists-p</a> "zs3-demo")</b>
 131   => NIL
 132
 133   * <b>(<a href='#create-bucket'>create-bucket</a> "zs3-demo")</b>
 134   => #&lt;RESPONSE 200 "OK" {10040D3281}>
 135
 136   * <b>(<a href='#http-code''>http-code</a> *)</b>
 137   => 200
 138
 139   * <b>(<a href='#put-vector'>put-vector</a> (<a href='#octet-vector'>octet-vector</a> 8 6 7 5 3 0 9 ) "zs3-demo" "jenny")</b>
 140   => #&lt;RESPONSE 200 "OK" {10033EC2E1}>
 141
 142   * <b>(create-bucket "zs3 demo")</b>
 143   Error:
 144    InvalidBucketName: The specified bucket is not valid.
 145    For more information, see:
 146      <a href="http://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html">http://docs.aws.amazon.com/AmazonS3/latest/dev/BucketRestrictions.html</a>
 147   [Condition of type INVALID-BUCKET-NAME]
 148
 149   * <b>(<a href='#copy-object'>copy-object</a> :from-bucket "zs3-demo" :from-key "jenny" :to-key "j2")</b>
 150   => #&lt;RESPONSE 200 "OK" {10040E3EA1}>
 151
 152   * <b>(<a href='#get-vector'>get-vector</a> "zs3-demo" "j2")</b>
 153   => #(8 6 7 5 3 0 9),
 154      ((:X-AMZ-ID-2 . "Huwo...")
 155       (:X-AMZ-REQUEST-ID . "304...")
 156       (:DATE . "Sat, 27 Sep 2008 15:01:03 GMT")
 157       (:LAST-MODIFIED . "Sat, 27 Sep 2008 14:57:31 GMT")
 158       (:ETAG . "\"f9e71fe2c41a10c0a78218e98a025520\"")
 159       (:CONTENT-TYPE . "binary/octet-stream")
 160       (:CONTENT-LENGTH . "7")
 161       (:CONNECTION . "close")
 162       (:SERVER . "AmazonS3"))
 163
 164   * <b>(<a href='#put-string'>put-string</a> "N&auml;men" "zs3-demo" "bork")</b>
 165   => #&lt;RESPONSE 200 "OK" {10047A3791}>
 166
 167   * <b>(values (get-vector "zs3-demo" "bork"))</b>
 168   => #(78 195 164 109 101 110)
 169
 170   * <b>(values (<a href='#get-file'>get-file</a> "zs3-demo" "bork" "bork.txt"))</b>
 171   => #P"bork.txt"
 172
 173   * <b>(setf *distribution* (<a href='#create-distribution'>create-distribution</a> "zs3-demo" :cnames "cdn.wigflip.com")</b>
 174   => #&lt;DISTRIBUTION X2S94L4KLZK5G0 for "zs3-demo.s3.amazonaws.com" [InProgress]>
 175
 176   * <b>(progn (sleep 180) (<a href='#refresh'>refresh</a> *distribution*))</b>
 177   => #&lt;DISTRIBUTION X2S94L4KLZK5G0 for "zs3-demo.s3.amazonaws.com" [Deployed]>
 178
 179   * <b>(<a href='#domain-name'>domain-name</a> *distribution*)</b>
 180   => "x214g1hzpjm1zp.cloudfront.net"
 181
 182   * <b>(<a href='#cnames'>cnames</a> *distribution*)</b>
 183   => ("cdn.wigflip.com")
 184
 185   * <b>(put-string "Hello, world" "zs3-demo" "cloudfront" :public t)</b>
 186   #&lt;RESPONSE 200 "OK" {10042689F1}>
 187
 188   * <b>(drakma:http-request "http://x214g1hzpjm1zp.cloudfront.net/cloudfront")</b>
 189   "Hello, world"
 190   200
 191   ((:X-AMZ-ID-2 . "NMc3IY3NzHGGEvV/KlzPgZMyDfPVT+ITtHo47Alqg00MboTxSX2f5XJzVTErfuHr")
 192    (:X-AMZ-REQUEST-ID . "52B050DC18638A00")
 193    (:DATE . "Thu, 05 Mar 2009 16:24:25 GMT")
 194    (:LAST-MODIFIED . "Thu, 05 Mar 2009 16:24:10 GMT")
 195    (:ETAG . "\"bc6e6f16b8a077ef5fbc8d59d0b931b9\"")
 196    (:CONTENT-TYPE . "text/plain")
 197    (:CONTENT-LENGTH . "12")
 198    (:SERVER . "AmazonS3")
 199    (:X-CACHE . "Miss from cloudfront")
 200    (:VIA . "1.0 ad78cb56da368c171e069e4444b2cbf6.cloudfront.net:11180")
 201    (:CONNECTION . "close"))
 202   #&lt;PURI:URI http://x214g1hzpjm1zp.cloudfront.net/cloudfront>
 203   #&lt;FLEXI-STREAMS:FLEXI-IO-STREAM {1002CE0781}>
 204   T
 205   "OK"
 206
 207   * <b>(drakma:http-request "http://x214g1hzpjm1zp.cloudfront.net/cloudfront")</b>
 208   "Hello, world"
 209   200
 210   ((:X-AMZ-ID-2 . "NMc3IY3NzHGGEvV/KlzPgZMyDfPVT+ITtHo47Alqg00MboTxSX2f5XJzVTErfuHr")
 211    (:X-AMZ-REQUEST-ID . "52B050DC18638A00")
 212    (:DATE . "Thu, 05 Mar 2009 16:24:25 GMT")
 213    (:LAST-MODIFIED . "Thu, 05 Mar 2009 16:24:10 GMT")
 214    (:ETAG . "\"bc6e6f16b8a077ef5fbc8d59d0b931b9\"")
 215    (:CONTENT-TYPE . "text/plain")
 216    (:CONTENT-LENGTH . "12")
 217    (:SERVER . "AmazonS3")
 218    (:AGE . "311")
 219    (:X-CACHE . "Hit from cloudfront")
 220    (:VIA . "1.0 0d78cb56da368c171e069e4444b2cbf6.cloudfront.net:11180")
 221    (:CONNECTION . "close"))
 222   #&lt;PURI:URI http://x214g1hzpjm1zp.cloudfront.net/cloudfront>
 223   #&lt;FLEXI-STREAMS:FLEXI-IO-STREAM {100360A781}>
 224   T
 225   "OK"
 226
 227 </pre>
 228
 229
 230 <a name='limitations'><h2>Limitations</h2></a>
 231
 232 <p>ZS3 supports many of the features of Amazon's S3 REST
 233 interface. Some features are unsupported or incompletely supported:
 234
 235   <ul>
 236     <li> No direct support
 237     for <a href="http://docs.aws.amazon.com/AmazonDevPay/latest/DevPayDeveloperGuide/Welcome.html">Amazon
 238     DevPay</a>
 239
 240     <li> No support for checking the 100-Continue response to avoid
 241     unnecessary large requests; this will hopefully be fixed with a
 242     future <a href='http://weitz.de/drakma/'>Drakma</a> release
 243
 244     <li> If a character in a key is encoded with multiple bytes in
 245       UTF-8, a bad interaction
 246       between <a href="http://puri.b9.com/">PURI</a> and Amazon's web
 247       servers will trigger a validation error.
 248
 249   </ul>
 250
 251 <a name='dictionary'><h2>The ZS3 Dictionary</h2></a>
 252
 253 <p>The following sections document the symbols that are exported from
 254 ZS3.
 255
 256
 257  <a name='credentials'><h3>Credentials</h3></a>
 258
 259 <p>
 260
 261 <div class='item'>
 262   <div class='type'><a name='*credentials*'>[Special variable]</a></div>
 263   <div class='signature'>
 264     <code class='name'>*credentials*</code>
 265   </div>
 266
 267   <blockquote class='description'>
 268     <p><code>*CREDENTIALS*</code> is the source of the Amazon Access
 269     Key and Secret Key for authenticated requests. Any object that has
 270     methods for the <a href='#access-key'><tt>ACCESS-KEY</tt></a>
 271     and <a href='#secret-key'><tt>SECRET-KEY</tt></a> generic
 272     functions may be used.
 273
 274     <p>If <code>*CREDENTIALS*</code> is a cons, it is treated as a
 275       list, and the first element of the list is taken as the access
 276       key and the second element of the list is taken as the secret
 277       key.
 278
 279     <p>The default value of <code>*CREDENTIALS*</code> is NIL, which
 280       will signal an error. You must set <code>*CREDENTIALS*</code> to
 281       something that follows the credentials generic function protocol
 282       to use ZS3.
 283
 284     <p>All ZS3 functions that involve authenticated requests take an
 285     optional <code class='kw'>:CREDENTIALS</code> keyword
 286     parameter. This parameter is bound to <code>*CREDENTIALS*</code>
 287     for the duration of the function call.
 288
 289     <p>The following illustrates how to implement a credentials object
 290       that gets the access and secret key from external environment
 291       variables.
 292
 293 <pre class='code'>
 294   (defclass environment-credentials () ())
 295
 296   (defmethod access-key ((credentials environment-credentials))
 297     (declare (ignore credentials))
 298     (getenv "AWS_ACCESS_KEY"))
 299
 300   (defmethod secret-key ((credentials environment-credentials))
 301     (declare (ignore credentials))
 302     (getenv "AWS_SECRET_KEY"))
 303
 304   (setf *credentials* (make-instance 'environment-credentials))
 305 </pre>
 306   </blockquote>
 307 </div>
 308
 309
 310 <div class='item'>
 311   <div class='type'><a name='access-key'>[Generic function]</a></div>
 312   <div class='signature'>
 313     <code class='name'>access-key</code>
 314     <span class='args'>
 315       <var>credentials</var>
 316     </span>
 317     <span class='result'>=> <var>access-key-string</var></span>
 318   </div>
 319
 320   <blockquote class='description'>
 321     <p>Returns the access key for <var>credentials</var>.
 322   </blockquote>
 323 </div>
 324
 325
 326 <div class='item'>
 327   <div class='type'><a name='security-token'>[Function]</a></div>
 328   <div class='signature'>
 329     <code class='name'>security-token</code>
 330     <span class='args'>
 331       <var>credentials</var>
 332     </span>
 333     <span class='result'>=> <var>security-token-string</var></span>
 334   </div>
 335
 336   <blockquote class='description'>
 337     <p>Returns the security token string for <var>credentials</var>,
 338     or NIL if there is no associated security token.</p>
 339   </blockquote>
 340 </div>
 341
 342
 343 <div class='item'>
 344   <div class='type'><a name='secret-key'>[Generic function]</a></div>
 345   <div class='signature'>
 346     <code class='name'>secret-key</code>
 347     <span class='args'>
 348       <var>credentials</var>
 349     </span>
 350     <span class='result'>=> <var>secret-key-string</var></span>
 351   </div>
 352
 353   <blockquote class='description'>
 354     <p>Returns the secret key for <var>credentials</var>.
 355   </blockquote>
 356 </div>
 357
 358 <div class='item'>
 359   <div class='type'><a name='file-credentials'>[Function]</a></div>
 360   <div class='signature'>
 361     <code class='name'>file-credentials</code>
 362     <span class='args'>
 363       <var>pathname</var>
 364     </span>
 365     <span class='result'>=> <var>credentials</var></span>
 366   </div>
 367
 368   <blockquote class='description'>
 369     <p>Loads credentials on demand from <var>pathname</var>. The file
 370       named by <var>pathname</var> should be a text file with the
 371       access key on the first line and the secret key on the second
 372       line.
 373
 374     <p>It can be used like so:
 375
 376 <pre class='code'>
 377   (setf *credentials* (file-credentials "/etc/s3.conf"))
 378 </pre>
 379   </blockquote>
 380 </div>
 381
 382
 383
 384 <a name='responses'><h3>Responses</h3></a>
 385
 386 <p>
 387     Some operations return a response as an additional value. All
 388     response objects can be interrogated to obtain the HTTP code,
 389     headers and phrase.
 390 </p>
 391
 392 <p>
 393     The outcome of some requests &mdash; a very small proportion
 394     &mdash; will be an error <cite>internal</cite> to the AWS server. In these
 395     circumstances an exponential backoff policy operates; if this
 396     encounters too many failures then ZS3 signals an <tt>internal-error</tt>
 397     which can be interrogated to obtain the response object, and
 398     through that the HTTP response code and headers:
 399 </p>
 400
 401
 402 <pre class="code">
 403 * <b>e</b>
 404 #&lt;ZS3:INTERNAL-ERROR @ #x1000296bc92&gt;
 405 * <b>(setf r (zs3:request-error-response e))</b>
 406 #&lt;ZS3::AMAZON-ERROR "InternalError"&gt;
 407 * <b>(zs3:http-code r)</b>
 408 500
 409 * <b>(zs3:http-headers r)</b>
 410 ((:X-AMZ-REQUEST-ID . "3E20E3BAC24AB9AA")
 411  (:X-AMZ-ID-2 . "80sxu4PDKtx1BWLOcSrUVWD90mMMVaMx6y9c+sz5VBGa2eAES2YlNaefn5kqRsfvrbaF+7QGNXA=")
 412  (:CONTENT-TYPE . "application/xml")
 413  (:TRANSFER-ENCODING . "chunked")
 414  (:DATE . "Fri, 30 Sep 2016 10:10:11 GMT")
 415  (:CONNECTION . "close")
 416  (:SERVER . "AmazonS3"))
 417 * <b>(zs3:http-phrase r)</b>
 418 "Internal Server Error"
 419 *</pre>
 420
 421 <div class='item'>
 422     <div class='type'><a name='*backoff*'>[Special variable]</a></div>
 423     <div class='signature'>
 424         <code class='name'>*backoff*</code>
 425     </div>
 426
 427     <blockquote class='description'>
 428         <p>
 429         Used as the default value of <code>:backoff</code> when
 430         submitting a request. The value should be a cons of two
 431         numbers: how many times to try before giving up, and how long
 432         to wait (in ms) before trying for the second time. Each
 433         subsequent attempt will double that time.
 434         </p>
 435
 436         <p>
 437         The default value is <code>(3 . 100)</code>.
 438         </p>
 439
 440         <p>
 441         If a requst fails more times than permitted by
 442         <code>*backoff*</code>, an error will be signalled. It is the
 443         application's responsibility to handle this error.</p>
 444     </blockquote>
 445 </div>
 446
 447
 448 <div class='item'>
 449     <div class='type'><a name='request-error-response'>[Function]</a></div>
 450     <div class='signature'>
 451         <code class='name'>request-error-response</code>
 452         <span class='args'>
 453             <var>request-error</var>
 454         </span>
 455         <span class='result'>=> <var>response</var></span>
 456     </div>
 457
 458     <blockquote class='description'>
 459         <p>Returns the <code>response</code> object associated with a request-error.
 460     </blockquote>
 461 </div>
 462
 463
 464 <div class='item'>
 465     <div class='type'><a name='http-code'>[Function]</a></div>
 466     <div class='signature'>
 467         <code class='name'>http-code</code>
 468         <span class='args'>
 469             <var>response</var>
 470         </span>
 471         <span class='result'>=> <var>code</var></span>
 472     </div>
 473
 474     <blockquote class='description'>
 475         <p>Returns the HTTP code associated with a <code>response</code> object.
 476     </blockquote>
 477 </div>
 478
 479
 480 <div class='item'>
 481     <div class='type'><a name='http-headers'>[Function]</a></div>
 482     <div class='signature'>
 483         <code class='name'>http-headers</code>
 484         <span class='args'>
 485             <var>response</var>
 486         </span>
 487         <span class='result'>=> <var>headers</var></span>
 488     </div>
 489
 490     <blockquote class='description'>
 491         <p>Returns the HTTP headers associated with a <code>response</code> object.
 492     </blockquote>
 493 </div>
 494
 495
 496 <div class='item'>
 497     <div class='type'><a name='http-phrase'>[Function]</a></div>
 498     <div class='signature'>
 499         <code class='name'>http-phrase</code>
 500         <span class='args'>
 501             <var>response</var>
 502         </span>
 503         <span class='result'>=> <var>phrase</var></span>
 504     </div>
 505
 506     <blockquote class='description'>
 507         <p>Returns the HTTP phrase associated with a <code>response</code> object.
 508     </blockquote>
 509 </div>
 510
 511
 512 <a name='bucket-ops'><h3>Operations on Buckets</h3></a>
 513
 514  <p>With ZS3, you can put, get, copy, and delete buckets. You can also
 515  get information about the bucket.
 516
 517 <div class='item'>
 518   <div class='type'><a name='all-buckets'>[Function]</a></div>
 519   <div class='signature'>
 520     <code class='name'>all-buckets</code>
 521     <span class='args'>
 522       <code class='llkw'>&amp;key</code> <var>credentials</var> <var>backoff</var>
 523     </span>
 524     <span class='result'>=> <var>bucket-vector</var></span>
 525   </div>
 526
 527   <blockquote class='description'>
 528     <p>Returns a vector of all bucket objects. Bucket object
 529     attributes are accessible via <a href='#name'><tt>NAME</tt></a>
 530     and <a href='#creation-date'><tt>CREATION-DATE</tt></a>.
 531   </blockquote>
 532 </div>
 533
 534 <div class='item'>
 535   <div class='type'><a name='creation-date'>[Function]</a></div>
 536   <div class='signature'>
 537     <code class='name'>creation-date</code>
 538     <span class='args'>
 539       <var>bucket-object</var>
 540     </span>
 541     <span class='result'>=> <var>creation-universal-time</var></span>
 542   </div>
 543
 544   <blockquote class='description'>
 545     <p>Returns the creation date of <var>bucket-object</var>, which
 546       must be a bucket object, as a universal time.
 547   </blockquote>
 548 </div>
 549
 550
 551 <div class='item'>
 552   <div class='type'><a name='name'>[Function]</a></div>
 553   <div class='signature'>
 554     <code class='name'>name</code>
 555     <span class='args'>
 556       <var>object</var>
 557     </span>
 558     <span class='result'>=> <var>name-string</var></span>
 559   </div>
 560
 561   <blockquote class='description'>
 562     <p>Returns the string name of <var>object</var>, which must be a
 563       key object or bucket object.
 564   </blockquote>
 565 </div>
 566
 567
 568 <div class='item'>
 569   <div class='type'><a name='all-keys'>[Function]</a></div>
 570   <div class='signature'>
 571     <code class='name'>all-keys</code>
 572     <span class='args'>
 573       <var>bucket</var>
 574       <code class='llkw'>&amp;key</code>
 575       <var>prefix</var>
 576       <var>credentials</var>
 577       <var>backoff</var>
 578     </span>
 579     <span class='result'>=> <var>key-vector</var></span>
 580   </div>
 581
 582   <blockquote class='description'>
 583     <p>Returns a vector of all key objects in <var>bucket</var> with names
 584     that start with the string <var>prefix</var>. If no prefix is
 585     specified, returns all keys. Keys in the vector are in
 586     alphabetical order by name. Key
 587     object attributes are accessible via
 588       <a href='#name'><tt>NAME</tt></a>,
 589       <a href='#size'><tt>SIZE</tt></a>,
 590       <a href='#etag'><tt>ETAG</tt></a>,
 591       <a href='#last-modified'><tt>LAST-MODIFIED</tt></a>,
 592       <a href='#owner'><tt>OWNER</tt>, and
 593       <a href='#storage-class'><tt>STORAGE-CLASS</tt></a></a>.
 594
 595     <p>This function is built
 596       on <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> and may
 597       involve multiple requests if a bucket has more than 1000 keys.
 598   </blockquote>
 599 </div>
 600
 601
 602 <div class='item'>
 603   <div class='type'><a name='bucket-exists-p'>[Function]</a></div>
 604   <div class='signature'>
 605     <code class='name'>bucket-exists-p</code>
 606     <span class='args'>
 607       <var>bucket</var>
 608       <code class='llkw'>&amp;key</code>
 609       <var>credentials</var>
 610       <var>backoff</var>
 611     </span>
 612     <span class='result'>=> <var>boolean</var></span>
 613   </div>
 614
 615   <blockquote class='description'>
 616     <p>Returns <i>true</i> if <var>bucket</var> exists.
 617   </blockquote>
 618 </div>
 619
 620
 621 <div class='item'>
 622   <div class='type'><a name='create-bucket'>[Function]</a></div>
 623   <div class='signature'>
 624     <code class='name'>create-bucket</code>
 625     <span class='args'>
 626       <var>name</var>
 627       <code class='llkw'>&amp;key</code>
 628       <var>access-policy</var>
 629       <var>public</var>
 630       <var>location</var>
 631       <var>credentials</var>
 632       <var>backoff</var>
 633     </span>
 634     <span class='result'>=> <var>response</var></span>
 635   </div>
 636
 637   <blockquote class='description'>
 638     <p>Creates a bucket named <var>name</var>.
 639
 640     <p>If provided, <var>access-policy</var> should be one of the
 641     following:
 642
 643       <ul>
 644         <li> <code class='kw'>:PRIVATE</code> - bucket owner is
 645           granted <code class='kw'>:FULL-CONTROL</code>; this is the
 646           default behavior if no access policy is provided
 647         <li> <code class='kw'>:PUBLIC-READ</code> - all users,
 648           regardless of authentication, can query the bucket's contents
 649         <li> <code class='kw'>:PUBLIC-READ-WRITE</code> - all users,
 650           regardless of authentication, can query the bucket's
 651           contents and create new objects in the bucket
 652         <li> <code class='kw'>:AUTHENTICATED-READ</code> -
 653           authenticated Amazon AWS users can query the bucket
 654       </ul>
 655
 656     <p>For more information about access policies,
 657     see <a href='http://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl'>Canned ACL</a>
 658     in the Amazon S3 developer documentation.
 659
 660     <p>If <var>public</var> is <i>true</i>, it has the same effect as
 661       providing an <var>access-policy</var>
 662       of <code class='kw'>:PUBLIC-READ</code>. An error is signaled if
 663       both <var>public</var> and
 664       <var>access-policy</var> are provided.
 665
 666     <p>If <var>location</var> is specified, the bucket will be created
 667       in a region matching the given location constraint. If no
 668       location is specified, the bucket is created in the US. Valid
 669       locations change over time, but currently include "EU",
 670       "us-west-1", "us-west-2", "eu-west-1", "eu-central-1",
 671       "ap-southeast-1", "ap-southeast-2", "ap-northeast-1", and
 672       "sa-east-1".
 673       See <a href="http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region">Regions
 674       and Endpoints</a> in the Amazon S3 developer documentation for
 675       the current information about location constraints.
 676   </blockquote>
 677 </div>
 678
 679
 680 <div class='item'>
 681   <div class='type'><a name='delete-bucket'>[Function]</a></div>
 682   <div class='signature'>
 683     <code class='name'>delete-bucket</code>
 684     <span class='args'>
 685       <var>bucket</var> <code class='llkw'>&amp;key</code>
 686       <var>credentials</var>
 687       <var>backoff</var>
 688     </span>
 689     <span class='result'>=> <var>response</var></span>
 690   </div>
 691
 692   <blockquote class='description'>
 693     <p>Deletes <var>bucket</var>. Signals a BUCKET-NOT-EMPTY error if
 694 the bucket is not empty, or a NO-SUCH-BUCKET error if there is no
 695 bucket with the given name.
 696
 697   </blockquote>
 698 </div>
 699
 700
 701 <div class='item'>
 702   <div class='type'><a name='bucket-location'>[Function]</a></div>
 703   <div class='signature'>
 704     <code class='name'>bucket-location</code>
 705     <span class='args'>
 706       <var>bucket</var> <code class='llkw'>&amp;key</code>
 707       <var>credentials</var>
 708       <var>backoff</var>
 709     </span>
 710     <span class='result'>=> <var>location</var></span>
 711   </div>
 712
 713   <blockquote class='description'>
 714     <p>Returns the location specified when creating a bucket, or NIL if no
 715       location was specified.
 716   </blockquote>
 717 </div>
 718
 719 <div class='item'>
 720   <div class='type'><a name='bucket-lifecycle'>[Function]</a></div>
 721   <div class='signature'>
 722     <code class='name'>bucket-lifecycle</code>
 723     <span class='args'>
 724       <var>bucket</var>
 725     </span>
 726     <span class='result'>=> <var>rules-list</var></span>
 727   </div>
 728
 729   <blockquote class='description'>
 730     <p>Returns a list of lifecycle rules
 731     for <var>bucket</var>. Signals a NO-SUCH-LIFECYCLE-CONFIGURATION
 732     error if the bucket has no lifecycle rules configured.
 733
 734     <p>Bucket lifecycle rules are used to control the automatic
 735       deletion of objects in a bucket. For more information about
 736       bucket lifecycle configuration,
 737       see <a href="http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectExpiration.html">Object
 738       Expiration</a> in the Amazon S3 developer documentation.
 739   </blockquote>
 740 </div>
 741
 742 <div class='item'>
 743   <div class='type'><a name='setf-bucket-lifecycle'>[Function]</a></div>
 744   <div class='signature'>
 745     <code class='name'>(setf bucket-lifecycle)</code>
 746     <span class='args'>
 747       <var>rules</var> <var>bucket</var>
 748     </span>
 749     <span class='result'>=> <var>rules</var>, <var>response</var></span>
 750   </div>
 751
 752   <blockquote class='description'>
 753     <p>Sets the lifecycle configuration of <var>bucket</var> to the
 754     designator for a list of bucket lifecycle rules <var>rules</var>.
 755
 756     <p>To create a
 757     bucket lifecycle rule,
 758     use <a href='#lifecycle-rule'><tt>LIFECYCLE-RULE</tt></a>. For
 759     example, to automatically delete objects with keys matching a
 760     "logs/" prefix after 30 days:
 761
 762 <pre class='code'>
 763 (setf (bucket-lifecycle "my-bucket") (lifecycle-rule :prefix "logs/" :days 30))
 764 </pre>
 765
 766     <p>To delete a bucket's lifecycle configuration, use an empty list
 767     of rules, e.g.
 768
 769 <pre class='code'>
 770 (setf (bucket-lifecycle "my-bucket") nil)
 771 </pre>
 772
 773   </blockquote>
 774 </div>
 775
 776 <div class='item'>
 777   <div class='type'><a name='lifecycle-rule'>[Function]</a></div>
 778   <div class='signature'>
 779     <code class='name'>lifecycle-rule</code>
 780     <span class='args'>
 781       <code class='llkw'>&amp;key</code>
 782       <var>action</var>
 783       <var>prefix</var>
 784       <var>days</var>
 785       <var>date</var>
 786     </span>
 787     <span class='result'>=> <var>rule</var></span>
 788   </div>
 789
 790   <blockquote class='description'>
 791     <p>Creates a rule object suitable for passing
 792       to <a href='#setf-bucket-lifecycle'><tt>(SETF
 793           BUCKET-LIFECYCLE)</tt></a>.
 794
 795     <p><var>action</var> should be either <tt>:expire</tt> (the
 796     default) or <tt>:transition</tt>. For <tt>:expire</tt>, matching
 797     objects are deleted. For <tt>:transition</tt>, matching objects
 798     are transitioned to the GLACIER storage class. For more
 799     information about S3-to-Glacier object transition,
 800     see <a href="http://docs.aws.amazon.com/AmazonS3/latest/dev/object-archival.html">Object
 801     Archival (Transition Objects to the Glacier Storage Class)</a> in
 802     the Amazon S3 Developer's Guide.
 803
 804     <p><var>prefix</var> is a string; all objects in a bucket with
 805         keys matching the prefix will be affected by the rule.
 806
 807     <p><var>days</var> is the number of days after which an object
 808     will be affected.
 809
 810     <p><var>date</var> is the date after which objects will be affected.
 811
 812     <p>Only one of <var>days</var> or <var>date</var> may be provided.
 813   </blockquote>
 814 </div>
 815
 816 <div class='item'>
 817   <div class='type'><a name='restore-object'>[Function]</a></div>
 818   <div class='signature'>
 819     <code class='name'>restore-object</code>
 820     <span class='args'>
 821       <var>bucket</var>
 822       <var>key</var>
 823       <code class='llkw'>&amp;body</code>
 824       <var>days</var>
 825       <var>credentials</var>
 826       <var>backoff</var>
 827     </span>
 828     <span class='result'>=> <var>response</var></span>
 829   </div>
 830
 831   <blockquote class='description'>
 832     <p>Initiates a restoration operation on the object identified
 833       by <var>bucket</var> and <var>key</var>.  A restoration
 834       operation can take several hours to complete. The restored
 835       object is temporarily stored with the reduced redundancy storage
 836       class. The status of the operation may monitored
 837       via <a href='#object-restoration-status'><tt>OBJECT-RESTORATION-STATUS</tt></a>.
 838
 839     <p><var>days</var> is the number of days for which the restored
 840       object should be avilable for normal retrieval before
 841       transitioning back to archival storage.
 842
 843     <p>Object restoration operation is only applicable to objects that
 844       have been transitioned to Glacier storage by the containing
 845       bucket's lifecycle configuration.
 846
 847     <p>For more information,
 848     see <a href="http://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOSTrestore.html">POST
 849     Object restore</a> in the S3 documentation.
 850   </blockquote>
 851 </div>
 852
 853 <div class='item'>
 854   <div class='type'><a name='object-restoration-status'>[Function]</a></div>
 855   <div class='signature'>
 856     <code class='name'>object-restoration-status</code>
 857     <span class='args'>
 858       <var>bucket</var>
 859       <var>key</var>
 860       <code class='llkw'>&amp;key</code>
 861       <var>credentials</var>
 862       <var>backoff</var>
 863     </span>
 864     <span class='result'>=> <var>status-string</var></span>
 865   </div>
 866
 867   <blockquote class='description'>
 868     <p>Returns a string describing the status of restoring the object
 869     identified by <var>bucket</var> and <var>key</var>. If no
 870     restoration is in progress, or the operation is not applicable,
 871     returns NIL.
 872   </blockquote>
 873 </div>
 874
 875
 876
 877 <a name='querying-buckets'><h3>Querying Buckets</h3></a>
 878
 879 <p>S3 has a flexible interface for querying a bucket for information
 880   about its contents. ZS3 supports this interface via
 881   <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a>,
 882    <a href='#continue-bucket-query'><tt>CONTINUE-BUCKET-QUERY</tt></a>,
 883    and related functions.
 884
 885 <div class='item'>
 886   <div class='type'><a name='query-bucket'>[Function]</a></div>
 887   <div class='signature'>
 888     <code class='name'>query-bucket</code>
 889     <span class='args'>
 890       <var>bucket</var>
 891       <code class='llkw'>&amp;key</code>
 892       <var>prefix</var>
 893       <var>marker</var>
 894       <var>max-keys</var>
 895       <var>delimiter</var>
 896       <var>credentials</var>
 897       <var>backoff</var>
 898     </span>
 899     <span class='result'>=> <var>response</var></span>
 900   </div>
 901
 902   <blockquote class='description'>
 903     <p>Query <var>bucket</var> for key information. Returns a response
 904     object that has the result of the query. Response attributes are
 905     accessible via
 906       <a href='#bucket-name'><tt>BUCKET-NAME</tt></a>,
 907       <a href='#prefix'><tt>PREFIX</tt></a>,
 908       <a href='#marker'><tt>MARKER</tt></a>,
 909       <a href='#delimiter'><tt>DELIMITER</tt></a>,
 910       <a href='#truncatedp'><tt>TRUNCATEDP</tt></a>,
 911       <a href='#keys'><tt>KEYS</tt></a>, and
 912       <a href='#common-prefixes'><tt>COMMON-PREFIXES</tt></a>.
 913
 914     <p>Amazon might return fewer key objects than actually match the
 915       query parameters, based on <var>max-keys</var> or the result
 916       limit of 1000 key objects. In that
 917       case, <a href='#truncatedp'><tt>TRUNCATEDP</tt></a>
 918       for <var>response</var> is <i>true</i>, and
 919       <a href='#continue-bucket-query'><tt>CONTINUE-BUCKET-QUERY</tt></a>
 920       can be used with <var>response</var> be used to get successive
 921       responses for the query parameters.
 922
 923     <p>When <var>prefix</var> is supplied, only key objects with names
 924       that start with <var>prefix</var> will be returned
 925       in <var>response</var>.
 926
 927     <p>When <var>marker</var> is supplied, only key objects with names
 928       occurring lexically after <var>marker</var> will be returned in
 929       <var>response</var>.
 930
 931     <p>When <var>max-keys</var> is supplied, it places an inclusive
 932       upper limit on the number of key objects returned
 933       in <var>response</var>. Note that Amazon currently limits
 934       responses to at most 1000 key objects even
 935       if <var>max-keys</var> is greater than 1000.
 936
 937     <p>When <var>delimiter</var> is supplied, key objects that have
 938       the delimiter string after <var>prefix</var> in their names are
 939       not returned in the <a href='#keys'><tt>KEYS</tt></a> attribute
 940       of the response, but are instead accumulated into the
 941       <a href='#common-prefixes'><tt>COMMON-PREFIXES</tt></a>
 942       attribute of the response. For example:
 943 <pre class='code'>
 944   * <b>(all-keys "zs3-demo")</b>
 945   => #(#&lt;KEY "a" 4>
 946        #&lt;KEY "b/1" 4>
 947        #&lt;KEY "b/2" 4>
 948        #&lt;KEY "b/3" 4>
 949        #&lt;KEY "c/10" 4>
 950        #&lt;KEY "c/20" 4>
 951        #&lt;KEY "c/30" 4>)
 952
 953   * <b>(setf *response* (query-bucket "zs3-demo" :delimiter "/"))</b>
 954   => #&lt;BUCKET-LISTING "zs3-demo">
 955
 956   * <b>(values (keys *response*) (common-prefixes *response*))</b>
 957   => #(#&lt;KEY "a" 4>),
 958      #("b/"
 959        "c/")
 960
 961   * <b>(setf *response* (query-bucket "zs3-demo" :delimiter "/" :prefix "b/"))</b>
 962   => #&lt;BUCKET-LISTING "zs3-demo">
 963
 964   * <b>(values (keys *response*) (common-prefixes *response*))</b>
 965   => #(#&lt;KEY "b/1" 4>
 966        #&lt;KEY "b/2" 4>
 967        #&lt;KEY "b/3" 4>),
 968      #()</pre>
 969
 970     <p>For more information about bucket queries,
 971     see <a href="http://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketGET.html">GET
 972     Bucket</a> in the Amazon S3 developer documentation.
 973
 974   </blockquote>
 975
 976 </div>
 977
 978
 979 <div class='item'>
 980   <div class='type'><a name='continue-bucket-query'>[Function]</a></div>
 981   <div class='signature'>
 982     <code class='name'>continue-bucket-query</code>
 983     <span class='args'>
 984       <var>response</var>
 985     </span>
 986     <span class='result'>=> <var>response</var></span>
 987   </div>
 988
 989   <blockquote class='description'>
 990     <p>If <var>response</var> is a truncated response from a previous
 991     call to
 992       <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a>,
 993       continue-bucket-query returns the result of resuming the query at the
 994       truncation point. When there are no more results,
 995       continue-bucket-query returns NIL.
 996   </blockquote>
 997 </div>
 998
 999 <div class='item'>
1000   <div class='type'><a name='bucket-name'>[Function]</a></div>
1001   <div class='signature'>
1002     <code class='name'>bucket-name</code>
1003     <span class='args'>
1004       <var>response</var>
1005     </span>
1006     <span class='result'>=> <var>name</var></span>
1007   </div>
1008
1009   <blockquote class='description'>
1010     <p>Returns the name of the bucket used in the call
1011       to <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> that
1012       produced <var>response</var>.
1013   </blockquote>
1014 </div>
1015
1016
1017
1018
1019 <div class='item'>
1020   <div class='type'><a name='keys'>[Function]</a></div>
1021   <div class='signature'>
1022     <code class='name'>keys</code>
1023     <span class='args'>
1024       <var>response</var>
1025     </span>
1026     <span class='result'>=> <var>keys-vector</var></span>
1027   </div>
1028
1029   <blockquote class='description'>
1030     <p>Returns the vector of key objects in <var>response</var>. Key
1031     object attributes are accessible via
1032       <a href='#name'><tt>NAME</tt></a>,
1033       <a href='#size'><tt>SIZE</tt></a>,
1034       <a href='#etag'><tt>ETAG</tt></a>,
1035       <a href='#last-modified'><tt>LAST-MODIFIED</tt></a>,
1036       and <a href='#owner'><tt>OWNER</tt></a>.
1037   </blockquote>
1038 </div>
1039
1040
1041 <div class='item'>
1042   <div class='type'><a name='common-prefixes'>[Function]</a></div>
1043   <div class='signature'>
1044     <code class='name'>common-prefixes</code>
1045     <span class='args'>
1046       <var>response</var>
1047     </span>
1048     <span class='result'>=> <var>prefix-vector</var></span>
1049   </div>
1050
1051   <blockquote class='description'>
1052     <p>Returns a vector of common prefix strings, based on the
1053       delimiter argument of
1054       the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
1055       produced <var>response</var>.
1056   </blockquote>
1057 </div>
1058
1059
1060 <div class='item'>
1061   <div class='type'><a name='prefix'>[Function]</a></div>
1062   <div class='signature'>
1063     <code class='name'>prefix</code>
1064     <span class='args'>
1065       <var>response</var>
1066     </span>
1067     <span class='result'>=> <var>prefix-string</var></span>
1068   </div>
1069
1070   <blockquote class='description'>
1071     <p>Returns the prefix given to
1072     the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
1073     produced <var>response</var>. If present, all keys
1074     in <var>response</var> have <var>prefix-string</var> as a prefix.
1075   </blockquote>
1076 </div>
1077
1078 <div class='item'>
1079   <div class='type'><a name='marker'>[Function]</a></div>
1080   <div class='signature'>
1081     <code class='name'>marker</code>
1082     <span class='args'>
1083       <var>response</var>
1084     </span>
1085     <span class='result'>=> <var>marker</var></span>
1086   </div>
1087
1088   <blockquote class='description'>
1089     <p>Returns the marker given to
1090       the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
1091       produced <var>response</var>. If present,
1092       it lexically precedes all key names in the response.
1093   </blockquote>
1094 </div>
1095
1096 <div class='item'>
1097   <div class='type'><a name='delimiter'>[Function]</a></div>
1098   <div class='signature'>
1099     <code class='name'>delimiter</code>
1100     <span class='args'>
1101       <var>response</var>
1102     </span>
1103     <span class='result'>=> <var>delimiter</var></span>
1104   </div>
1105
1106   <blockquote class='description'>
1107     <p>Returns the delimiter used in
1108       the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
1109       produced <var>response</var>.
1110   </blockquote>
1111 </div>
1112
1113
1114 <div class='item'>
1115   <div class='type'><a name='truncatedp'>[Function]</a></div>
1116   <div class='signature'>
1117     <code class='name'>truncatedp</code>
1118     <span class='args'>
1119       <var>response</var>
1120     </span>
1121     <span class='result'>=> <var>boolean</var></span>
1122   </div>
1123
1124   <blockquote class='description'>
1125     <p>Returns <i>true</i> if <var>response</var> is truncated; that
1126     is, if there is more data to retrieve for a
1127     given <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a>
1128     query. <a href='#continue-bucket-query'><tt>CONTINUE-BUCKET-QUERY</tt></a>
1129     may be used to fetch more data.
1130   </blockquote>
1131 </div>
1132
1133
1134 <div class='item'>
1135   <div class='type'><a name='last-modified'>[Function]</a></div>
1136   <div class='signature'>
1137     <code class='name'>last-modified</code>
1138     <span class='args'>
1139       <var>key-object</var>
1140     </span>
1141     <span class='result'>=> <var>universal-time</var></span>
1142   </div>
1143
1144   <blockquote class='description'>
1145     <p>Returns a universal time representing the last modified time
1146     of <var>key-object</var>.
1147   </blockquote>
1148 </div>
1149
1150
1151 <div class='item'>
1152   <div class='type'><a name='etag'>[Function]</a></div>
1153   <div class='signature'>
1154     <code class='name'>etag</code>
1155     <span class='args'>
1156       <var>key-object</var>
1157     </span>
1158     <span class='result'>=> <var>etag-string</var></span>
1159   </div>
1160
1161   <blockquote class='description'>
1162     <p>Returns the etag for <var>key-object</var>.
1163   </blockquote>
1164 </div>
1165
1166
1167 <div class='item'>
1168   <div class='type'><a name='size'>[Function]</a></div>
1169   <div class='signature'>
1170     <code class='name'>size</code>
1171     <span class='args'>
1172       <var>key-object</var>
1173     </span>
1174     <span class='result'>=> <var>size</var></span>
1175   </div>
1176
1177   <blockquote class='description'>
1178     <p>Returns the size, in octets, of <var>key-object</var>.
1179   </blockquote>
1180 </div>
1181
1182
1183 <div class='item'>
1184   <div class='type'><a name='owner'>[Function]</a></div>
1185   <div class='signature'>
1186     <code class='name'>owner</code>
1187     <span class='args'>
1188       <var>key-object</var>
1189     </span>
1190     <span class='result'>=> <var>owner</var></span>
1191   </div>
1192
1193   <blockquote class='description'>
1194       <p>Returns the owner of <var>key-object</var>, or NIL if no owner
1195       information is available.
1196   </blockquote>
1197 </div>
1198
1199
1200 <div class='item'>
1201   <div class='type'><a name='storage-class'>[Function]</a></div>
1202   <div class='signature'>
1203     <code class='name'>storage-class</code>
1204     <span class='args'>
1205       <var>key-object</var>
1206     </span>
1207     <span class='result'>=> <var>storage-class</var></span>
1208   </div>
1209
1210   <blockquote class='description'>
1211     <p>Returns the storage class of <var>key-object</var>.
1212   </blockquote>
1213 </div>
1214
1215
1216
1217
1218
1219 <a name='object-ops'><h3>Operations on Objects</h3></a>
1220
1221 <p>Objects are the stored binary data in S3. Every object is uniquely
1222   identified by a bucket/key pair. ZS3 has several functions for
1223   storing and fetching objects, and querying object attributes.
1224
1225 <div class='item'>
1226   <div class='type'><a name='get-object'>[Function]</a></div>
1227   <div class='signature'>
1228     <code class='name'>get-object</code>
1229     <span class='args'>
1230       <var>bucket</var>
1231       <var>key</var>
1232       <code class='llkw'>&amp;key</code>
1233       <var>output</var> <br>
1234       <var>start</var> <var>end</var> <br>
1235       <var>when-modified-since</var> <var>unless-modified-since</var> <br>
1236       <var>when-etag-matches</var> <var>unless-etag-matches</var> <br>
1237       <var>if-exists</var> <var>string-external-format</var>
1238       <var>credentials</var>
1239       <var>backoff</var>
1240     </span>
1241     <span class='result'>=> <var>object</var></span>
1242   </div>
1243
1244   <blockquote class='description'>
1245     <p>Fetch the object referenced by <var>bucket</var>
1246     and <var>key</var>. The secondary value of all successful requests
1247     is an alist of <a href='http://weitz.de/drakma/'>Drakma</a>-style
1248     response HTTP headers.
1249
1250     <p>If <var>output</var> is <code class='kw'>:VECTOR</code> (the
1251     default), the object's octets are returned in a vector.
1252
1253     <p>If <var>output</var> is <code class='kw'>:STRING</code>, the
1254     object's octets are converted to a string using the encoding
1255     specified by <var>string-external-format</var>, which defaults
1256     to <code class='kw'>:UTF-8</code>. See <a href="http://weitz.de/flexi-streams/#external-formats">External
1257     formats</a> in the FLEXI-STREAMS documentation for supported
1258     values for the string external format. Note that, even
1259     when <var>output</var> is <code class='kw'>:STRING</code>, the
1260     start and end arguments operate on the object's underlying octets,
1261     not the string representation in a particular encoding. It's
1262     possible to produce a subsequence of the object's octets that are
1263     not valid in the desired encoding.
1264
1265     <p>If <var>output</var> is a string or pathname, the object's
1266     octets are saved to a file identified by the string or
1267     pathname. The <var>if-exists</var> argument is passed
1268     to <code>WITH-OPEN-FILE</code> to control the behavior when the
1269     output file already exists. It defaults
1270     to <code class='kw'>:SUPERSEDE</code>.
1271
1272     <p>If <var>output</var> is <code class='kw'>:STREAM</code>, a
1273     stream is returned from which the object's contents may be read.
1274
1275     <p><var>start</var> marks the first index fetched from the
1276     object's data. <var>end</var> specifies the index after the last
1277     octet fetched. If start is NIL, it defaults to 0. If end is nil,
1278     it defaults to the total length of the object. If
1279     both <var>start</var> and <var>end</var> are
1280     provided, <var>start</var> must be less than or equal
1281     to <var>end</var>.
1282
1283     <p><var>when-modified-since</var>
1284     and <var>unless-modified-since</var> are optional. If
1285     <var>when-modified-since</var> is provided, the result will be the normal
1286     object value if the object has been modified since the provided
1287     universal time, NIL otherwise. The logic is reversed for
1288     <var>unless-modified-since</var>.
1289
1290     <p><var>when-etag-matches</var> and <var>unless-etag-matches</var> are optional. If
1291     <var>when-etag-matches</var> is provided, the result will be the
1292     normal object value if the object's etag matches the provided
1293     string, NIL otherwise. The logic is reversed
1294     for <var>unless-etag-matches</var>.
1295
1296   </blockquote>
1297 </div>
1298
1299 <div class='item'>
1300   <div class='type'><a name='get-vector'>[Function]</a></div>
1301   <div class='signature'>
1302     <code class='name'>get-vector</code>
1303     <span class='args'>
1304       <var>bucket</var> <var>key</var>
1305       <code class='llkw'>&amp;key</code>
1306       <var>start</var> <var>end</var>
1307       <var>when-modified-since</var> <var>unless-modified-since</var>
1308       <var>when-etag-matches</var> <var>unless-etag-matches</var>
1309       <var>credentials</var>
1310       <var>backoff</var>
1311     </span>
1312     <span class='result'>=> <var>vector</var></span>
1313   </div>
1314
1315   <blockquote class='description'>
1316     <p>get-vector is a convenience interface to <a href='#get-object'><tt>GET-OBJECT</tt></a>. It is equivalent
1317       to calling:
1318
1319 <pre class='code'>
1320   (get-object bucket key <b>:output :vector</b> ...)
1321 </pre>
1322   </blockquote>
1323 </div>
1324
1325 <div class='item'>
1326   <div class='type'><a name='get-string'>[Function]</a></div>
1327   <div class='signature'>
1328     <code class='name'>get-string</code>
1329     <span class='args'>
1330       <var>bucket</var> <var>key</var>
1331       <code class='llkw'>&amp;key</code>
1332       <var>external-format</var>
1333       <var>start</var> <var>end</var>
1334       <var>when-modified-since</var>
1335       <var>unless-modified-since</var>
1336       <var>when-etag-matches</var>
1337       <var>unless-etag-matches</var>
1338       <var>credentials</var>
1339       <var>backoff</var>
1340     </span>
1341     <span class='result'>=> <var>string</var></span>
1342   </div>
1343
1344   <blockquote class='description'>
1345     get-string is a convenience interface
1346     to <a href='#get-object'><tt>GET-OBJECT</tt></a>. It is equivalent
1347     to calling:
1348
1349 <pre class='code'>
1350   (get-object bucket key <b>:output :string</b> :string-external-format external-format ...)
1351 </pre>
1352
1353   </blockquote>
1354 </div>
1355
1356 <div class='item'>
1357   <div class='type'><a name='get-file'>[Function]</a></div>
1358   <div class='signature'>
1359     <code class='name'>get-file</code>
1360     <span class='args'>
1361       <var>bucket</var> <var>key</var> <var>file</var>
1362       <code class='llkw'>&amp;key</code>
1363       <var>start</var> <var>end</var>
1364       <var>when-modified-since</var>
1365       <var>unless-modified-since</var>
1366       <var>when-etag-matches</var>
1367       <var>unless-etag-matches</var>
1368       <var>credentials</var>
1369       <var>backoff</var>
1370     </span>
1371     <span class='result'>=> <var>pathname</var></span>
1372   </div>
1373
1374   <blockquote class='description'>
1375     <p>get-file is a convenience interface
1376       to <a href='#get-object'><tt>GET-OBJECT</tt></a>. It is
1377       equivalent to calling:
1378
1379 <pre class='code'>
1380   (get-object bucket key <b>:output file</b> ...)
1381 </pre>
1382
1383   </blockquote>
1384 </div>
1385
1386
1387 <div class='item'>
1388   <div class='type'><a name='put-object'>[Function]</a></div>
1389   <div class='signature'>
1390     <code class='name'>put-object</code>
1391     <span class='args'>
1392       <var>object</var> <var>bucket</var> <var>key</var>
1393       <code class='llkw'>&amp;key</code>
1394       <var>access-policy</var>
1395       <var>public</var>
1396       <var>metadata</var>
1397       <var>string-external-format</var>
1398       <var>cache-control</var>
1399       <var>content-encoding</var>
1400       <var>content-disposition</var>
1401       <var>content-type</var>
1402       <var>expires</var>
1403       <var>storage-class</var>
1404       <var>credentials</var>
1405       <var>backoff</var>
1406     </span>
1407     <span class='result'>=> <var>response</var></span>
1408   </div>
1409
1410   <blockquote class='description'>
1411     <p>Stores the octets of <var>object</var> in the location
1412     identified by <var>bucket</var> and <var>key</var>.
1413
1414     <p>If <i>object</i> is an octet vector, it is stored directly.
1415
1416     <p>If <i>object</i> is a string, it is converted to an octet
1417     vector using <i>string-external-format</i>, which defaults
1418     to <code class='kw'>:UTF-8</code>, then
1419     stored. See <a href="http://weitz.de/flexi-streams/#external-formats">External
1420     formats</a> in the FLEXI-STREAMS documentation for supported
1421     values for the string external format.
1422
1423     <p>If <i>object</i> is a pathname, its contents are loaded in
1424     memory as an octet vector and stored.
1425
1426     <p>If provided, <var>access-policy</var> should be one of the
1427     following:
1428
1429       <ul>
1430         <li> <code class='kw'>:PRIVATE</code> - object owner is
1431           granted <code class='kw'>:FULL-CONTROL</code>; this is the
1432           default behavior if no access policy is provided
1433         <li> <code class='kw'>:PUBLIC-READ</code> - all users,
1434           regardless of authentication, can read the object
1435         <li> <code class='kw'>:AUTHENTICATED-READ</code> -
1436           authenticated Amazon AWS users can read the object
1437       </ul>
1438
1439     <p>For more information about access policies,
1440       see <a href='http://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl'>Canned ACL</a> in the Amazon S3 developer documentation.
1441
1442     <p>If <var>public</var> is <i>true</i>, it has the same effect as
1443       providing an <var>access-policy</var>
1444       of <code class='kw'>:PUBLIC-READ</code>. An error is signaled if
1445       both <var>public</var> and
1446       <var>access-policy</var> are provided.
1447
1448
1449     <p>If provided, <var>metadata</var> should be an alist of Amazon
1450     metadata to set on the object. When the object is fetched again,
1451     the metadata will be returned in HTTP headers prefixed with
1452     "x-amz-meta-".
1453
1454     <p>The <i>cache-control</i>, <i>content-encoding</i>, <i>content-disposition</i>,
1455     <i>content-type</i>, and <i>expires</i> values are all used to set
1456     HTTP properties of the object that are returned with subsequent
1457     GET or HEAD requests. If <i>content-type</i> is not set, it
1458     defaults to "binary/octet-stream". The others default to
1459     NIL. If <i>expires</i> is provided, it should be a universal time.
1460
1461     <p>If provided, <var>storage-class</var> should refer to one of
1462     the standard storage classes available for S3; currently the
1463     accepted values are the strings "STANDARD" and
1464     "REDUCED_REDUNDANCY". Using other values may trigger an API error
1465     from S3. For more information about reduced redundancy storage,
1466     see <a href="http://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.html#RRS">reduced
1467     Redundancy Storage</a> in the Developer Guide.
1468 </div>
1469
1470 <div class='item'>
1471   <div class='type'><a name='put-vector'>[Function]</a></div>
1472   <div class='signature'>
1473     <code class='name'>put-vector</code>
1474     <span class='args'>
1475       <var>vector</var>
1476       <var>bucket</var>
1477       <var>key</var> <code class='llkw'>&amp;key</code>
1478       <var>start</var> <var>end</var>
1479       <var>access-policy</var>
1480       <var>public</var> <var>metadata</var>
1481       <var>content-disposition</var>
1482       <var>content-encoding</var>
1483       <var>content-type</var>
1484       <var>expires</var>
1485       <var>storage-class</var>
1486       <var>credentials</var>
1487       <var>backoff</var>
1488     </span>
1489     <span class='result'>=> <var>response</var></span>
1490   </div>
1491
1492   <blockquote class='description'>
1493     <p>put-vector is a convenience interface
1494     to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It is similar
1495     to calling:
1496
1497 <pre class='code'>
1498   (put-object vector bucket key ...)
1499 </pre>
1500   </blockquote>
1501
1502   <p>If one of <var>start</var> or <var>end</var> is provided, they
1503     are used as bounding index designators on the string, and only a
1504     subsequence is used.
1505 </div>
1506
1507 <div class='item'>
1508   <div class='type'><a name='put-string'>[Function]</a></div>
1509   <div class='signature'>
1510     <code class='name'>put-string</code>
1511     <span class='args'>
1512       <var>string</var> <var>bucket</var> <var>key</var>
1513       <code class='llkw'>&amp;key</code>
1514       <var>start</var> <var>end</var>
1515       <var>external-format</var>
1516       <var>access-policy</var>
1517       <var>public</var> <var>metadata</var>
1518       <var>content-disposition</var>
1519       <var>content-encoding</var>
1520       <var>content-type</var>
1521       <var>expires</var>
1522       <var>storage-class</var>
1523       <var>credentials</var>
1524       <var>backoff</var>
1525     </span>
1526     <span class='result'>=> <var>response</var></span>
1527   </div>
1528
1529   <blockquote class='description'>
1530     <p>put-string is a convenience interface
1531 to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It is similar to
1532 calling:
1533
1534 <pre class='code'>
1535   (put-object string bucket key :string-external-format external-format ...)
1536 </pre>
1537   </blockquote>
1538
1539   <p>If one of <var>start</var> or end is <var>supplied</var>, they
1540     are used as bounding index designators on the string, and only a
1541     substring is used.
1542 </div>
1543
1544 <div class='item'>
1545   <div class='type'><a name='put-file'>[Function]</a></div>
1546   <div class='signature'>
1547     <code class='name'>put-file</code>
1548     <span class='args'>
1549       <var>file</var> <var>bucket</var> <var>key</var>
1550       <code class='llkw'>&amp;key</code>
1551       <var>start</var> <var>end</var>
1552       <var>access-policy</var>
1553       <var>public</var> <var>metadata</var>
1554       <var>content-disposition</var> <var>content-encoding</var> <var>content-type</var>
1555       <var>expires</var>
1556       <var>storage-class</var>
1557       <var>credentials</var>
1558       <var>backoff</var>
1559     </span>
1560     <span class='result'>=> <var>response</var></span>
1561   </div>
1562
1563   <blockquote class='description'>
1564     <p>put-file is a convenience interface
1565     to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It is almost
1566     equivalent to calling:
1567
1568 <pre class='code'>
1569   (put-object (pathname file) bucket key ...)
1570 </pre>
1571
1572     <p>If <var>key</var> is T, the <code>FILE-NAMESTRING</code> of
1573       the file is used as the key instead of <i>key</i>.
1574
1575     <p>If one of <var>start</var> or <var>end</var> is supplied, only
1576       a subset of the file is used. If <var>start</var> is not
1577       NIL, <var>start</var> octets starting from the beginning of the
1578       file are skipped. If <var>end</var> is not NIL, octets in the
1579       file at and after <var>end</var> are ignored. An error of type
1580       <tt>CL:END-OF-FILE</tt> is signaled if <var>end</var> is
1581       provided and the file size is less than <var>end</var>.
1582   </blockquote>
1583 </div>
1584
1585
1586 <div class='item'>
1587   <div class='type'><a name='put-stream'>[Function]</a></div>
1588   <div class='signature'>
1589     <code class='name'>put-stream</code>
1590     <span class='args'>
1591       <var>file</var> <var>bucket</var> <var>key</var>
1592       <code class='llkw'>&amp;key</code>
1593       <var>start</var> <var>end</var>
1594       <var>access-policy</var>
1595       <var>public</var> <var>metadata</var>
1596       <var>content-disposition</var> <var>content-encoding</var> <var>content-type</var>
1597       <var>expires</var>
1598       <var>storage-class</var>
1599       <var>credentials</var>
1600       <var>backoff</var>
1601     </span>
1602     <span class='result'>=> <var>response</var></span>
1603   </div>
1604
1605   <blockquote class='description'>
1606     <p>put-stream is similar to
1607     to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It has the same
1608     effect as collecting octets from <var>stream</var> into a vector
1609     and using:
1610
1611 <pre class='code'>
1612   (put-object vector bucket key ...)
1613 </pre>
1614
1615     <p>If <var>start</var> is not NIL, <var>start</var> octets
1616       starting from the current position in the stream are skipped
1617       before collecting.
1618
1619     <p>If <var>end</var> is NIL, octets are collected until the end of
1620       the stream is reached.
1621
1622     <p>If <var>end</var> is not NIL, collecting octets stops just
1623       before reaching <var>end</var> in the stream. An error of type
1624       <tt>CL:END-OF-FILE</tt> is signaled if the stream ends
1625       prematurely.
1626   </blockquote>
1627 </div>
1628
1629
1630 <div class='item'>
1631   <div class='type'><a name='copy-object'>[Function]</a></div>
1632   <div class='signature'>
1633     <code class='name'>copy-object</code>
1634     <span class='args'>
1635       <code class='llkw'>&amp;key</code>
1636       <var>from-bucket</var>
1637       <var>from-key</var>
1638       <var>to-bucket</var>
1639       <var>to-key</var> <br>
1640       <var>access-policy</var>
1641       <var>public</var> <br>
1642       <var>when-etag-matches</var>
1643       <var>unless-etag-matches</var> <br>
1644       <var>when-modified-since</var>
1645       <var>unless-modified-since</var> <br>
1646       <var>metadata</var> <var>public</var> <var>precondition-errors</var>
1647       <var>storage-class</var>
1648       <var>credentials</var>
1649       <var>backoff</var>
1650     </span>
1651     <span class='result'>=> <var>response</var></span>
1652   </div>
1653
1654   <blockquote class='description'>
1655     <p>Copies the object identified by <var>from-bucket</var>
1656     and <var>from-key</var> to a new location identified by
1657     <var>to-bucket</var> and <var>to-key</var>.
1658
1659     If <var>to-bucket</var> is NIL, <var>from-bucket</var> is used as
1660     the target. If <var>to-key</var> is nil, <var>from-key</var> is
1661     used as the target. An error is signaled if both <var>to-bucket</var> and
1662     <var>to-key</var> are NIL.
1663
1664     <p><var>access-policy</var> and <var>public</var> have the same
1665       effect on the target object as
1666       in <a href='#put-object'><tt>PUT-OBJECT</tt></a>.
1667
1668     <p>The precondition arguments <var>when-etag-matches</var>, <var>unless-etag-matches</var>,
1669     <var>when-modified-since</var>, and <var>unless-modified-since</var> work the same way they
1670     do in <a href='#get-object'><tt>GET-OBJECT</tt></a>, but with one difference: if <var>precondition-errors</var> is
1671     <i>true</i>, an <code>PRECONDITION-FAILED</code> error is signaled
1672     when a precondition does not hold, instead of returning NIL.
1673
1674     <p>If <var>metadata</var> is explicitly provided, it follows the
1675     same behavior as
1676     with <a href='#put-object'><tt>PUT-OBJECT</tt></a>. Passing NIL
1677     means that the new object has no metadata. Otherwise, the metadata
1678     is copied from the original object.
1679
1680     <p>If <var>storage-class</var> is provided, it should refer to one
1681     of the standard storage classes available for S3; currently the
1682     accepted values are the strings "STANDARD" and
1683     "REDUCED_REDUNDANCY". Using other values may trigger an API error
1684     from S3. For more information about reduced redundancy storage,
1685     see <a href="http://docs.aws.amazon.com/AmazonS3/latest/dev/Introduction.html#RRS">Reduced
1686     Redundancy Storage</a> in the Developer Guide.
1687   </blockquote>
1688 </div>
1689
1690 <div class='item'>
1691   <div class='type'><a name='delete-object'>[Function]</a></div>
1692   <div class='signature'>
1693     <code class='name'>delete-object</code>
1694     <span class='args'>
1695       <var>bucket</var>
1696       <var>key</var>
1697       <code class='llkw'>&amp;key</code>
1698       <var>credentials</var>
1699       <var>backoff</var>
1700     </span>
1701     <span class='result'>=> <var>response</var></span>
1702   </div>
1703
1704   <blockquote class='description'>
1705     <p>Deletes the object identified by <var>bucket</var>
1706       and <var>key</var>.
1707     <p>If <var>bucket</var> is a valid bucket for
1708       which you have delete access granted, S3 will always return a success
1709       response, even if <var>key</var> does not reference an existing
1710       object.
1711   </blockquote>
1712 </div>
1713
1714 <div class='item'>
1715   <div class='type'><a name='delete-objects'>[Function]</a></div>
1716   <div class='signature'>
1717     <code class='name'>delete-objects</code>
1718     <span class='args'>
1719       <var>bucket</var>
1720       <var>keys</var>
1721       <code class='llkw'>&amp;key</code>
1722       <var>credentials</var>
1723       <var>backoff</var>
1724     </span>
1725     <span class='result'>=> <var>deleted-count</var>, <var>errors</var></span>
1726   </div>
1727
1728   <blockquote class='description'>
1729     <p>Deletes <var>keys</var>, which should be a sequence of keys,
1730     from <var>bucket</var>. The primary value is the number of objects
1731     deleted. The secondary value is a list of error plists; if there
1732     are no errors deleting any of the keys, the secondary value is
1733     NIL.
1734   </blockquote>
1735 </div>
1736
1737 <div class='item'>
1738   <div class='type'><a name='delete-all-objects'>[Function]</a></div>
1739   <div class='signature'>
1740     <code class='name'>delete-all-objects</code>
1741     <span class='args'>
1742       <var>bucket</var>
1743       <code class='llkw'>&amp;key</code>
1744       <var>credentials</var>
1745       <var>backoff</var>
1746     </span>
1747     <span class='result'>=> <var>count</var></span>
1748   </div>
1749
1750   <blockquote class='description'>
1751     <p>Deletes all objects in <var>bucket</var> and returns the count
1752       of objects deleted.
1753   </blockquote>
1754 </div>
1755
1756
1757 <div class='item'>
1758   <div class='type'><a name='object-metadata'>[Function]</a></div>
1759   <div class='signature'>
1760     <code class='name'>object-metadata</code>
1761     <span class='args'>
1762       <var>bucket</var>
1763       <var>key</var>
1764       <code class='llkw'>&amp;key</code>
1765       <var>credentials</var>
1766       <var>backoff</var>
1767     </span>
1768     <span class='result'>=> <var>metadata-alist</var></span>
1769   </div>
1770
1771   <blockquote class='description'>
1772     <p>Returns the metadata for the object identified by <var>bucket</var> and <var>key</var>, or
1773     NIL if there is no metadata. For example:
1774
1775 <pre class='code'>
1776   * <b>(put-string "Hadjaha!" "zs3-demo" "hadjaha.txt" :metadata (parameters-alist :language "Swedish"))</b>
1777   => #&lt;RESPONSE 200 "OK" {1003BD2841}>
1778
1779   * <b>(object-metadata "zs3-demo" "hadjaha.txt")</b>
1780   => ((:LANGUAGE . "Swedish"))
1781 </pre>
1782
1783   </blockquote>
1784 </div>
1785
1786 <div class='item'>
1787   <div class='type'><a name='set-storage-class'>[Function]</a></div>
1788   <div class='signature'>
1789     <code class='name'>set-storage-class</code>
1790     <span class='args'>
1791       <var>bucket</var>
1792       <var>key</var>
1793       <var>storage-class</var>
1794       <code class='llkw'>&amp;key</code>
1795       <var>credentials</var>
1796       <var>backoff</var>
1797     </span>
1798     <span class='result'>=> <var>response</var></span>
1799   </div>
1800
1801   <blockquote class='description'>
1802     <p>Sets the storage class of the object identified
1803       by <var>bucket</var> and <var>key</var>
1804       to <var>storage-class</var>. This is a convenience function that
1805       uses <a href='#copy-object'><tt>COPY-OBJECT</tt></a> to make
1806       storage class changes.
1807
1808     <p>The storage class of an object can be determined by querying
1809       the bucket with <a href='#all-keys'><tt>ALL-KEYS</tt></a>
1810       or <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> and
1811       using <a href='#storage-class'><tt>STORAGE-CLASS</tt></a> on one
1812       of the resulting key objects.
1813   </blockquote>
1814 </div>
1815
1816
1817
1818 <a name='access-control'><h3>Access Control</h3></a>
1819
1820 <p>Each S3 resource has an associated access control list that is
1821   created automatically when the resource is created. The access
1822   control list specifies the resource owner and a list of permission
1823   grants.
1824
1825 <p>Grants consist of a permission and a grantee. The permission must
1826   be one of <code class='kw'>:READ</code>, <code class='kw'>:WRITE</code>,
1827   <code class='kw'>:READ-ACL</code>, <code class='kw'>:WRITE-ACL</code>,
1828   or <code class='kw'>:FULL-CONTROL</code>. The grantee should be a
1829   person object, an acl-group object, or an acl-email object.
1830
1831 <p>ZS3 has several functions that assist in reading, modifying, and
1832   storing access control lists.
1833
1834
1835 <div class='item'>
1836   <div class='type'><a name='get-acl'>[Function]</a></div>
1837   <div class='signature'>
1838     <code class='name'>get-acl</code>
1839     <span class='args'>
1840       <code class='llkw'>&amp;key</code>
1841       <var>bucket</var>
1842       <var>key</var>
1843       <var>credentials</var>
1844       <var>backoff</var>
1845     </span>
1846     <span class='result'>=> <var>owner</var>, <var>grants</var></span>
1847   </div>
1848
1849   <blockquote class='description'>
1850     <p>Returns the owner and grant list for a resource as
1851     multiple values.
1852   </blockquote>
1853 </div>
1854
1855
1856 <div class='item'>
1857   <div class='type'><a name='put-acl'>[Function]</a></div>
1858   <div class='signature'>
1859     <code class='name'>put-acl</code>
1860     <span class='args'>
1861       <var>owner</var> <var>grants</var>
1862       <code class='llkw'>&amp;key</code>
1863       <var>bucket</var>
1864       <var>key</var>
1865       <var>credentials</var>
1866       <var>backoff</var>
1867     </span>
1868     <span class='result'>=> <var>response</var></span>
1869   </div>
1870
1871   <blockquote class='description'>
1872     <p>Sets the owner and grant list of a resource.
1873   </blockquote>
1874 </div>
1875
1876
1877 <div class='item'>
1878   <div class='type'><a name='grant'>[Function]</a></div>
1879   <div class='signature'>
1880     <code class='name'>grant</code>
1881     <span class='args'>
1882       <var>permission</var>
1883       <code class='llkw'>&amp;key</code>
1884       <var>to</var>
1885     </span>
1886     <span class='result'>=> <var>grant</var></span>
1887   </div>
1888
1889   <blockquote class='description'>
1890     <p>Returns a grant object that represents a permission (one of <code class='kw'>:READ</code>, <code class='kw'>:WRITE</code>,
1891       <code class='kw'>:READ-ACL</code>, <code class='kw'>:WRITE-ACL</code>,
1892       or <code class='kw'>:FULL-CONTROL</code>) for the
1893       grantee <var>to</var>. For example:
1894
1895 <pre class='code'>
1896   * <b>(grant :full-control :to (<a href='#acl-email'>acl-email</a> "bob@example.com"))</b>
1897   => #&lt;GRANT :FULL-CONTROL to "bob@example.com">
1898
1899   * <b>(grant :read :to <a href='#*all-users*'>*all-users*</a>)</b>
1900   => #&lt;GRANT :READ to "AllUsers">
1901 </pre>
1902
1903     <p>It can be used to create or modify a grant list for use
1904     with <a href='#put-acl'><tt>PUT-ACL</tt></a>.
1905   </blockquote>
1906 </div>
1907
1908
1909 <div class='item'>
1910   <div class='type'><a name='acl-eqv'>[Function]</a></div>
1911   <div class='signature'>
1912     <code class='name'>acl-eqv</code>
1913     <span class='args'>
1914       <var>a</var> <var>b</var>
1915     </span>
1916     <span class='result'>=> <var>boolean</var></span>
1917   </div>
1918
1919   <blockquote class='description'>
1920     <p>Returns <i>true</i> if <var>a</var> and <var>b</var> are equivalent
1921       ACL-related objects (person, group, email, or grant).
1922   </blockquote>
1923 </div>
1924
1925
1926 <div class='item'>
1927   <div class='type'><a name='*all-users*'>[Special variable]</a></div>
1928   <div class='signature'>
1929     <code class='name'>*all-users*</code>
1930   </div>
1931
1932   <blockquote class='description'>
1933     <p>This acl-group includes all users, including unauthenticated
1934     clients.
1935   </blockquote>
1936 </div>
1937
1938
1939 <div class='item'>
1940   <div class='type'><a name='*aws-users*'>[Special variable]</a></div>
1941   <div class='signature'>
1942     <code class='name'>*aws-users*</code>
1943   </div>
1944
1945   <blockquote class='description'>
1946     <p>This acl-group object includes only users that have an
1947     Amazon Web Services account.
1948   </blockquote>
1949 </div>
1950
1951
1952 <div class='item'>
1953   <div class='type'><a name='*log-delivery*'>[Special variable]</a></div>
1954   <div class='signature'>
1955     <code class='name'>*log-delivery*</code>
1956   </div>
1957
1958   <blockquote class='description'>
1959     <p>This acl-group object includes the S3 system user that creates
1960       logfile objects. See
1961       also <a href='#enable-logging-to'><tt>ENABLE-LOGGING-TO</tt></a>.
1962   </blockquote>
1963 </div>
1964
1965
1966 <div class='item'>
1967   <div class='type'><a name='acl-email'>[Function]</a></div>
1968   <div class='signature'>
1969     <code class='name'>acl-email</code>
1970     <span class='args'>
1971       <var>email-address</var>
1972     </span>
1973     <span class='result'>=> <var>acl-email</var></span>
1974   </div>
1975
1976   <blockquote class='description'>
1977     <p>Returns an acl-email object, which can be used as a grantee for
1978       <a href='#grant'><tt>GRANT</tt></a>.
1979   </blockquote>
1980 </div>
1981
1982
1983 <div class='item'>
1984   <div class='type'><a name='acl-person'>[Function]</a></div>
1985   <div class='signature'>
1986     <code class='name'>acl-person</code>
1987     <span class='args'>
1988       <var>id</var>
1989       <code class='llkw'>&amp;optional</code>
1990       <var>display-name</var>
1991     </span>
1992     <span class='result'>=> <var>acl-person</var></span>
1993   </div>
1994
1995   <blockquote class='description'>
1996     <p>Returns an acl-person object for use as a resource owner (for
1997       <a href='#put-acl'><tt>PUT-ACL</tt></a>) or as a grantee
1998       (for <a href='#grant'><tt>GRANT</tt></a>). <var>id</var> must be
1999       a string representing the person's Amazon AWS canonical ID; for
2000       information about getting the canonical ID, see
2001       the <a href="http://docs.aws.amazon.com/AmazonS3/latest/dev/S3_ACLs_UsingACLs.html">Managing
2002       Access with ACLS</a>
2003       in the Amazon S3 developer
2004       documentation. If <var>display-name</var> is provided, it is
2005       used only for printing the object in Lisp; it is ignored when
2006       passed to S3.
2007   </blockquote>
2008 </div>
2009
2010
2011 <div class='item'>
2012   <div class='type'><a name='me'>[Function]</a></div>
2013   <div class='signature'>
2014     <code class='name'>me</code>
2015     <span class='args'>
2016       <code class='llkw'>&amp;key</code>
2017       <var>credentials</var>
2018       <var>backoff</var>
2019     </span>
2020     <span class='result'>=> <var>acl-person</var></span>
2021   </div>
2022
2023   <blockquote class='description'>
2024     <p>Returns the acl-person object associated with the current
2025       credentials.
2026
2027     <p>This data requires a S3 request, but the result is always the
2028     same per credentials and is cached.
2029   </blockquote>
2030 </div>
2031
2032
2033 <div class='item'>
2034   <div class='type'><a name='make-public'>[Function]</a></div>
2035   <div class='signature'>
2036     <code class='name'>make-public</code>
2037     <span class='args'>
2038       <code class='llkw'>&amp;key</code>
2039       <var>bucket</var>
2040       <var>key</var>
2041       <var>credentials</var>
2042       <var>backoff</var>
2043     </span>
2044     <span class='result'>=> <var>response</var></span>
2045   </div>
2046
2047   <blockquote class='description'>
2048     <p>Makes a resource publicly accessible, i.e. readable by
2049       the <a href='#*all-users*'><tt>*ALL-USERS*</tt></a> group.
2050   </blockquote>
2051 </div>
2052
2053
2054 <div class='item'>
2055   <div class='type'><a name='make-private'>[Function]</a></div>
2056   <div class='signature'>
2057     <code class='name'>make-private</code>
2058     <span class='args'>
2059       <code class='llkw'>&amp;key</code>
2060       <var>bucket</var>
2061       <var>key</var>
2062       <var>credentials</var>
2063       <var>backoff</var>
2064     </span>
2065     <span class='result'>=> <var>response</var></span>
2066   </div>
2067
2068   <blockquote class='description'>
2069     <p>Removes public access to a resource, i.e. removes all
2070       access grants for
2071       the <a href='#*all-users*'><tt>*ALL-USERS*</tt></a> group.
2072   </blockquote>
2073 </div>
2074
2075
2076
2077 <a name='access-logging'><h3>Access Logging</h3></a>
2078
2079 <p>S3 offers support for logging information about client
2080   requests. Logfile objects are delivered by a system user in
2081   the <a href='#*log-delivery*'><tt>*LOG-DELIVERY*</tt></a> group to a
2082   bucket of your choosing. For more information about S3 access
2083   logging and the logfile format, see
2084   the <a href="http://docs.aws.amazon.com/AmazonS3/latest/dev/ServerLogs.html">Server
2085   Access Logging</a> in the Amazon S3
2086   developer documentation.
2087
2088 <div class='item'>
2089   <div class='type'><a name='enable-logging-to'>[Function]</a></div>
2090   <div class='signature'>
2091     <code class='name'>enable-logging-to</code>
2092     <span class='args'>
2093       <var>bucket</var>
2094       <code class='llkw'>&amp;key</code>
2095       <var>credentials</var>
2096       <var>backoff</var>
2097     </span>
2098     <span class='result'>=> <var>response</var></span>
2099   </div>
2100
2101   <blockquote class='description'>
2102     Adds the necessary permission grants to <var>bucket</var> to allow
2103     S3 to write logfile objects into it.
2104   </blockquote>
2105 </div>
2106
2107
2108 <div class='item'>
2109   <div class='type'><a name='disable-logging-to'>[Function]</a></div>
2110   <div class='signature'>
2111     <code class='name'>disable-logging-to</code>
2112     <span class='args'>
2113       <var>bucket</var>
2114       <code class='llkw'>&amp;key</code>
2115       <var>credentials</var>
2116       <var>backoff</var>
2117     </span>
2118     <span class='result'>=> <var>response</var></span>
2119   </div>
2120
2121   <blockquote class='description'>
2122     <p>Changes the access control list of <var>bucket</var> to remove
2123     all grants for
2124     the <a href='#*log-delivery*'><tt>*LOG-DELIVERY*</tt></a> group.
2125   </blockquote>
2126 </div>
2127
2128
2129 <div class='item'>
2130   <div class='type'><a name='enable-logging'>[Function]</a></div>
2131   <div class='signature'>
2132     <code class='name'>enable-logging</code>
2133     <span class='args'>
2134       <var>bucket</var>
2135       <var>target-bucket</var>
2136       <var>target-prefix</var>
2137       <code class='llkw'>&amp;key</code>
2138       <var>target-grants</var>
2139       <var>credentials</var>
2140       <var>backoff</var>
2141     </span>
2142     <span class='result'>=> <var>response</var></span>
2143   </div>
2144
2145   <blockquote class='description'>
2146     <p>Enables logging of all requests
2147     involving <var>bucket</var>. Logfile objects are created in
2148       <var>target-bucket</var> and each logfile's key starts with
2149       <var>target-prefix</var>.
2150
2151     <p>When a new logfile is
2152       created, its list of access control grants is extended with
2153       <var>target-grants</var>, if any.
2154
2155     <p>If <var>target-bucket</var> does not have the necessary grants
2156     to allow logging, the grants are implicitly added by
2157     calling <a href='#enable-logging-to'><tt>ENABLE-LOGGING-TO</tt></a>.
2158   </blockquote>
2159 </div>
2160
2161
2162 <div class='item'>
2163   <div class='type'><a name='disable-logging'>[Function]</a></div>
2164   <div class='signature'>
2165     <code class='name'>disable-logging</code>
2166     <span class='args'>
2167       <var>bucket</var> <code class='llkw'>&amp;key</code>
2168       <var>credentials</var>
2169       <var>backoff</var>
2170     </span>
2171     <span class='result'>=> <var>response</var></span>
2172   </div>
2173
2174   <blockquote class='description'>
2175     Disables logging for <var>bucket</var>.
2176   </blockquote>
2177 </div>
2178
2179
2180 <div class='item'>
2181   <div class='type'><a name='logging-setup'>[Function]</a></div>
2182   <div class='signature'>
2183     <code class='name'>logging-setup</code>
2184     <span class='args'>
2185       <var>bucket</var>
2186       <code class='llkw'>&amp;key</code>
2187       <var>credentials</var>
2188       <var>backoff</var>
2189     </span>
2190     <span class='result'>=> <var>target-bucket</var>,
2191       <var>target-prefix</var>,
2192       <var>target-grants</var></span>
2193   </div>
2194
2195   <blockquote class='description'>
2196     <p>If logging is enabled for <var>bucket</var>, returns the target
2197       bucket, target prefix, and target grants as multiple values.
2198   </blockquote>
2199 </div>
2200
2201
2202 <a name='misc'><h3>Miscellaneous Operations</h3></a>
2203
2204 <p>
2205
2206 <div class='item'>
2207   <div class='type'><a name='*use-ssl*'>[Special variable]</a></div>
2208   <div class='signature'>
2209     <code class='name'>*use-ssl*</code>
2210   </div>
2211
2212   <blockquote class='description'>
2213     <p>When <i>true</i>, requests to S3 are sent via HTTPS. The
2214       default is NIL.
2215   </blockquote>
2216 </div>
2217
2218 <div class='item'>
2219   <div class='type'><a name='*use-keep-alive*'>[Special variable]</a></div>
2220   <div class='signature'>
2221     <code class='name'>*use-keep-alive*</code>
2222   </div>
2223
2224   <blockquote class='description'>
2225     <p>When <i>true</i>, HTTP keep-alives are used to reuse a single
2226     network connection for multiple requests.</p>
2227   </blockquote>
2228 </div>
2229
2230 <div class='item'>
2231   <div class='type'><a name='with-keep-alive'>[Macro]</a></div>
2232   <div class='signature'>
2233     <code class='name'>with-keep-alive</code>
2234     <span class='args'>
2235       <code class='llkw'>&amp;body</code> <var>body</var>
2236     </span>
2237     <span class='result'>=> |</span>
2238   </div>
2239
2240   <blockquote class='description'>
2241     <p>Evaluate <var>body</var> in a context
2242     where <a href='#*use-keep-alive*'><tt>*USE-KEEP-ALIVE*</tt></a>
2243     is <i>true</i>.
2244   </blockquote>
2245 </div>
2246
2247
2248
2249 <div class='item'>
2250   <div class='type'><a name='make-post-policy'>[Function]</a></div>
2251   <div class='signature'>
2252     <code class='name'>make-post-policy</code>
2253     <span class='args'>
2254       <code class='llkw'>&amp;key</code>
2255       <var>expires</var>
2256       <var>conditions</var>
2257       <var>credentials</var>
2258     </span>
2259     <span class='result'>=> <var>policy</var>, <var>signature</var></span>
2260   </div>
2261
2262   <blockquote class='description'>
2263     <p>Returns an encoded HTML POST form policy and its signature as
2264     multiple values. The policy can be used to conditionally allow any
2265     user to put objects into S3.
2266
2267     <p><var>expires</var> must be a universal time after which
2268     the policy is no longer accepted.
2269
2270     <p><var>conditions</var> must be a list of conditions that the
2271     posted form fields must satisfy. Each condition is a list of a
2272     condition keyword, a form field name, and the form field
2273     value. For example, the following are all valid conditions:
2274
2275     <p>
2276       <ul>
2277         <li> <code>(:starts-with "key" "uploads/")</code>
2278         <li> <code>(:eq "bucket" "user-uploads")</code>
2279         <li> <code>(:eq "acl" "public-read")</code>
2280         <li> <code>(:range "content-length-range" 1 10000)</code>
2281       </ul>
2282
2283     <p>These conditions are converted into a post policy description,
2284     base64-encoded, and returned as <var>policy</var>. The signature
2285     is returned as <var>signature</var>. These values can then be
2286     embedded in an HTML form and used to allow direct browser uploads.
2287
2288     <p>For example, if <var>policy</var> is
2289     "YSBwYXRlbnRseSBmYWtlIHBvbGljeQ==" and the policy signature is
2290     "ZmFrZSBzaWduYXR1cmU=", you could construct a form like this:
2291
2292 <p class='html'>
2293 &lt;form action="http://user-uploads.s3.amazonaws.com/" method="post" enctype="multipart/form-data"><br>
2294 &lt;input type="input" name="key" value="uploads/fun.jpg"><br>
2295 &lt;input type=hidden name="acl" value="public-read"><br>
2296 &lt;input type=hidden name="AWSAccessKeyId" value="8675309JGT9876430310"><br>
2297 &lt;input type=hidden name="Policy" value="YSBwYXRlbnRseSBmYWtlIHBvbGljeQ=="><br>
2298 &lt;input type=hidden name='Signature' value="ZmFrZSBzaWduYXR1cmU="><br>
2299 &lt;input name='file' type='file'><br>
2300 &lt;input type=submit value='Submit'><br>
2301 &lt;/form><br>
2302
2303    <p>For full, detailed documentation of browser-based POST uploads
2304    and policy documents,
2305    see <a href="http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingHTTPPOST.html">Browser-Based
2306    Uploads Using POST</a> in the Amazon S3 developer documentation.
2307   </blockquote>
2308 </div>
2309
2310
2311 <div class='item'>
2312   <div class='type'><a name='head'>[Function]</a></div>
2313   <div class='signature'>
2314     <code class='name'>head</code>
2315     <span class='args'>
2316       <code class='llkw'>&amp;key</code>
2317       <var>bucket</var>
2318       <var>key</var>
2319       <var>parameters</var>
2320       <var>credentials</var>
2321       <var>backoff</var>
2322     </span>
2323     <span class='result'>=> <var>headers-alist</var>,
2324       <var>status-code</var>,
2325       <var>phrase</var></span>
2326   </div>
2327
2328   <blockquote class='description'>
2329     <p>Submits a HTTP HEAD request for the resource identified by
2330       <var>bucket</var> and optionally <var>key</var>. Returns the
2331       <a href='http://weitz.de/drakma/'>Drakma</a> headers, HTTP
2332       status code, and HTTP phrase as multiple values.
2333
2334     <p>When <var>parameters</var> is supplied, it should be an alist
2335       of keys and values to pass as GET request parameters. For
2336       example:
2337
2338 <pre class='code'>
2339   * <b>(head :bucket "zs3-demo" :parameters (<a href='http://cliki.net/parameters-alist?download'>parameters-alist</a> :max-keys 0))</b>
2340   => ((:X-AMZ-ID-2  . "...")
2341       (:X-AMZ-REQUEST-ID . "...")
2342       (:DATE . "Sat, 27 Sep 2008 19:00:35 GMT")
2343       (:CONTENT-TYPE . "application/xml")
2344       (:TRANSFER-ENCODING . "chunked")
2345       (:SERVER . "AmazonS3")
2346       (:CONNECTION . "close")),
2347       200,
2348       "OK"</pre>
2349   </blockquote>
2350 </div>
2351
2352
2353 <div class='item'>
2354   <div class='type'><a name='authorized-url'>[Function]</a></div>
2355   <div class='signature'>
2356     <code class='name'>authorized-url</code>
2357     <span class='args'>
2358       <code class='llkw'>&amp;key</code>
2359       <var>bucket</var>
2360       <var>key</var>
2361       <var>vhost</var>
2362       <var>expires</var>
2363       <var>ssl</var>
2364       <var>sub-resource</var>
2365       <var>credentials</var>
2366     </span>
2367     <span class='result'>=> <var>url</var></span>
2368   </div>
2369
2370   <blockquote class='description'>
2371     <p>Creates an URL that allows temporary access to a resource regardless
2372     of its ACL.
2373
2374     <p>If neither <var>bucket</var> nor <var>key</var> is specified, the top-level bucket listing
2375     is accessible. If <var>key</var> is not specified, listing the keys of <var>bucket</var> is
2376     accessible. If both <var>bucket</var> and key are <var>specified</var>, the object specified
2377     by <var>bucket</var> and <var>key</var> is accessible.
2378
2379     <p><var>expires</var> is required, and should be the integer
2380     universal time after which the URL is no longer valid.
2381
2382     <p><var>vhost</var> controls the construction of the
2383     url. If <var>vhost</var> is nil, the constructed URL refers to the
2384     bucket, if present, as part of the path. If <var>vhost</var>
2385     is <code class='kw'>:AMAZON</code>, the bucket name is used as a
2386     prefix to the Amazon hostname. If <var>vhost</var>
2387     is <code class='kw'>:FULL</code>, the bucket name becomes the full
2388     hostname of the url. For example:
2389
2390 <pre class='code'>
2391   * <b>(authorized-url :bucket "foo" :key "bar" :vhost nil)</b>
2392   =&gt; "http://s3.amazonaws.com/foo/bar?..."
2393
2394   * <b>(authorized-url :bucket "foo" :key "bar" :vhost :amazon)</b>
2395   =&gt; "http://foo.s3.amazonaws.com/bar?..."
2396
2397   * <b>(authorized-url :bucket "foo.example.com" :key "bar" :vhost :full)</b>
2398   =&gt;  "http://foo.example.com/bar?..."
2399 </pre>
2400
2401     <p>If <i>ssl</i> is <i>true</i>, the URL has "https" as the scheme,
2402     otherwise it has "http".
2403
2404     <p>If <i>sub-resource</i> is specified, it is used as part of the
2405     query string to access a specific sub-resource. Example Amazon
2406     sub-resources include "acl" for access to the ACL, "location" for
2407     location information, and "logging" for logging information. For
2408     more information about the various sub-resources, see the Amazon
2409     S3 developer documentation.
2410   </blockquote>
2411 </div>
2412
2413
2414 <div class='item'>
2415   <div class='type'><a name='resource-url'>[Function]</a></div>
2416   <div class='signature'>
2417     <code class='name'>resource-url</code>
2418     <span class='args'>
2419       <code class='llkw'>&amp;key</code>
2420       <var>bucket</var>
2421       <var>key</var>
2422       <var>vhost</var>
2423       <var>ssl</var>
2424       <var>sub-resource</var>
2425     </span>
2426     <span class='result'>=> <var>url</var></span>
2427   </div>
2428
2429   <blockquote class='description'>
2430     <p>Returns an URL that can be used to reference a resource. See
2431       <a href='#authorized-url'><tt>AUTHORIZED-URL</tt></a> for more
2432       info.
2433   </blockquote>
2434 </div>
2435
2436
2437 <a name='utility'><h3>Utility Functions</h3></a>
2438
2439 <p>
2440
2441 <div class='item'>
2442   <div class='type'><a name='octet-vector'>[Function]</a></div>
2443   <div class='signature'>
2444     <code class='name'>octet-vector</code>
2445     <span class='args'>
2446       <code class='llkw'>&amp;rest</code>
2447       <var>octets</var>
2448     </span>
2449     <span class='result'>=> <var>octet-vector</var></span>
2450   </div>
2451
2452   <blockquote class='description'>
2453     <p>Returns a vector of type
2454       <code>(simple-array&nbsp;(unsigned-byte&nbsp;8)&nbsp;(*))</code> initialized with <var>octets</var>.
2455   </blockquote>
2456 </div>
2457
2458
2459 <div class='item'>
2460   <div class='type'><a name='now+'>[Function]</a></div>
2461   <div class='signature'>
2462     <code class='name'>now+</code>
2463     <span class='args'>
2464       <var>delta</var>
2465     </span>
2466     <span class='result'>=> <var>universal-time</var></span>
2467   </div>
2468
2469   <blockquote class='description'>
2470     <p>Returns a universal time that represents the current time
2471       incremented by <var>delta</var> seconds. It's useful for passing
2472       as the <code class='kw'>:EXPIRES</code> parameter to functions
2473       like <a href='#put-object'><tt>PUT-OBJECT</tt></a>
2474       and <a href='#authorized-url'><tt>AUTHORIZED-URL</tt></a>.
2475   </blockquote>
2476 </div>
2477
2478
2479 <div class='item'>
2480   <div class='type'><a name='now-'>[Function]</a></div>
2481   <div class='signature'>
2482     <code class='name'>now-</code>
2483     <span class='args'>
2484       <var>delta</var>
2485     </span>
2486     <span class='result'>=> <var>universal-time</var></span>
2487   </div>
2488
2489   <blockquote class='description'>
2490     <p>Like <a href='#now+'><tt>NOW+</tt></a>, but decrements the
2491       current time instead of incrementing it.
2492   </blockquote>
2493 </div>
2494
2495
2496 <div class='item'>
2497   <div class='type'><a name='file-etag'>[Function]</a></div>
2498   <div class='signature'>
2499     <code class='name'>file-etag</code>
2500     <span class='args'>
2501       <var>pathname</var>
2502     </span>
2503     <span class='result'>=> <var>etag</var></span>
2504   </div>
2505
2506   <blockquote class='description'>
2507     <p>Returns the etag of <var>pathname</var>. This can be useful for the
2508       conditional arguments
2509       <code class='kw'>:WHEN-ETAG-MATCHES</code> and
2510       <code class='kw'>:UNLESS-ETAG-MATCHES</code>
2511       in <a href='#get-object'><tt>GET-OBJECT</tt></a>
2512       and <a href='#copy-object'><tt>COPY-OBJECT</tt></a>.
2513   </blockquote>
2514 </div>
2515
2516
2517 <div class='item'>
2518   <div class='type'><a name='parameters-alist'>[Function]</a></div>
2519   <div class='signature'>
2520     <code class='name'>parameters-alist</code>
2521     <span class='args'>
2522       <code class='llkw'>&amp;rest</code>
2523       <var>parameters</var>
2524       <code class='llkw'>&amp;key</code>
2525       <code class='llkw'>&amp;allow-other-keys</code>
2526     </span>
2527     <span class='result'>=> <var>alist</var></span>
2528   </div>
2529
2530   <blockquote class='description'>
2531     <p>Returns an alist based on all keyword arguments passed to the
2532       function. Keywords are converted to their lowercase symbol name and
2533       values are converted to strings. For example:
2534
2535 <pre class='code'>
2536   * <b>(parameters-alist :name "Bob" :age 21)</b>
2537   => (("name" . "Bob") ("age" . "21"))
2538 </pre>
2539
2540     <p>This can be used to construct Amazon metadata alists
2541     for <a href='#put-object'><tt>PUT-OBJECT</tt></a>
2542     and <a href='#copy-object'><tt>COPY-OBJECT</tt></a>, or request
2543     parameters in <a href='#head'><tt>HEAD</tt></a>.
2544
2545   </blockquote>
2546 </div>
2547
2548
2549
2550 <div class='item'>
2551   <div class='type'><a name='clear-redirects'>[Function]</a></div>
2552   <div class='signature'>
2553     <code class='name'>clear-redirects</code>
2554     <span class='args'>
2555     </span>
2556     <span class='result'>=> |</span>
2557   </div>
2558
2559   <blockquote class='description'>
2560     <p>Clear ZS3's internal cache of redirections.
2561
2562     <p>Most ZS3 requests are submitted against the Amazon S3 endpoint
2563       "s3.amazonaws.com". Some requests, however, are permanently
2564       redirected by S3 to new endpoints. ZS3 maintains an internal cache
2565       of permanent redirects, but it's possible for that cache to get
2566       out of sync if external processes alter the bucket structure
2567
2568     <p>For example, if the bucket "eu.zs3" is created with a EU
2569       location constraint, S3 will respond to requests to that bucket
2570       with a permanent redirect to "eu.zs3.s3.amazonaws.com", and ZS3
2571       will cache that redirect information. But if the bucket is
2572       deleted and recreated by a third party, the redirect might no
2573       longer be necessary.
2574   </blockquote>
2575 </div>
2576
2577
2578 <a name='cloudfront'><h2>CloudFront</h2>
2579
2580 <p>CloudFront functions allow the creation and manipulation of
2581   distributions. In ZS3, distributions are represented by objects that
2582   reflect the state of a distributon at some point in time. It's
2583   possible for the distribution to change behind the scenes without
2584   notice, e.g. when a distribution's <a href='#status'>status</a> is
2585   updated from "InProgress" to "Deployed".
2586
2587   <p>The
2588   functions <a href='#enable'><tt>ENABLE</tt></a>, <a href='#disable'><tt>DISABLE</tt></a>, <a href='#ensure-cname'><tt>ENSURE-CNAME</tt></a>,
2589   <a href='#remove-cname'><tt>REMOVE-CNAME</tt></a>,
2590   and <a href='#set-comment'><tt>SET-COMMENT</tt></a> are designed so
2591   that regardless of the state of the distribution provided, after the
2592   function completes, the new state of the distribution will reflect
2593   the desired update. The
2594   functions <a href='#status'><tt>STATUS</tt></a>, <a href='#cnames'><tt>CNAMES</tt></a>,
2595   and
2596   <a href='#enabledp'><tt>ENABLEDP</tt></a> do not automatically
2597   refresh the object and therefore might reflect outdated
2598   information. To ensure the object has the most recent information,
2599   use <a href='#refresh'><tt>REFRESH</tt></a>. For example, to fetch
2600   the current, live status, use <tt>(status (refresh
2601   distribution))</tt>.
2602
2603
2604
2605 <div class='item'>
2606   <div class='type'><a name='all-distributions'>[Function]</a></div>
2607   <div class='signature'>
2608     <code class='name'>all-distributions</code>
2609     <span class='args'>
2610     </span>
2611     <span class='result'>=> |</span>
2612   </div>
2613
2614   <blockquote class='description'>
2615     <p>Returns a list of all distributions.
2616   </blockquote>
2617 </div>
2618
2619 <div class='item'>
2620   <div class='type'><a name='create-distribution'>[Function]</a></div>
2621   <div class='signature'>
2622     <code class='name'>create-distribution</code>
2623     <span class='args'>
2624       <var>bucket-name</var>
2625       <code class='llkw'>&amp;key</code>
2626       <var>cnames</var>
2627       <var>enabled</var>
2628       <var>comment</var>
2629     </span>
2630     <span class='result'>=> <var>distribution</var></span>
2631   </div>
2632
2633   <blockquote class='description'>
2634     Creates and returns a new distribution object that will cache
2635     objects from the bucket named
2636     by <var>bucket-name</var>.
2637
2638     <p>If <var>cnames</var> is provided, it is taken as a designator
2639     for a list of additional domain names that can be used to access
2640     the distribution.
2641
2642     <p>If <var>enabled</var> is NIL, the distribution is initially
2643       created in a disabled state. The default value is is T.
2644
2645     <p>If <var>comment</var> is provided, it becomes part of the newly
2646       created distribution.
2647   </blockquote>
2648 </div>
2649
2650 <div class='item'>
2651   <div class='type'><a name='delete-distribution'>[Function]</a></div>
2652   <div class='signature'>
2653     <code class='name'>delete-distribution</code>
2654     <span class='args'>
2655       <var>distribution</var>
2656     </span>
2657     <span class='result'>=> |</span>
2658   </div>
2659
2660   <blockquote class='description'>
2661     <p>Deletes <var>distribution</var>. Distributions must be disabled
2662       before deletion; see <a href='#disable'><tt>DISABLE</tt></a>.
2663   </blockquote>
2664 </div>
2665
2666
2667 <div class='item'>
2668   <div class='type'><a name='refresh'>[Function]</a></div>
2669   <div class='signature'>
2670     <code class='name'>refresh</code>
2671     <span class='args'>
2672       <var>distribution</var>
2673     </span>
2674     <span class='result'>=> <var>distribution</var></span>
2675   </div>
2676
2677   <blockquote class='description'>
2678     <p>Queries Amazon for the latest information
2679     regarding <var>distribution</var> and destructively modifies the
2680     instance with the new information. Returns its argument.
2681   </blockquote>
2682 </div>
2683
2684
2685 <div class='item'>
2686   <div class='type'><a name='enable'>[Function]</a></div>
2687   <div class='signature'>
2688     <code class='name'>enable</code>
2689     <span class='args'>
2690       <var>distribution</var>
2691     </span>
2692     <span class='result'>=> |</span>
2693   </div>
2694
2695   <blockquote class='description'>
2696     <p>Enables <var>distribution</var>.
2697   </blockquote>
2698 </div>
2699
2700
2701 <div class='item'>
2702   <div class='type'><a name='disable'>[Function]</a></div>
2703   <div class='signature'>
2704     <code class='name'>disable</code>
2705     <span class='args'>
2706       <var>distribution</var>
2707     </span>
2708     <span class='result'>=> |</span>
2709   </div>
2710
2711   <blockquote class='description'>
2712     <p>Disables <var>distribution</var>.
2713   </blockquote>
2714 </div>
2715
2716
2717 <div class='item'>
2718   <div class='type'><a name='ensure-cname'>[Function]</a></div>
2719   <div class='signature'>
2720     <code class='name'>ensure-cname</code>
2721     <span class='args'>
2722       <var>distribution</var>
2723       <var>cname</var>
2724     </span>
2725     <span class='result'>=> |</span>
2726   </div>
2727
2728   <blockquote class='description'>
2729     <p>Adds <var>cname</var> to the CNAMEs of <var>distribution</var>,
2730       if necessary.
2731   </blockquote>
2732 </div>
2733
2734 <div class='item'>
2735   <div class='type'><a name='remove-cname'>[Function]</a></div>
2736   <div class='signature'>
2737     <code class='name'>remove-cname</code>
2738     <span class='args'>
2739       <var>distribution</var>
2740       <var>cname</var>
2741     </span>
2742     <span class='result'>=> |</span>
2743   </div>
2744
2745   <blockquote class='description'>
2746     <p>Removes <var>cname</var> from the CNAMEs of <var>distribution</var>.
2747   </blockquote>
2748 </div>
2749
2750
2751 <div class='item'>
2752   <div class='type'><a name='set-comment'>[Function]</a></div>
2753   <div class='signature'>
2754     <code class='name'>set-comment</code>
2755     <span class='args'>
2756       <var>distribution</var>
2757       <var>comment</var>
2758     </span>
2759     <span class='result'>=> |</span>
2760   </div>
2761
2762   <blockquote class='description'>
2763     <p>Sets the comment of <var>distribution</var> to <var>comment</var>.
2764   </blockquote>
2765 </div>
2766
2767
2768 <div class='item'>
2769   <div class='type'><a name='distributions-for-bucket'>[Function]</a></div>
2770   <div class='signature'>
2771     <code class='name'>distributions-for-bucket</code>
2772     <span class='args'>
2773       <var>bucket-name</var>
2774     </span>
2775     <span class='result'>=> |</span>
2776   </div>
2777
2778   <blockquote class='description'>
2779     <p>Returns a list of distributions that
2780       have <var>bucket-name</var> as the origin bucket.
2781   </blockquote>
2782 </div>
2783
2784
2785 <div class='item'>
2786   <div class='type'><a name='distribution-error'>[Condition]</a></div>
2787   <div class='signature'>
2788     <code class='name'>distribution-error</code>
2789   </div>
2790
2791   <blockquote class='description'>
2792     <p>All errors signaled as a result of a CloudFront request error
2793       are subtypes of <tt>distribution-error</tt>.
2794   </blockquote>
2795 </div>
2796
2797
2798 <div class='item'>
2799   <div class='type'><a name='distribution-not-disabled'>[Condition]</a></div>
2800   <div class='signature'>
2801     <code class='name'>distribution-not-disabled</code>
2802   </div>
2803
2804   <blockquote class='description'>
2805     <p>Distributions must be fully disabled before they are
2806       deleted. If they have not been disabled, or the status of the
2807       distribution is still
2808       "InProgress", <tt>distribution-not-disabled</tt> is signaled.
2809   </blockquote>
2810 </div>
2811
2812
2813 <div class='item'>
2814   <div class='type'><a name='cname-already-exists'>[Condition]</a></div>
2815   <div class='signature'>
2816     <code class='name'>cname-already-exists</code>
2817   </div>
2818
2819   <blockquote class='description'>
2820     <p>A CNAME may only appear on one distribution. If you attempt to
2821       add a CNAME to a distribution that is already present on some
2822       other distribution, <tt>cname-already-exists</tt> is signaled.
2823   </blockquote>
2824 </div>
2825
2826
2827 <div class='item'>
2828   <div class='type'><a name='too-many-distributions'>[Condition]</a></div>
2829   <div class='signature'>
2830     <code class='name'>too-many-distributions</code>
2831   </div>
2832
2833   <blockquote class='description'>
2834     <p>If creating a new distribution
2835       via <a href='#create-distribution'><tt>CREATE-DISTRIBUTION</tt></a>
2836       would exceed the account limit of total distributions,
2837       <tt>too-many-distributions</tt> is signaled.
2838   </blockquote>
2839 </div>
2840
2841
2842 <div class='item'>
2843   <div class='type'><a name='status'>[Function]</a></div>
2844   <div class='signature'>
2845     <code class='name'>status</code>
2846     <span class='args'>
2847       <var>distribution</var>
2848     </span>
2849     <span class='result'>=> <var>status</var></span>
2850   </div>
2851
2852   <blockquote class='description'>
2853     <p>Returns a string describing the status
2854       of <var>distribution</var>. The status is either "InProgress",
2855       meaning that the distribution's configuration has not fully
2856       propagated through the CloudFront system, or "Deployed".
2857   </blockquote>
2858 </div>
2859
2860
2861 <div class='item'>
2862   <div class='type'><a name='origin-bucket'>[Function]</a></div>
2863   <div class='signature'>
2864     <code class='name'>origin-bucket</code>
2865     <span class='args'>
2866       <var>distribution</var>
2867     </span>
2868     <span class='result'>=> <var>origin-bucket</var></span>
2869   </div>
2870
2871   <blockquote class='description'>
2872     <p>Returns the origin bucket for <var>distribution</var>. It is
2873       different from a normal ZS3 bucket name, because it has
2874       ".s3.amazonaws.com" as a suffix.
2875   </blockquote>
2876 </div>
2877
2878
2879 <div class='item'>
2880   <div class='type'><a name='domain-name'>[Function]</a></div>
2881   <div class='signature'>
2882     <code class='name'>domain-name</code>
2883     <span class='args'>
2884       <var>distribution</var>
2885     </span>
2886     <span class='result'>=> <var>domain-name</var></span>
2887   </div>
2888
2889   <blockquote class='description'>
2890     <p>Returns the domain name through which CloudFront-enabled access
2891       to a resource may be made.
2892   </blockquote>
2893 </div>
2894
2895
2896 <div class='item'>
2897   <div class='type'><a name='cnames'>[Function]</a></div>
2898   <div class='signature'>
2899     <code class='name'>cnames</code>
2900     <span class='args'>
2901       <var>distribution</var>
2902     </span>
2903     <span class='result'>=> <var>cnames</var></span>
2904   </div>
2905
2906   <blockquote class='description'>
2907     Returns a list of CNAMEs associated with <var>distribution</var>.
2908   </blockquote>
2909 </div>
2910
2911
2912 <div class='item'>
2913   <div class='type'><a name='enabledp'>[Function]</a></div>
2914   <div class='signature'>
2915     <code class='name'>enabledp</code>
2916     <span class='args'>
2917       <var>distribution</var>
2918     </span>
2919     <span class='result'>=> <var>boolean</var></span>
2920   </div>
2921
2922   <blockquote class='description'>
2923     <p>Returns <i>true</i> if <var>distribution</var> is enabled, NIL
2924       otherwise.
2925   </blockquote>
2926 </div>
2927
2928
2929 <div class='item'>
2930   <div class='type'><a name='invalidate-paths'>[Function]</a></div>
2931   <div class='signature'>
2932     <code class='name'>invalidate-paths</code>
2933     <span class='args'>
2934       <var>distribution</var>
2935       <var>paths</var>
2936     </span>
2937     <span class='result'>=> <var>invalidation</var></span>
2938   </div>
2939
2940   <blockquote class='description'>
2941     <p>Initiates the invalidation of resources identified
2942       by <var>paths</var> in <var>distribution</var>. <var>paths</var>
2943       should consist of key names that correspond to objects in the
2944       distribution's S3 bucket.
2945
2946     <p>The <var>invalidation</var> object reports on the status of the
2947       invalidation request. It can be queried
2948       with <a href='#status'><tt>STATUS</tt></a> and refreshed
2949       with <a href='#refresh'><tt>REFRESH</tt></a>.
2950
2951 <pre class='code'>
2952 * <b>(invalidate-paths distribution '("/css/site.css" "/js/site.js"))</b>
2953 #&lt;INVALIDATION "I1HJC711OFAVKO" [InProgress]>
2954 * <b>(progn (sleep 300) (refresh *))</b>
2955 #&lt;INVALIDATION "I1HJC711OFAVKO" [Completed]>
2956 </pre>
2957   </blockquote>
2958 </div>
2959
2960
2961
2962
2963 <a name='references'><h2>References</h2></a>
2964
2965   <ul>
2966     <li> Amazon, <a href="http://aws.amazon.com/documentation/s3/">Amazon
2967    S3 Technical Documentation</a>
2968     <li> Amazon, <a href="http://aws.amazon.com/documentation/cloudfront/">Amazon CloudFront Technical Documentation</a>
2969   </ul>
2970
2971
2972
2973
2974 <a name='acknowledgements'><h2>Acknowledgements</h2>
2975
2976   <p>Several people on <a href='http://freenode.net/'>freenode</a>
2977     #lisp pointed out typos and glitches in this
2978     documentation. Special thanks to Bart "_3b" Botta for providing a
2979     detailed documentation review that pointed out glitches,
2980     omissions, and overly confusing passages.
2981
2982   <p>James Wright corrected a problem with computing the string to
2983     sign and URL encoding.
2984
2985 <a name='feedback'><h2>Feedback</h2></a>
2986
2987   <p>If you have any questions or comments about ZS3, please email
2988   me, <a href='mailto:xach@xach.com'>Zach Beane</a>
2989
2990   <p>For ZS3 announcements and development discussion, please see the
2991   <a href="http://groups.google.com/group/zs3-devel">zs3-devel</a>
2992   mailing list.
2993
2994   <p><i>2016-06-17</i>
2995
2996  <p class='copyright'>Copyright &copy; 2008-2016 Zachary Beane, All Rights Reserved
2997
2998
2999 </div>
3000 </body>
3001 </html>
3002