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