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.13, released on August 1st, 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>action</var>
 620       <var>prefix</var>
 621       <var>days</var>
 622       <var>date</var>
 623     </span>
 624     <span class='result'>=> <var>rule</var></span>
 625   </div>
 626
 627   <blockquote class='description'>
 628     <p>Creates a rule object suitable for passing
 629       to <a href='#setf-bucket-lifecycle'><tt>(SETF
 630           BUCKET-LIFECYCLE)</tt></a>.
 631
 632     <p><var>action</var> should be either <tt>:expire</tt> (the
 633     default) or <tt>:transition</tt>. For <tt>:expire</tt>, matching
 634     objects are deleted. For <tt>:transition</tt>, matching objects
 635     are transitioned to the GLACIER storage class. For more
 636     information about S3-to-Glacier object transition,
 637     see <a href="http://docs.amazonwebservices.com/AmazonS3/latest/dev/object-archival.html">Object
 638     Archival (Transition Objects to the Glacier Storage Class)</a> in
 639     the Amazon S3 Developer's Guide.
 640
 641     <p><var>prefix</var> is a string; all objects in a bucket with
 642         keys matching the prefix will be affected by the rule.
 643
 644     <p><var>days</var> is the number of days after which an object
 645     will be affected.
 646
 647     <p><var>date</var> is the date after which objects will be affected.
 648
 649     <p>Only one of <var>days</var> or <var>date</var> may be provided.
 650   </blockquote>
 651 </div>
 652
 653
 654
 655 <a name='querying-buckets'><h3>Querying Buckets</h3></a>
 656
 657 <p>S3 has a flexible interface for querying a bucket for information
 658   about its contents. ZS3 supports this interface via
 659   <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a>,
 660    <a href='#continue-bucket-query'><tt>CONTINUE-BUCKET-QUERY</tt></a>,
 661    and related functions.
 662
 663 <div class='item'>
 664   <div class='type'><a name='query-bucket'>[Function]</a></div>
 665   <div class='signature'>
 666     <code class='name'>query-bucket</code>
 667     <span class='args'>
 668       <var>bucket</var>
 669       <code class='llkw'>&amp;key</code>
 670       <var>prefix</var>
 671       <var>marker</var>
 672       <var>max-keys</var>
 673       <var>delimiter</var>
 674       <var>credentials</var>
 675     </span>
 676     <span class='result'>=> <var>response</var></span>
 677   </div>
 678
 679   <blockquote class='description'>
 680     <p>Query <var>bucket</var> for key information. Returns a response
 681     object that has the result of the query. Response attributes are
 682     accessible via
 683       <a href='#bucket-name'><tt>BUCKET-NAME</tt></a>,
 684       <a href='#prefix'><tt>PREFIX</tt></a>,
 685       <a href='#marker'><tt>MARKER</tt></a>,
 686       <a href='#delimiter'><tt>DELIMITER</tt></a>,
 687       <a href='#truncatedp'><tt>TRUNCATEDP</tt></a>,
 688       <a href='#keys'><tt>KEYS</tt></a>, and
 689       <a href='#common-prefixes'><tt>COMMON-PREFIXES</tt></a>.
 690
 691     <p>Amazon might return fewer key objects than actually match the
 692       query parameters, based on <var>max-keys</var> or the result
 693       limit of 1000 key objects. In that
 694       case, <a href='#truncatedp'><tt>TRUNCATEDP</tt></a>
 695       for <var>response</var> is <i>true</i>, and
 696       <a href='#continue-bucket-query'><tt>CONTINUE-BUCKET-QUERY</tt></a>
 697       can be used with <var>response</var> be used to get successive
 698       responses for the query parameters.
 699
 700     <p>When <var>prefix</var> is supplied, only key objects with names
 701       that start with <var>prefix</var> will be returned
 702       in <var>response</var>.
 703
 704     <p>When <var>marker</var> is supplied, only key objects with names
 705       occurring lexically after <var>marker</var> will be returned in
 706       <var>response</var>.
 707
 708     <p>When <var>max-keys</var> is supplied, it places an inclusive
 709       upper limit on the number of key objects returned
 710       in <var>response</var>. Note that Amazon currently limits
 711       responses to at most 1000 key objects even
 712       if <var>max-keys</var> is greater than 1000.
 713
 714     <p>When <var>delimiter</var> is supplied, key objects that have
 715       the delimiter string after <var>prefix</var> in their names are
 716       not returned in the <a href='#keys'><tt>KEYS</tt></a> attribute
 717       of the response, but are instead accumulated into the
 718       <a href='#common-prefixes'><tt>COMMON-PREFIXES</tt></a>
 719       attribute of the response. For example:
 720 <pre class='code'>
 721   * <b>(all-keys "zs3-demo")</b>
 722   => #(#&lt;KEY "a" 4>
 723        #&lt;KEY "b/1" 4>
 724        #&lt;KEY "b/2" 4>
 725        #&lt;KEY "b/3" 4>
 726        #&lt;KEY "c/10" 4>
 727        #&lt;KEY "c/20" 4>
 728        #&lt;KEY "c/30" 4>)
 729
 730   * <b>(setf *response* (query-bucket "zs3-demo" :delimiter "/"))</b>
 731   => #&lt;BUCKET-LISTING "zs3-demo">
 732
 733   * <b>(values (keys *response*) (common-prefixes *response*))</b>
 734   => #(#&lt;KEY "a" 4>),
 735      #("b/"
 736        "c/")
 737
 738   * <b>(setf *response* (query-bucket "zs3-demo" :delimiter "/" :prefix "b/"))</b>
 739   => #&lt;BUCKET-LISTING "zs3-demo">
 740
 741   * <b>(values (keys *response*) (common-prefixes *response*))</b>
 742   => #(#&lt;KEY "b/1" 4>
 743        #&lt;KEY "b/2" 4>
 744        #&lt;KEY "b/3" 4>),
 745      #()</pre>
 746
 747     <p>For more information about bucket queries,
 748     see <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTBucketGET.html">GET
 749     Bucket</a> in the Amazon S3 developer documentation.
 750
 751   </blockquote>
 752
 753 </div>
 754
 755
 756 <div class='item'>
 757   <div class='type'><a name='continue-bucket-query'>[Function]</a></div>
 758   <div class='signature'>
 759     <code class='name'>continue-bucket-query</code>
 760     <span class='args'>
 761       <var>response</var>
 762     </span>
 763     <span class='result'>=> <var>response</var></span>
 764   </div>
 765
 766   <blockquote class='description'>
 767     <p>If <var>response</var> is a truncated response from a previous
 768     call to
 769       <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a>,
 770       continue-bucket-query returns the result of resuming the query at the
 771       truncation point. When there are no more results,
 772       continue-bucket-query returns NIL.
 773   </blockquote>
 774 </div>
 775
 776 <div class='item'>
 777   <div class='type'><a name='bucket-name'>[Function]</a></div>
 778   <div class='signature'>
 779     <code class='name'>bucket-name</code>
 780     <span class='args'>
 781       <var>response</var>
 782     </span>
 783     <span class='result'>=> <var>name</var></span>
 784   </div>
 785
 786   <blockquote class='description'>
 787     <p>Returns the name of the bucket used in the call
 788       to <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> that
 789       produced <var>response</var>.
 790   </blockquote>
 791 </div>
 792
 793
 794
 795
 796 <div class='item'>
 797   <div class='type'><a name='keys'>[Function]</a></div>
 798   <div class='signature'>
 799     <code class='name'>keys</code>
 800     <span class='args'>
 801       <var>response</var>
 802     </span>
 803     <span class='result'>=> <var>keys-vector</var></span>
 804   </div>
 805
 806   <blockquote class='description'>
 807     <p>Returns the vector of key objects in <var>response</var>. Key
 808     object attributes are accessible via
 809       <a href='#name'><tt>NAME</tt></a>,
 810       <a href='#size'><tt>SIZE</tt></a>,
 811       <a href='#etag'><tt>ETAG</tt></a>,
 812       <a href='#last-modified'><tt>LAST-MODIFIED</tt></a>,
 813       and <a href='#owner'><tt>OWNER</tt></a>.
 814   </blockquote>
 815 </div>
 816
 817
 818 <div class='item'>
 819   <div class='type'><a name='common-prefixes'>[Function]</a></div>
 820   <div class='signature'>
 821     <code class='name'>common-prefixes</code>
 822     <span class='args'>
 823       <var>response</var>
 824     </span>
 825     <span class='result'>=> <var>prefix-vector</var></span>
 826   </div>
 827
 828   <blockquote class='description'>
 829     <p>Returns a vector of common prefix strings, based on the
 830       delimiter argument of
 831       the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
 832       produced <var>response</var>.
 833   </blockquote>
 834 </div>
 835
 836
 837 <div class='item'>
 838   <div class='type'><a name='prefix'>[Function]</a></div>
 839   <div class='signature'>
 840     <code class='name'>prefix</code>
 841     <span class='args'>
 842       <var>response</var>
 843     </span>
 844     <span class='result'>=> <var>prefix-string</var></span>
 845   </div>
 846
 847   <blockquote class='description'>
 848     <p>Returns the prefix given to
 849     the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
 850     produced <var>response</var>. If present, all keys
 851     in <var>response</var> have <var>prefix-string</var> as a prefix.
 852   </blockquote>
 853 </div>
 854
 855 <div class='item'>
 856   <div class='type'><a name='marker'>[Function]</a></div>
 857   <div class='signature'>
 858     <code class='name'>marker</code>
 859     <span class='args'>
 860       <var>response</var>
 861     </span>
 862     <span class='result'>=> <var>marker</var></span>
 863   </div>
 864
 865   <blockquote class='description'>
 866     <p>Returns the marker given to
 867       the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
 868       produced <var>response</var>. If present,
 869       it lexically precedes all key names in the response.
 870   </blockquote>
 871 </div>
 872
 873 <div class='item'>
 874   <div class='type'><a name='delimiter'>[Function]</a></div>
 875   <div class='signature'>
 876     <code class='name'>delimiter</code>
 877     <span class='args'>
 878       <var>response</var>
 879     </span>
 880     <span class='result'>=> <var>delimiter</var></span>
 881   </div>
 882
 883   <blockquote class='description'>
 884     <p>Returns the delimiter used in
 885       the <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> call that
 886       produced <var>response</var>.
 887   </blockquote>
 888 </div>
 889
 890
 891 <div class='item'>
 892   <div class='type'><a name='truncatedp'>[Function]</a></div>
 893   <div class='signature'>
 894     <code class='name'>truncatedp</code>
 895     <span class='args'>
 896       <var>response</var>
 897     </span>
 898     <span class='result'>=> <var>boolean</var></span>
 899   </div>
 900
 901   <blockquote class='description'>
 902     <p>Returns <i>true</i> if <var>response</var> is truncated; that
 903     is, if there is more data to retrieve for a
 904     given <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a>
 905     query. <a href='#continue-bucket-query'><tt>CONTINUE-BUCKET-QUERY</tt></a>
 906     may be used to fetch more data.
 907   </blockquote>
 908 </div>
 909
 910
 911 <div class='item'>
 912   <div class='type'><a name='last-modified'>[Function]</a></div>
 913   <div class='signature'>
 914     <code class='name'>last-modified</code>
 915     <span class='args'>
 916       <var>key-object</var>
 917     </span>
 918     <span class='result'>=> <var>universal-time</var></span>
 919   </div>
 920
 921   <blockquote class='description'>
 922     <p>Returns a universal time representing the last modified time
 923     of <var>key-object</var>.
 924   </blockquote>
 925 </div>
 926
 927
 928 <div class='item'>
 929   <div class='type'><a name='etag'>[Function]</a></div>
 930   <div class='signature'>
 931     <code class='name'>etag</code>
 932     <span class='args'>
 933       <var>key-object</var>
 934     </span>
 935     <span class='result'>=> <var>etag-string</var></span>
 936   </div>
 937
 938   <blockquote class='description'>
 939     <p>Returns the etag for <var>key-object</var>.
 940   </blockquote>
 941 </div>
 942
 943
 944 <div class='item'>
 945   <div class='type'><a name='size'>[Function]</a></div>
 946   <div class='signature'>
 947     <code class='name'>size</code>
 948     <span class='args'>
 949       <var>key-object</var>
 950     </span>
 951     <span class='result'>=> <var>size</var></span>
 952   </div>
 953
 954   <blockquote class='description'>
 955     <p>Returns the size, in octets, of <var>key-object</var>.
 956   </blockquote>
 957 </div>
 958
 959
 960 <div class='item'>
 961   <div class='type'><a name='owner'>[Function]</a></div>
 962   <div class='signature'>
 963     <code class='name'>owner</code>
 964     <span class='args'>
 965       <var>key-object</var>
 966     </span>
 967     <span class='result'>=> <var>owner</var></span>
 968   </div>
 969
 970   <blockquote class='description'>
 971       <p>Returns the owner of <var>key-object</var>, or NIL if no owner
 972       information is available.
 973   </blockquote>
 974 </div>
 975
 976
 977 <div class='item'>
 978   <div class='type'><a name='storage-class'>[Function]</a></div>
 979   <div class='signature'>
 980     <code class='name'>storage-class</code>
 981     <span class='args'>
 982       <var>key-object</var>
 983     </span>
 984     <span class='result'>=> <var>storage-class</var></span>
 985   </div>
 986
 987   <blockquote class='description'>
 988     <p>Returns the storage class of <var>key-object</var>.
 989   </blockquote>
 990 </div>
 991
 992
 993
 994
 995
 996 <a name='object-ops'><h3>Operations on Objects</h3></a>
 997
 998 <p>Objects are the stored binary data in S3. Every object is uniquely
 999   identified by a bucket/key pair. ZS3 has several functions for
1000   storing and fetching objects, and querying object attributes.
1001
1002 <div class='item'>
1003   <div class='type'><a name='get-object'>[Function]</a></div>
1004   <div class='signature'>
1005     <code class='name'>get-object</code>
1006     <span class='args'>
1007       <var>bucket</var>
1008       <var>key</var>
1009       <code class='llkw'>&amp;key</code>
1010       <var>output</var> <br>
1011       <var>start</var> <var>end</var> <br>
1012       <var>when-modified-since</var> <var>unless-modified-since</var> <br>
1013       <var>when-etag-matches</var> <var>unless-etag-matches</var> <br>
1014       <var>if-exists</var> <var>string-external-format</var>
1015       <var>credentials</var>
1016     </span>
1017     <span class='result'>=> <var>object</var></span>
1018   </div>
1019
1020   <blockquote class='description'>
1021     <p>Fetch the object referenced by <var>bucket</var>
1022     and <var>key</var>. The secondary value of all successful requests
1023     is an alist of <a href='http://weitz.de/drakma/'>Drakma</a>-style
1024     response HTTP headers.
1025
1026     <p>If <var>output</var> is <code class='kw'>:VECTOR</code> (the
1027     default), the object's octets are returned in a vector.
1028
1029     <p>If <var>output</var> is <code class='kw'>:STRING</code>, the
1030     object's octets are converted to a string using the encoding
1031     specified by <var>string-external-format</var>, which defaults
1032     to <code class='kw'>:UTF-8</code>. See <a href="http://weitz.de/flexi-streams/#external-formats">External
1033     formats</a> in the FLEXI-STREAMS documentation for supported
1034     values for the string external format. Note that, even
1035     when <var>output</var> is <code class='kw'>:STRING</code>, the
1036     start and end arguments operate on the object's underlying octets,
1037     not the string representation in a particular encoding. It's
1038     possible to produce a subsequence of the object's octets that are
1039     not valid in the desired encoding.
1040
1041     <p>If <var>output</var> is a string or pathname, the object's
1042     octets are saved to a file identified by the string or
1043     pathname. The <var>if-exists</var> argument is passed
1044     to <code>WITH-OPEN-FILE</code> to control the behavior when the
1045     output file already exists. It defaults
1046     to <code class='kw'>:SUPERSEDE</code>.
1047
1048     <p>If <var>output</var> is <code class='kw'>:STREAM</code>, a
1049     stream is returned from which the object's contents may be read.
1050
1051     <p><var>start</var> marks the first index fetched from the
1052     object's data. <var>end</var> specifies the index after the last
1053     octet fetched. If start is NIL, it defaults to 0. If end is nil,
1054     it defaults to the total length of the object. If
1055     both <var>start</var> and <var>end</var> are
1056     provided, <var>start</var> must be less than or equal
1057     to <var>end</var>.
1058
1059     <p><var>when-modified-since</var>
1060     and <var>unless-modified-since</var> are optional. If
1061     <var>when-modified-since</var> is provided, the result will be the normal
1062     object value if the object has been modified since the provided
1063     universal time, NIL otherwise. The logic is reversed for
1064     <var>unless-modified-since</var>.
1065
1066     <p><var>when-etag-matches</var> and <var>unless-etag-matches</var> are optional. If
1067     <var>when-etag-matches</var> is provided, the result will be the
1068     normal object value if the object's etag matches the provided
1069     string, NIL otherwise. The logic is reversed
1070     for <var>unless-etag-matches</var>.
1071
1072   </blockquote>
1073 </div>
1074
1075 <div class='item'>
1076   <div class='type'><a name='get-vector'>[Function]</a></div>
1077   <div class='signature'>
1078     <code class='name'>get-vector</code>
1079     <span class='args'>
1080       <var>bucket</var> <var>key</var>
1081       <code class='llkw'>&amp;key</code>
1082       <var>start</var> <var>end</var>
1083       <var>when-modified-since</var> <var>unless-modified-since</var>
1084       <var>when-etag-matches</var> <var>unless-etag-matches</var>
1085       <var>credentials</var>
1086     </span>
1087     <span class='result'>=> <var>vector</var></span>
1088   </div>
1089
1090   <blockquote class='description'>
1091     <p>get-vector is a convenience interface to <a href='#get-object'><tt>GET-OBJECT</tt></a>. It is equivalent
1092       to calling:
1093
1094 <pre class='code'>
1095   (get-object bucket key <b>:output :vector</b> ...)
1096 </pre>
1097   </blockquote>
1098 </div>
1099
1100 <div class='item'>
1101   <div class='type'><a name='get-string'>[Function]</a></div>
1102   <div class='signature'>
1103     <code class='name'>get-string</code>
1104     <span class='args'>
1105       <var>bucket</var> <var>key</var>
1106       <code class='llkw'>&amp;key</code>
1107       <var>external-format</var>
1108       <var>start</var> <var>end</var>
1109       <var>when-modified-since</var>
1110       <var>unless-modified-since</var>
1111       <var>when-etag-matches</var>
1112       <var>unless-etag-matches</var>
1113       <var>credentials</var>
1114     </span>
1115     <span class='result'>=> <var>string</var></span>
1116   </div>
1117
1118   <blockquote class='description'>
1119     get-string is a convenience interface
1120     to <a href='#get-object'><tt>GET-OBJECT</tt></a>. It is equivalent
1121     to calling:
1122
1123 <pre class='code'>
1124   (get-object bucket key <b>:output :string</b> :string-external-format external-format ...)
1125 </pre>
1126
1127   </blockquote>
1128 </div>
1129
1130 <div class='item'>
1131   <div class='type'><a name='get-file'>[Function]</a></div>
1132   <div class='signature'>
1133     <code class='name'>get-file</code>
1134     <span class='args'>
1135       <var>bucket</var> <var>key</var> <var>file</var>
1136       <code class='llkw'>&amp;key</code>
1137       <var>start</var> <var>end</var>
1138       <var>when-modified-since</var>
1139       <var>unless-modified-since</var>
1140       <var>when-etag-matches</var>
1141       <var>unless-etag-matches</var>
1142       <var>credentials</var>
1143     </span>
1144     <span class='result'>=> <var>pathname</var></span>
1145   </div>
1146
1147   <blockquote class='description'>
1148     <p>get-file is a convenience interface
1149       to <a href='#get-object'><tt>GET-OBJECT</tt></a>. It is
1150       equivalent to calling:
1151
1152 <pre class='code'>
1153   (get-object bucket key <b>:output file</b> ...)
1154 </pre>
1155
1156   </blockquote>
1157 </div>
1158
1159
1160 <div class='item'>
1161   <div class='type'><a name='put-object'>[Function]</a></div>
1162   <div class='signature'>
1163     <code class='name'>put-object</code>
1164     <span class='args'>
1165       <var>object</var> <var>bucket</var> <var>key</var>
1166       <code class='llkw'>&amp;key</code>
1167       <var>access-policy</var>
1168       <var>public</var>
1169       <var>metadata</var>
1170       <var>string-external-format</var>
1171       <var>cache-control</var>
1172       <var>content-encoding</var>
1173       <var>content-disposition</var>
1174       <var>content-type</var>
1175       <var>expires</var>
1176       <var>storage-class</var>
1177       <var>credentials</var>
1178     </span>
1179     <span class='result'>=> |</span>
1180   </div>
1181
1182   <blockquote class='description'>
1183     <p>Stores the octets of <var>object</var> in the location
1184     identified by <var>bucket</var> and <var>key</var>.
1185
1186     <p>If <i>object</i> is an octet vector, it is stored directly.
1187
1188     <p>If <i>object</i> is a string, it is converted to an octet
1189     vector using <i>string-external-format</i>, which defaults
1190     to <code class='kw'>:UTF-8</code>, then
1191     stored. See <a href="http://weitz.de/flexi-streams/#external-formats">External
1192     formats</a> in the FLEXI-STREAMS documentation for supported
1193     values for the string external format.
1194
1195     <p>If <i>object</i> is a pathname, its contents are loaded in
1196     memory as an octet vector and stored.
1197
1198     <p>If provided, <var>access-policy</var> should be one of the
1199     following:
1200
1201       <ul>
1202         <li> <code class='kw'>:PRIVATE</code> - object owner is
1203           granted <code class='kw'>:FULL-CONTROL</code>; this is the
1204           default behavior if no access policy is provided
1205         <li> <code class='kw'>:PUBLIC-READ</code> - all users,
1206           regardless of authentication, can read the object
1207         <li> <code class='kw'>:AUTHENTICATED-READ</code> -
1208           authenticated Amazon AWS users can read the object
1209       </ul>
1210
1211     <p>For more information about access policies,
1212       see <a href='http://docs.amazonwebservices.com/AmazonS3/2006-03-01/RESTAccessPolicy.html'>Canned
1213         Access Policies</a> in the Amazon S3 developer documentation.
1214
1215     <p>If <var>public</var> is <i>true</i>, it has the same effect as
1216       providing an <var>access-policy</var>
1217       of <code class='kw'>:PUBLIC-READ</code>. An error is signaled if
1218       both <var>public</var> and
1219       <var>access-policy</var> are provided.
1220
1221
1222     <p>If provided, <var>metadata</var> should be an alist of Amazon
1223     metadata to set on the object. When the object is fetched again,
1224     the metadata will be returned in HTTP headers prefixed with
1225     "x-amz-meta-".
1226
1227     <p>The <i>cache-control</i>, <i>content-encoding</i>, <i>content-disposition</i>,
1228     <i>content-type</i>, and <i>expires</i> values are all used to set
1229     HTTP properties of the object that are returned with subsequent
1230     GET or HEAD requests. If <i>content-type</i> is not set, it
1231     defaults to "binary/octet-stream". The others default to
1232     NIL. If <i>expires</i> is provided, it should be a universal time.
1233
1234     <p>If provided, <var>storage-class</var> should refer to one of
1235     the standard storage classes available for S3; currently the
1236     accepted values are the strings "STANDARD" and
1237     "REDUCED_REDUNDANCY". Using other values may trigger an API error
1238     from S3. For more information about reduced redundancy storage,
1239     see <a href="http://docs.amazonwebservices.com/AmazonS3/latest/dev/Introduction.html#RRS">Reduced
1240     Redundancy Storage</a> in the Developer Guide.
1241 </div>
1242
1243 <div class='item'>
1244   <div class='type'><a name='put-vector'>[Function]</a></div>
1245   <div class='signature'>
1246     <code class='name'>put-vector</code>
1247     <span class='args'>
1248       <var>vector</var>
1249       <var>bucket</var>
1250       <var>key</var> <code class='llkw'>&amp;key</code>
1251       <var>start</var> <var>end</var>
1252       <var>access-policy</var>
1253       <var>public</var> <var>metadata</var>
1254       <var>content-disposition</var>
1255       <var>content-encoding</var>
1256       <var>content-type</var>
1257       <var>expires</var>
1258       <var>storage-class</var>
1259       <var>credentials</var>
1260     </span>
1261     <span class='result'>=> |</span>
1262   </div>
1263
1264   <blockquote class='description'>
1265     <p>put-vector is a convenience interface
1266     to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It is similar
1267     to calling:
1268
1269 <pre class='code'>
1270   (put-object vector bucket key ...)
1271 </pre>
1272   </blockquote>
1273
1274   <p>If one of <var>start</var> or <var>end</var> is provided, they
1275     are used as bounding index designators on the string, and only a
1276     subsequence is used.
1277 </div>
1278
1279 <div class='item'>
1280   <div class='type'><a name='put-string'>[Function]</a></div>
1281   <div class='signature'>
1282     <code class='name'>put-string</code>
1283     <span class='args'>
1284       <var>string</var> <var>bucket</var> <var>key</var>
1285       <code class='llkw'>&amp;key</code>
1286       <var>start</var> <var>end</var>
1287       <var>external-format</var>
1288       <var>access-policy</var>
1289       <var>public</var> <var>metadata</var>
1290       <var>content-disposition</var>
1291       <var>content-encoding</var>
1292       <var>content-type</var>
1293       <var>expires</var>
1294       <var>storage-class</var>
1295       <var>credentials</var>
1296     </span>
1297     <span class='result'>=> |</span>
1298   </div>
1299
1300   <blockquote class='description'>
1301     <p>put-string is a convenience interface
1302 to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It is similar to
1303 calling:
1304
1305 <pre class='code'>
1306   (put-object string bucket key :string-external-format external-format ...)
1307 </pre>
1308   </blockquote>
1309
1310   <p>If one of <var>start</var> or end is <var>supplied</var>, they
1311     are used as bounding index designators on the string, and only a
1312     substring is used.
1313 </div>
1314
1315 <div class='item'>
1316   <div class='type'><a name='put-file'>[Function]</a></div>
1317   <div class='signature'>
1318     <code class='name'>put-file</code>
1319     <span class='args'>
1320       <var>file</var> <var>bucket</var> <var>key</var>
1321       <code class='llkw'>&amp;key</code>
1322       <var>start</var> <var>end</var>
1323       <var>access-policy</var>
1324       <var>public</var> <var>metadata</var>
1325       <var>content-disposition</var> <var>content-encoding</var> <var>content-type</var>
1326       <var>expires</var>
1327       <var>storage-class</var>
1328       <var>credentials</var>
1329     </span>
1330     <span class='result'>=> |</span>
1331   </div>
1332
1333   <blockquote class='description'>
1334     <p>put-file is a convenience interface
1335     to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It is almost
1336     equivalent to calling:
1337
1338 <pre class='code'>
1339   (put-object (pathname file) bucket key ...)
1340 </pre>
1341
1342     <p>If <var>key</var> is T, the <code>FILE-NAMESTRING</code> of
1343       the file is used as the key instead of <i>key</i>.
1344
1345     <p>If one of <var>start</var> or <var>end</var> is supplied, only
1346       a subset of the file is used. If <var>start</var> is not
1347       NIL, <var>start</var> octets starting from the beginning of the
1348       file are skipped. If <var>end</var> is not NIL, octets in the
1349       file at and after <var>end</var> are ignored. An error of type
1350       <tt>CL:END-OF-FILE</tt> is signaled if <var>end</var> is
1351       provided and the file size is less than <var>end</var>.
1352   </blockquote>
1353 </div>
1354
1355
1356 <div class='item'>
1357   <div class='type'><a name='put-stream'>[Function]</a></div>
1358   <div class='signature'>
1359     <code class='name'>put-stream</code>
1360     <span class='args'>
1361       <var>file</var> <var>bucket</var> <var>key</var>
1362       <code class='llkw'>&amp;key</code>
1363       <var>start</var> <var>end</var>
1364       <var>access-policy</var>
1365       <var>public</var> <var>metadata</var>
1366       <var>content-disposition</var> <var>content-encoding</var> <var>content-type</var>
1367       <var>expires</var>
1368       <var>storage-class</var>
1369       <var>credentials</var>
1370     </span>
1371     <span class='result'>=> |</span>
1372   </div>
1373
1374   <blockquote class='description'>
1375     <p>put-stream is similar to
1376     to <a href='#put-object'><tt>PUT-OBJECT</tt></a>. It has the same
1377     effect as collecting octets from <var>stream</var> into a vector
1378     and using:
1379
1380 <pre class='code'>
1381   (put-object vector bucket key ...)
1382 </pre>
1383
1384     <p>If <var>start</var> is not NIL, <var>start</var> octets
1385       starting from the current position in the stream are skipped
1386       before collecting.
1387
1388     <p>If <var>end</var> is NIL, octets are collected until the end of
1389       the stream is reached.
1390
1391     <p>If <var>end</var> is not NIL, collecting octets stops just
1392       before reaching <var>end</var> in the stream. An error of type
1393       <tt>CL:END-OF-FILE</tt> is signaled if the stream ends
1394       prematurely.
1395   </blockquote>
1396 </div>
1397
1398
1399 <div class='item'>
1400   <div class='type'><a name='copy-object'>[Function]</a></div>
1401   <div class='signature'>
1402     <code class='name'>copy-object</code>
1403     <span class='args'>
1404       <code class='llkw'>&amp;key</code>
1405       <var>from-bucket</var>
1406       <var>from-key</var>
1407       <var>to-bucket</var>
1408       <var>to-key</var> <br>
1409       <var>access-policy</var>
1410       <var>public</var> <br>
1411       <var>when-etag-matches</var>
1412       <var>unless-etag-matches</var> <br>
1413       <var>when-modified-since</var>
1414       <var>unless-modified-since</var> <br>
1415       <var>metadata</var> <var>public</var> <var>precondition-errors</var>
1416       <var>storage-class</var>
1417       <var>credentials</var>
1418     </span>
1419     <span class='result'>=> |</span>
1420   </div>
1421
1422   <blockquote class='description'>
1423     <p>Copies the object identified by <var>from-bucket</var>
1424     and <var>from-key</var> to a new location identified by
1425     <var>to-bucket</var> and <var>to-key</var>.
1426
1427     If <var>to-bucket</var> is NIL, <var>from-bucket</var> is used as
1428     the target. If <var>to-key</var> is nil, <var>from-key</var> is
1429     used as the target. An error is signaled if both <var>to-bucket</var> and
1430     <var>to-key</var> are NIL.
1431
1432     <p><var>access-policy</var> and <var>public</var> have the same
1433       effect on the target object as
1434       in <a href='#put-object'><tt>PUT-OBJECT</tt></a>.
1435
1436     <p>The precondition arguments <var>when-etag-matches</var>, <var>unless-etag-matches</var>,
1437     <var>when-modified-since</var>, and <var>unless-modified-since</var> work the same way they
1438     do in <a href='#get-object'><tt>GET-OBJECT</tt></a>, but with one difference: if <var>precondition-errors</var> is
1439     <i>true</i>, an <code>PRECONDITION-FAILED</code> error is signaled
1440     when a precondition does not hold, instead of returning NIL.
1441
1442     <p>If <var>metadata</var> is explicitly provided, it follows the
1443     same behavior as
1444     with <a href='#put-object'><tt>PUT-OBJECT</tt></a>. Passing NIL
1445     means that the new object has no metadata. Otherwise, the metadata
1446     is copied from the original object.
1447
1448     <p>If <var>storage-class</var> is provided, it should refer to one
1449     of the standard storage classes available for S3; currently the
1450     accepted values are the strings "STANDARD" and
1451     "REDUCED_REDUNDANCY". Using other values may trigger an API error
1452     from S3. For more information about reduced redundancy storage,
1453     see <a href="http://docs.amazonwebservices.com/AmazonS3/latest/dev/Introduction.html#RRS">Reduced
1454     Redundancy Storage</a> in the Developer Guide.
1455   </blockquote>
1456 </div>
1457
1458 <div class='item'>
1459   <div class='type'><a name='delete-object'>[Function]</a></div>
1460   <div class='signature'>
1461     <code class='name'>delete-object</code>
1462     <span class='args'>
1463       <var>bucket</var>
1464       <var>key</var>
1465       <code class='llkw'>&amp;key</code>
1466       <var>credentials</var>
1467     </span>
1468     <span class='result'>=> |</span>
1469   </div>
1470
1471   <blockquote class='description'>
1472     <p>Deletes the object identified by <var>bucket</var>
1473       and <var>key</var>.
1474     <p>If <var>bucket</var> is a valid bucket for
1475       which you have delete access granted, S3 will always return a success
1476       response, even if <var>key</var> does not reference an existing
1477       object.
1478   </blockquote>
1479 </div>
1480
1481 <div class='item'>
1482   <div class='type'><a name='delete-objects'>[Function]</a></div>
1483   <div class='signature'>
1484     <code class='name'>delete-objects</code>
1485     <span class='args'>
1486       <var>bucket</var>
1487       <var>keys</var>
1488       <code class='llkw'>&amp;key</code>
1489       <var>credentials</var>
1490     </span>
1491     <span class='result'>=> <var>deleted-count</var>, <var>errors</var></span>
1492   </div>
1493
1494   <blockquote class='description'>
1495     <p>Deletes <var>keys</var>, which should be a sequence of keys,
1496     from <var>bucket</var>. The primary value is the number of objects
1497     deleted. The secondary value is a list of error plists; if there
1498     are no errors deleting any of the keys, the secondary value is
1499     NIL.
1500   </blockquote>
1501 </div>
1502
1503 <div class='item'>
1504   <div class='type'><a name='delete-all-objects'>[Function]</a></div>
1505   <div class='signature'>
1506     <code class='name'>delete-all-objects</code>
1507     <span class='args'>
1508       <var>bucket</var>
1509       <code class='llkw'>&amp;key</code>
1510       <var>credentials</var>
1511     </span>
1512     <span class='result'>=> <var>count</var></span>
1513   </div>
1514
1515   <blockquote class='description'>
1516     <p>Deletes all objects in <var>bucket</var> and returns the count
1517       of objects deleted.
1518   </blockquote>
1519 </div>
1520
1521
1522 <div class='item'>
1523   <div class='type'><a name='object-metadata'>[Function]</a></div>
1524   <div class='signature'>
1525     <code class='name'>object-metadata</code>
1526     <span class='args'>
1527       <var>bucket</var>
1528       <var>key</var>
1529       <code class='llkw'>&amp;key</code>
1530       <var>credentials</var>
1531     </span>
1532     <span class='result'>=> <var>metadata-alist</var></span>
1533   </div>
1534
1535   <blockquote class='description'>
1536     <p>Returns the metadata for the object identified by <var>bucket</var> and <var>key</var>, or
1537     NIL if there is no metadata. For example:
1538
1539 <pre class='code'>
1540   * <b>(put-string "Hadjaha!" "zs3-demo" "hadjaha.txt" :metadata (parameters-alist :language "Swedish"))</b>
1541   => #&lt;RESPONSE 200 "OK" {1003BD2841}>
1542
1543   * <b>(object-metadata "zs3-demo" "hadjaha.txt")</b>
1544   => ((:LANGUAGE . "Swedish"))
1545 </pre>
1546
1547   </blockquote>
1548 </div>
1549
1550 <div class='item'>
1551   <div class='type'><a name='set-storage-class'>[Function]</a></div>
1552   <div class='signature'>
1553     <code class='name'>set-storage-class</code>
1554     <span class='args'>
1555       <var>bucket</var>
1556       <var>key</var>
1557       <var>storage-class</var>
1558       <code class='llkw'>&amp;key</code>
1559       <var>credentials</var>
1560     </span>
1561     <span class='result'>=> |</span>
1562   </div>
1563
1564   <blockquote class='description'>
1565     <p>Sets the storage class of the object identified
1566       by <var>bucket</var> and <var>key</var>
1567       to <var>storage-class</var>. This is a convenience function that
1568       uses <a href='#copy-object'><tt>COPY-OBJECT</tt></a> to make
1569       storage class changes.
1570
1571     <p>The storage class of an object can be determined by querying
1572       the bucket with <a href='#all-keys'><tt>ALL-KEYS</tt></a>
1573       or <a href='#query-bucket'><tt>QUERY-BUCKET</tt></a> and
1574       using <a href='#storage-class'><tt>STORAGE-CLASS</tt></a> on one
1575       of the resulting key objects.
1576   </blockquote>
1577 </div>
1578
1579
1580
1581 <a name='access-control'><h3>Access Control</h3></a>
1582
1583 <p>Each S3 resource has an associated access control list that is
1584   created automatically when the resource is created. The access
1585   control list specifies the resource owner and a list of permission
1586   grants.
1587
1588 <p>Grants consist of a permission and a grantee. The permission must
1589   be one of <code class='kw'>:READ</code>, <code class='kw'>:WRITE</code>,
1590   <code class='kw'>:READ-ACL</code>, <code class='kw'>:WRITE-ACL</code>,
1591   or <code class='kw'>:FULL-CONTROL</code>. The grantee should be a
1592   person object, an acl-group object, or an acl-email object.
1593
1594 <p>ZS3 has several functions that assist in reading, modifying, and
1595   storing access control lists.
1596
1597
1598 <div class='item'>
1599   <div class='type'><a name='get-acl'>[Function]</a></div>
1600   <div class='signature'>
1601     <code class='name'>get-acl</code>
1602     <span class='args'>
1603       <code class='llkw'>&amp;key</code>
1604       <var>bucket</var>
1605       <var>key</var>
1606       <var>credentials</var>
1607     </span>
1608     <span class='result'>=> <var>owner</var>, <var>grants</var></span>
1609   </div>
1610
1611   <blockquote class='description'>
1612     <p>Returns the owner and grant list for a resource as
1613     multiple values.
1614   </blockquote>
1615 </div>
1616
1617
1618 <div class='item'>
1619   <div class='type'><a name='put-acl'>[Function]</a></div>
1620   <div class='signature'>
1621     <code class='name'>put-acl</code>
1622     <span class='args'>
1623       <var>owner</var> <var>grants</var>
1624       <code class='llkw'>&amp;key</code>
1625       <var>bucket</var>
1626       <var>key</var>
1627       <var>credentials</var>
1628     </span>
1629     <span class='result'>=> |</span>
1630   </div>
1631
1632   <blockquote class='description'>
1633     <p>Sets the owner and grant list of a resource.
1634   </blockquote>
1635 </div>
1636
1637
1638 <div class='item'>
1639   <div class='type'><a name='grant'>[Function]</a></div>
1640   <div class='signature'>
1641     <code class='name'>grant</code>
1642     <span class='args'>
1643       <var>permission</var>
1644       <code class='llkw'>&amp;key</code>
1645       <var>to</var>
1646     </span>
1647     <span class='result'>=> <var>grant</var></span>
1648   </div>
1649
1650   <blockquote class='description'>
1651     <p>Returns a grant object that represents a permission (one of <code class='kw'>:READ</code>, <code class='kw'>:WRITE</code>,
1652       <code class='kw'>:READ-ACL</code>, <code class='kw'>:WRITE-ACL</code>,
1653       or <code class='kw'>:FULL-CONTROL</code>) for the
1654       grantee <var>to</var>. For example:
1655
1656 <pre class='code'>
1657   * <b>(grant :full-control :to (<a href='#acl-email'>acl-email</a> "bob@example.com"))</b>
1658   => #&lt;GRANT :FULL-CONTROL to "bob@example.com">
1659
1660   * <b>(grant :read :to <a href='#*all-users*'>*all-users*</a>)</b>
1661   => #&lt;GRANT :READ to "AllUsers">
1662 </pre>
1663
1664     <p>It can be used to create or modify a grant list for use
1665     with <a href='#put-acl'><tt>PUT-ACL</tt></a>.
1666   </blockquote>
1667 </div>
1668
1669
1670 <div class='item'>
1671   <div class='type'><a name='acl-eqv'>[Function]</a></div>
1672   <div class='signature'>
1673     <code class='name'>acl-eqv</code>
1674     <span class='args'>
1675       <var>a</var> <var>b</var>
1676     </span>
1677     <span class='result'>=> <var>boolean</var></span>
1678   </div>
1679
1680   <blockquote class='description'>
1681     <p>Returns <i>true</i> if <var>a</var> and <var>b</var> are equivalent
1682       ACL-related objects (person, group, email, or grant).
1683   </blockquote>
1684 </div>
1685
1686
1687 <div class='item'>
1688   <div class='type'><a name='*all-users*'>[Special variable]</a></div>
1689   <div class='signature'>
1690     <code class='name'>*all-users*</code>
1691   </div>
1692
1693   <blockquote class='description'>
1694     <p>This acl-group includes all users, including unauthenticated
1695     clients.
1696   </blockquote>
1697 </div>
1698
1699
1700 <div class='item'>
1701   <div class='type'><a name='*aws-users*'>[Special variable]</a></div>
1702   <div class='signature'>
1703     <code class='name'>*aws-users*</code>
1704   </div>
1705
1706   <blockquote class='description'>
1707     <p>This acl-group object includes only users that have an
1708     Amazon Web Services account.
1709   </blockquote>
1710 </div>
1711
1712
1713 <div class='item'>
1714   <div class='type'><a name='*log-delivery*'>[Special variable]</a></div>
1715   <div class='signature'>
1716     <code class='name'>*log-delivery*</code>
1717   </div>
1718
1719   <blockquote class='description'>
1720     <p>This acl-group object includes the S3 system user that creates
1721       logfile objects. See
1722       also <a href='#enable-logging-to'><tt>ENABLE-LOGGING-TO</tt></a>.
1723   </blockquote>
1724 </div>
1725
1726
1727 <div class='item'>
1728   <div class='type'><a name='acl-email'>[Function]</a></div>
1729   <div class='signature'>
1730     <code class='name'>acl-email</code>
1731     <span class='args'>
1732       <var>email-address</var>
1733     </span>
1734     <span class='result'>=> <var>acl-email</var></span>
1735   </div>
1736
1737   <blockquote class='description'>
1738     <p>Returns an acl-email object, which can be used as a grantee for
1739       <a href='#grant'><tt>GRANT</tt></a>.
1740   </blockquote>
1741 </div>
1742
1743
1744 <div class='item'>
1745   <div class='type'><a name='acl-person'>[Function]</a></div>
1746   <div class='signature'>
1747     <code class='name'>acl-person</code>
1748     <span class='args'>
1749       <var>id</var>
1750       <code class='llkw'>&amp;optional</code>
1751       <var>display-name</var>
1752     </span>
1753     <span class='result'>=> <var>acl-person</var></span>
1754   </div>
1755
1756   <blockquote class='description'>
1757     <p>Returns an acl-person object for use as a resource owner (for
1758       <a href='#put-acl'><tt>PUT-ACL</tt></a>) or as a grantee
1759       (for <a href='#grant'><tt>GRANT</tt></a>). <var>id</var> must be
1760       a string representing the person's Amazon AWS canonical ID; for
1761       information about getting the canonical ID, see
1762       the <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/S3_ACLs.html">Access
1763       Control Lists</a> in the Amazon S3 developer
1764       documentation. If <var>display-name</var> is provided, it is
1765       used only for printing the object in Lisp; it is ignored when
1766       passed to S3.
1767   </blockquote>
1768 </div>
1769
1770
1771 <div class='item'>
1772   <div class='type'><a name='me'>[Function]</a></div>
1773   <div class='signature'>
1774     <code class='name'>me</code>
1775     <span class='args'>
1776       <code class='llkw'>&amp;key</code>
1777       <var>credentials</var>
1778     </span>
1779     <span class='result'>=> <var>acl-person</var></span>
1780   </div>
1781
1782   <blockquote class='description'>
1783     <p>Returns the acl-person object associated with the current
1784       credentials.
1785
1786     <p>This data requires a S3 request, but the result is always the
1787     same per credentials and is cached.
1788   </blockquote>
1789 </div>
1790
1791
1792 <div class='item'>
1793   <div class='type'><a name='make-public'>[Function]</a></div>
1794   <div class='signature'>
1795     <code class='name'>make-public</code>
1796     <span class='args'>
1797       <code class='llkw'>&amp;key</code>
1798       <var>bucket</var>
1799       <var>key</var>
1800       <var>credentials</var>
1801     </span>
1802     <span class='result'>=> |</span>
1803   </div>
1804
1805   <blockquote class='description'>
1806     <p>Makes a resource publicly accessible, i.e. readable by
1807       the <a href='#*all-users*'><tt>*ALL-USERS*</tt></a> group.
1808   </blockquote>
1809 </div>
1810
1811
1812 <div class='item'>
1813   <div class='type'><a name='make-private'>[Function]</a></div>
1814   <div class='signature'>
1815     <code class='name'>make-private</code>
1816     <span class='args'>
1817       <code class='llkw'>&amp;key</code>
1818       <var>bucket</var>
1819       <var>key</var>
1820       <var>credentials</var>
1821     </span>
1822     <span class='result'>=> |</span>
1823   </div>
1824
1825   <blockquote class='description'>
1826     <p>Removes public access to a resource, i.e. removes all
1827       access grants for
1828       the <a href='#*all-users*'><tt>*ALL-USERS*</tt></a> group.
1829   </blockquote>
1830 </div>
1831
1832
1833
1834 <a name='access-logging'><h3>Access Logging</h3></a>
1835
1836 <p>S3 offers support for logging information about client
1837   requests. Logfile objects are delivered by a system user in
1838   the <a href='#*log-delivery*'><tt>*LOG-DELIVERY*</tt></a> group to a
1839   bucket of your choosing. For more information about S3 access
1840   logging and the logfile format, see
1841   the <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/ServerLogs.html">Server
1842   Access Logging</a> in the Amazon S3
1843   developer documentation.
1844
1845 <div class='item'>
1846   <div class='type'><a name='enable-logging-to'>[Function]</a></div>
1847   <div class='signature'>
1848     <code class='name'>enable-logging-to</code>
1849     <span class='args'>
1850       <var>bucket</var>
1851       <code class='llkw'>&amp;key</code>
1852       <var>credentials</var>
1853     </span>
1854     <span class='result'>=> |</span>
1855   </div>
1856
1857   <blockquote class='description'>
1858     Adds the necessary permission grants to <var>bucket</var> to allow
1859     S3 to write logfile objects into it.
1860   </blockquote>
1861 </div>
1862
1863
1864 <div class='item'>
1865   <div class='type'><a name='disable-logging-to'>[Function]</a></div>
1866   <div class='signature'>
1867     <code class='name'>disable-logging-to</code>
1868     <span class='args'>
1869       <var>bucket</var>
1870       <code class='llkw'>&amp;key</code>
1871       <var>credentials</var>
1872     </span>
1873     <span class='result'>=> |</span>
1874   </div>
1875
1876   <blockquote class='description'>
1877     <p>Changes the access control list of <var>bucket</var> to remove
1878     all grants for
1879     the <a href='#*log-delivery*'><tt>*LOG-DELIVERY*</tt></a> group.
1880   </blockquote>
1881 </div>
1882
1883
1884 <div class='item'>
1885   <div class='type'><a name='enable-logging'>[Function]</a></div>
1886   <div class='signature'>
1887     <code class='name'>enable-logging</code>
1888     <span class='args'>
1889       <var>bucket</var>
1890       <var>target-bucket</var>
1891       <var>target-prefix</var>
1892       <code class='llkw'>&amp;key</code>
1893       <var>target-grants</var>
1894       <var>credentials</var>
1895     </span>
1896     <span class='result'>=> |</span>
1897   </div>
1898
1899   <blockquote class='description'>
1900     <p>Enables logging of all requests
1901     involving <var>bucket</var>. Logfile objects are created in
1902       <var>target-bucket</var> and each logfile's key starts with
1903       <var>target-prefix</var>.
1904
1905     <p>When a new logfile is
1906       created, its list of access control grants is extended with
1907       <var>target-grants</var>, if any.
1908
1909     <p>If <var>target-bucket</var> does not have the necessary grants
1910     to allow logging, the grants are implicitly added by
1911     calling <a href='#enable-logging-to'><tt>ENABLE-LOGGING-TO</tt></a>.
1912   </blockquote>
1913 </div>
1914
1915
1916 <div class='item'>
1917   <div class='type'><a name='disable-logging'>[Function]</a></div>
1918   <div class='signature'>
1919     <code class='name'>disable-logging</code>
1920     <span class='args'>
1921       <var>bucket</var> <code class='llkw'>&amp;key</code> <var>credentials</var>
1922     </span>
1923     <span class='result'>=> |</span>
1924   </div>
1925
1926   <blockquote class='description'>
1927     Disables logging for <var>bucket</var>.
1928   </blockquote>
1929 </div>
1930
1931
1932 <div class='item'>
1933   <div class='type'><a name='logging-setup'>[Function]</a></div>
1934   <div class='signature'>
1935     <code class='name'>logging-setup</code>
1936     <span class='args'>
1937       <var>bucket</var>
1938       <code class='llkw'>&amp;key</code>
1939       <var>credentials</var>
1940     </span>
1941     <span class='result'>=> <var>target-bucket</var>,
1942       <var>target-prefix</var>,
1943       <var>target-grants</var></span>
1944   </div>
1945
1946   <blockquote class='description'>
1947     <p>If logging is enabled for <var>bucket</var>, returns the target
1948       bucket, target prefix, and target grants as multiple values.
1949   </blockquote>
1950 </div>
1951
1952
1953 <a name='misc'><h3>Miscellaneous Operations</h3></a>
1954
1955 <p>
1956
1957 <div class='item'>
1958   <div class='type'><a name='*use-ssl*'>[Special variable]</a></div>
1959   <div class='signature'>
1960     <code class='name'>*use-ssl*</code>
1961   </div>
1962
1963   <blockquote class='description'>
1964     <p>When <i>true</i>, requests to S3 are sent via HTTPS. The
1965       default is NIL.
1966   </blockquote>
1967 </div>
1968
1969
1970 <div class='item'>
1971   <div class='type'><a name='make-post-policy'>[Function]</a></div>
1972   <div class='signature'>
1973     <code class='name'>make-post-policy</code>
1974     <span class='args'>
1975       <code class='llkw'>&amp;key</code>
1976       <var>expires</var>
1977       <var>conditions</var>
1978       <var>credentials</var>
1979     </span>
1980     <span class='result'>=> <var>policy</var>, <var>signature</var></span>
1981   </div>
1982
1983   <blockquote class='description'>
1984     <p>Returns an encoded HTML POST form policy and its signature as
1985     multiple values. The policy can be used to conditionally allow any
1986     user to put objects into S3.
1987
1988     <p><var>expires</var> must be a universal time after which
1989     the policy is no longer accepted.
1990
1991     <p><var>conditions</var> must be a list of conditions that the
1992     posted form fields must satisfy. Each condition is a list of a
1993     condition keyword, a form field name, and the form field
1994     value. For example, the following are all valid conditions:
1995
1996     <p>
1997       <ul>
1998         <li> <code>(:starts-with "key" "uploads/")</code>
1999         <li> <code>(:eq "bucket" "user-uploads")</code>
2000         <li> <code>(:eq "acl" "public-read")</code>
2001         <li> <code>(:range "content-length-range" 1 10000)</code>
2002       </ul>
2003
2004     <p>These conditions are converted into a post policy description,
2005     base64-encoded, and returned as <var>policy</var>. The signature
2006     is returned as <var>signature</var>. These values can then be
2007     embedded in an HTML form and used to allow direct browser uploads.
2008
2009     <p>For example, if <var>policy</var> is
2010     "YSBwYXRlbnRseSBmYWtlIHBvbGljeQ==" and the policy signature is
2011     "ZmFrZSBzaWduYXR1cmU=", you could construct a form like this:
2012
2013 <p class='html'>
2014 &lt;form action="http://user-uploads.s3.amazonaws.com/" method="post" enctype="multipart/form-data"><br>
2015 &lt;input type="input" name="key" value="uploads/fun.jpg"><br>
2016 &lt;input type=hidden name="acl" value="public-read"><br>
2017 &lt;input type=hidden name="AWSAccessKeyId" value="8675309JGT9876430310"><br>
2018 &lt;input type=hidden name="Policy" value="YSBwYXRlbnRseSBmYWtlIHBvbGljeQ=="><br>
2019 &lt;input type=hidden name='Signature' value="ZmFrZSBzaWduYXR1cmU="><br>
2020 &lt;input name='file' type='file'><br>
2021 &lt;input type=submit value='Submit'><br>
2022 &lt;/form><br>
2023
2024    <p>For full, detailed documentation of browser-based POST uploads
2025    and policy documents,
2026    see <a href="http://docs.amazonwebservices.com/AmazonS3/2006-03-01/UsingHTTPPOST.html">Browser-Based
2027    Uploads Using POST</a> in the Amazon S3 developer documentation.
2028   </blockquote>
2029 </div>
2030
2031
2032 <div class='item'>
2033   <div class='type'><a name='head'>[Function]</a></div>
2034   <div class='signature'>
2035     <code class='name'>head</code>
2036     <span class='args'>
2037       <code class='llkw'>&amp;key</code>
2038       <var>bucket</var>
2039       <var>key</var>
2040       <var>parameters</var>
2041       <var>credentials</var>
2042     </span>
2043     <span class='result'>=> <var>headers-alist</var>,
2044       <var>status-code</var>,
2045       <var>phrase</var></span>
2046   </div>
2047
2048   <blockquote class='description'>
2049     <p>Submits a HTTP HEAD request for the resource identified by
2050       <var>bucket</var> and optionally <var>key</var>. Returns the
2051       <a href='http://weitz.de/drakma/'>Drakma</a> headers, HTTP
2052       status code, and HTTP phrase as multiple values.
2053
2054     <p>When <var>parameters</var> is supplied, it should be an alist
2055       of keys and values to pass as GET request parameters. For
2056       example:
2057
2058 <pre class='code'>
2059   * <b>(head :bucket "zs3-demo" :parameters (<a href='http://cliki.net/parameters-alist?download'>parameters-alist</a> :max-keys 0))</b>
2060   => ((:X-AMZ-ID-2  . "...")
2061       (:X-AMZ-REQUEST-ID . "...")
2062       (:DATE . "Sat, 27 Sep 2008 19:00:35 GMT")
2063       (:CONTENT-TYPE . "application/xml")
2064       (:TRANSFER-ENCODING . "chunked")
2065       (:SERVER . "AmazonS3")
2066       (:CONNECTION . "close")),
2067       200,
2068       "OK"</pre>
2069   </blockquote>
2070 </div>
2071
2072
2073 <div class='item'>
2074   <div class='type'><a name='authorized-url'>[Function]</a></div>
2075   <div class='signature'>
2076     <code class='name'>authorized-url</code>
2077     <span class='args'>
2078       <code class='llkw'>&amp;key</code>
2079       <var>bucket</var>
2080       <var>key</var>
2081       <var>vhost</var>
2082       <var>expires</var>
2083       <var>ssl</var>
2084       <var>sub-resource</var>
2085       <var>credentials</var>
2086     </span>
2087     <span class='result'>=> <var>url</var></span>
2088   </div>
2089
2090   <blockquote class='description'>
2091     <p>Creates an URL that allows temporary access to a resource regardless
2092     of its ACL.
2093
2094     <p>If neither <var>bucket</var> nor <var>key</var> is specified, the top-level bucket listing
2095     is accessible. If <var>key</var> is not specified, listing the keys of <var>bucket</var> is
2096     accessible. If both <var>bucket</var> and key are <var>specified</var>, the object specified
2097     by <var>bucket</var> and <var>key</var> is accessible.
2098
2099     <p><var>expires</var> is required, and should be the integer
2100     universal time after which the URL is no longer valid.
2101
2102     <p><var>vhost</var> controls the construction of the
2103     url. If <var>vhost</var> is nil, the constructed URL refers to the
2104     bucket, if present, as part of the path. If <var>vhost</var>
2105     is <code class='kw'>:AMAZON</code>, the bucket name is used as a
2106     prefix to the Amazon hostname. If <var>vhost</var>
2107     is <code class='kw'>:FULL</code>, the bucket name becomes the full
2108     hostname of the url. For example:
2109
2110 <pre class='code'>
2111   * <b>(authorized-url :bucket "foo" :key "bar" :vhost nil)</b>
2112   =&gt; "http://s3.amazonaws.com/foo/bar?..."
2113
2114   * <b>(authorized-url :bucket "foo" :key "bar" :vhost :amazon)</b>
2115   =&gt; "http://foo.s3.amazonaws.com/bar?..."
2116
2117   * <b>(authorized-url :bucket "foo.example.com" :key "bar" :vhost :full)</b>
2118   =&gt;  "http://foo.example.com/bar?..."
2119 </pre>
2120
2121     <p>If <i>ssl</i> is <i>true</i>, the URL has "https" as the scheme,
2122     otherwise it has "http".
2123
2124     <p>If <i>sub-resource</i> is specified, it is used as part of the
2125     query string to access a specific sub-resource. Example Amazon
2126     sub-resources include "acl" for access to the ACL, "location" for
2127     location information, and "logging" for logging information. For
2128     more information about the various sub-resources, see the Amazon
2129     S3 developer documentation.
2130   </blockquote>
2131 </div>
2132
2133
2134 <div class='item'>
2135   <div class='type'><a name='resource-url'>[Function]</a></div>
2136   <div class='signature'>
2137     <code class='name'>resource-url</code>
2138     <span class='args'>
2139       <code class='llkw'>&amp;key</code>
2140       <var>bucket</var>
2141       <var>key</var>
2142       <var>vhost</var>
2143       <var>ssl</var>
2144       <var>sub-resource</var>
2145     </span>
2146     <span class='result'>=> <var>url</var></span>
2147   </div>
2148
2149   <blockquote class='description'>
2150     <p>Returns an URL that can be used to reference a resource. See
2151       <a href='#authorized-url'><tt>AUTHORIZED-URL</tt></a> for more
2152       info.
2153   </blockquote>
2154 </div>
2155
2156
2157 <a name='utility'><h3>Utility Functions</h3></a>
2158
2159 <p>
2160
2161 <div class='item'>
2162   <div class='type'><a name='octet-vector'>[Function]</a></div>
2163   <div class='signature'>
2164     <code class='name'>octet-vector</code>
2165     <span class='args'>
2166       <code class='llkw'>&amp;rest</code>
2167       <var>octets</var>
2168     </span>
2169     <span class='result'>=> <var>octet-vector</var></span>
2170   </div>
2171
2172   <blockquote class='description'>
2173     <p>Returns a vector of type
2174       <code>(simple-array&nbsp;(unsigned-byte&nbsp;8)&nbsp;(*))</code> initialized with <var>octets</var>.
2175   </blockquote>
2176 </div>
2177
2178
2179 <div class='item'>
2180   <div class='type'><a name='now+'>[Function]</a></div>
2181   <div class='signature'>
2182     <code class='name'>now+</code>
2183     <span class='args'>
2184       <var>delta</var>
2185     </span>
2186     <span class='result'>=> <var>universal-time</var></span>
2187   </div>
2188
2189   <blockquote class='description'>
2190     <p>Returns a universal time that represents the current time
2191       incremented by <var>delta</var> seconds. It's useful for passing
2192       as the <code class='kw'>:EXPIRES</code> parameter to functions
2193       like <a href='#put-object'><tt>PUT-OBJECT</tt></a>
2194       and <a href='#authorized-url'><tt>AUTHORIZED-URL</tt></a>.
2195   </blockquote>
2196 </div>
2197
2198
2199 <div class='item'>
2200   <div class='type'><a name='now-'>[Function]</a></div>
2201   <div class='signature'>
2202     <code class='name'>now-</code>
2203     <span class='args'>
2204       <var>delta</var>
2205     </span>
2206     <span class='result'>=> <var>universal-time</var></span>
2207   </div>
2208
2209   <blockquote class='description'>
2210     <p>Like <a href='#now+'><tt>NOW+</tt></a>, but decrements the
2211       current time instead of incrementing it.
2212   </blockquote>
2213 </div>
2214
2215
2216 <div class='item'>
2217   <div class='type'><a name='file-etag'>[Function]</a></div>
2218   <div class='signature'>
2219     <code class='name'>file-etag</code>
2220     <span class='args'>
2221       <var>pathname</var>
2222     </span>
2223     <span class='result'>=> <var>etag</var></span>
2224   </div>
2225
2226   <blockquote class='description'>
2227     <p>Returns the etag of <var>pathname</var>. This can be useful for the
2228       conditional arguments
2229       <code class='kw'>:WHEN-ETAG-MATCHES</code> and
2230       <code class='kw'>:UNLESS-ETAG-MATCHES</code>
2231       in <a href='#get-object'><tt>GET-OBJECT</tt></a>
2232       and <a href='#copy-object'><tt>COPY-OBJECT</tt></a>.
2233   </blockquote>
2234 </div>
2235
2236
2237 <div class='item'>
2238   <div class='type'><a name='parameters-alist'>[Function]</a></div>
2239   <div class='signature'>
2240     <code class='name'>parameters-alist</code>
2241     <span class='args'>
2242       <code class='llkw'>&amp;rest</code>
2243       <var>parameters</var>
2244       <code class='llkw'>&amp;key</code>
2245       <code class='llkw'>&amp;allow-other-keys</code>
2246     </span>
2247     <span class='result'>=> <var>alist</var></span>
2248   </div>
2249
2250   <blockquote class='description'>
2251     <p>Returns an alist based on all keyword arguments passed to the
2252       function. Keywords are converted to their lowercase symbol name and
2253       values are converted to strings. For example:
2254
2255 <pre class='code'>
2256   * <b>(parameters-alist :name "Bob" :age 21)</b>
2257   => (("name" . "Bob") ("age" . "21"))
2258 </pre>
2259
2260     <p>This can be used to construct Amazon metadata alists
2261     for <a href='#put-object'><tt>PUT-OBJECT</tt></a>
2262     and <a href='#copy-object'><tt>COPY-OBJECT</tt></a>, or request
2263     parameters in <a href='#head'><tt>HEAD</tt></a>.
2264
2265   </blockquote>
2266 </div>
2267
2268
2269
2270 <div class='item'>
2271   <div class='type'><a name='clear-redirects'>[Function]</a></div>
2272   <div class='signature'>
2273     <code class='name'>clear-redirects</code>
2274     <span class='args'>
2275     </span>
2276     <span class='result'>=> |</span>
2277   </div>
2278
2279   <blockquote class='description'>
2280     <p>Clear ZS3's internal cache of redirections.
2281
2282     <p>Most ZS3 requests are submitted against the Amazon S3 endpoint
2283       "s3.amazonaws.com". Some requests, however, are permanently
2284       redirected by S3 to new endpoints. ZS3 maintains an internal cache
2285       of permanent redirects, but it's possible for that cache to get
2286       out of sync if external processes alter the bucket structure
2287
2288     <p>For example, if the bucket "eu.zs3" is created with a EU
2289       location constraint, S3 will respond to requests to that bucket
2290       with a permanent redirect to "eu.zs3.s3.amazonaws.com", and ZS3
2291       will cache that redirect information. But if the bucket is
2292       deleted and recreated by a third party, the redirect might no
2293       longer be necessary.
2294   </blockquote>
2295 </div>
2296
2297
2298 <a name='cloudfront'><h2>CloudFront</h2>
2299
2300 <p>CloudFront functions allow the creation and manipulation of
2301   distributions. In ZS3, distributions are represented by objects that
2302   reflect the state of a distributon at some point in time. It's
2303   possible for the distribution to change behind the scenes without
2304   notice, e.g. when a distribution's <a href='#status'>status</a> is
2305   updated from "InProgress" to "Deployed".
2306
2307   <p>The
2308   functions <a href='#enable'><tt>ENABLE</tt></a>, <a href='#disable'><tt>DISABLE</tt></a>, <a href='#ensure-cname'><tt>ENSURE-CNAME</tt></a>,
2309   <a href='#remove-cname'><tt>REMOVE-CNAME</tt></a>,
2310   and <a href='#set-comment'><tt>SET-COMMENT</tt></a> are designed so
2311   that regardless of the state of the distribution provided, after the
2312   function completes, the new state of the distribution will reflect
2313   the desired update. The
2314   functions <a href='#status'><tt>STATUS</tt></a>, <a href='#cnames'><tt>CNAMES</tt></a>,
2315   and
2316   <a href='#enabledp'><tt>ENABLEDP</tt></a> do not automatically
2317   refresh the object and therefore might reflect outdated
2318   information. To ensure the object has the most recent information,
2319   use <a href='#refresh'><tt>REFRESH</tt></a>. For example, to fetch
2320   the current, live status, use <tt>(status (refresh
2321   distribution))</tt>.
2322
2323
2324
2325 <div class='item'>
2326   <div class='type'><a name='all-distributions'>[Function]</a></div>
2327   <div class='signature'>
2328     <code class='name'>all-distributions</code>
2329     <span class='args'>
2330     </span>
2331     <span class='result'>=> |</span>
2332   </div>
2333
2334   <blockquote class='description'>
2335     <p>Returns a list of all distributions.
2336   </blockquote>
2337 </div>
2338
2339 <div class='item'>
2340   <div class='type'><a name='create-distribution'>[Function]</a></div>
2341   <div class='signature'>
2342     <code class='name'>create-distribution</code>
2343     <span class='args'>
2344       <var>bucket-name</var>
2345       <code class='llkw'>&amp;key</code>
2346       <var>cnames</var>
2347       <var>enabled</var>
2348       <var>comment</var>
2349     </span>
2350     <span class='result'>=> <var>distribution</var></span>
2351   </div>
2352
2353   <blockquote class='description'>
2354     Creates and returns a new distribution object that will cache
2355     objects from the bucket named
2356     by <var>bucket-name</var>.
2357
2358     <p>If <var>cnames</var> is provided, it is taken as a designator
2359     for a list of additional domain names that can be used to access
2360     the distribution.
2361
2362     <p>If <var>enabled</var> is NIL, the distribution is initially
2363       created in a disabled state. The default value is is T.
2364
2365     <p>If <var>comment</var> is provided, it becomes part of the newly
2366       created distribution.
2367   </blockquote>
2368 </div>
2369
2370 <div class='item'>
2371   <div class='type'><a name='delete-distribution'>[Function]</a></div>
2372   <div class='signature'>
2373     <code class='name'>delete-distribution</code>
2374     <span class='args'>
2375       <var>distribution</var>
2376     </span>
2377     <span class='result'>=> |</span>
2378   </div>
2379
2380   <blockquote class='description'>
2381     <p>Deletes <var>distribution</var>. Distributions must be disabled
2382       before deletion; see <a href='#disable'><tt>DISABLE</tt></a>.
2383   </blockquote>
2384 </div>
2385
2386
2387 <div class='item'>
2388   <div class='type'><a name='refresh'>[Function]</a></div>
2389   <div class='signature'>
2390     <code class='name'>refresh</code>
2391     <span class='args'>
2392       <var>distribution</var>
2393     </span>
2394     <span class='result'>=> <var>distribution</var></span>
2395   </div>
2396
2397   <blockquote class='description'>
2398     <p>Queries Amazon for the latest information
2399     regarding <var>distribution</var> and destructively modifies the
2400     instance with the new information. Returns its argument.
2401   </blockquote>
2402 </div>
2403
2404
2405 <div class='item'>
2406   <div class='type'><a name='enable'>[Function]</a></div>
2407   <div class='signature'>
2408     <code class='name'>enable</code>
2409     <span class='args'>
2410       <var>distribution</var>
2411     </span>
2412     <span class='result'>=> |</span>
2413   </div>
2414
2415   <blockquote class='description'>
2416     <p>Enables <var>distribution</var>.
2417   </blockquote>
2418 </div>
2419
2420
2421 <div class='item'>
2422   <div class='type'><a name='disable'>[Function]</a></div>
2423   <div class='signature'>
2424     <code class='name'>disable</code>
2425     <span class='args'>
2426       <var>distribution</var>
2427     </span>
2428     <span class='result'>=> |</span>
2429   </div>
2430
2431   <blockquote class='description'>
2432     <p>Disables <var>distribution</var>.
2433   </blockquote>
2434 </div>
2435
2436
2437 <div class='item'>
2438   <div class='type'><a name='ensure-cname'>[Function]</a></div>
2439   <div class='signature'>
2440     <code class='name'>ensure-cname</code>
2441     <span class='args'>
2442       <var>distribution</var>
2443       <var>cname</var>
2444     </span>
2445     <span class='result'>=> |</span>
2446   </div>
2447
2448   <blockquote class='description'>
2449     <p>Adds <var>cname</var> to the CNAMEs of <var>distribution</var>,
2450       if necessary.
2451   </blockquote>
2452 </div>
2453
2454 <div class='item'>
2455   <div class='type'><a name='remove-cname'>[Function]</a></div>
2456   <div class='signature'>
2457     <code class='name'>remove-cname</code>
2458     <span class='args'>
2459       <var>distribution</var>
2460       <var>cname</var>
2461     </span>
2462     <span class='result'>=> |</span>
2463   </div>
2464
2465   <blockquote class='description'>
2466     <p>Removes <var>cname</var> from the CNAMEs of <var>distribution</var>.
2467   </blockquote>
2468 </div>
2469
2470
2471 <div class='item'>
2472   <div class='type'><a name='set-comment'>[Function]</a></div>
2473   <div class='signature'>
2474     <code class='name'>set-comment</code>
2475     <span class='args'>
2476       <var>distribution</var>
2477       <var>comment</var>
2478     </span>
2479     <span class='result'>=> |</span>
2480   </div>
2481
2482   <blockquote class='description'>
2483     <p>Sets the comment of <var>distribution</var> to <var>comment</var>.
2484   </blockquote>
2485 </div>
2486
2487
2488 <div class='item'>
2489   <div class='type'><a name='distributions-for-bucket'>[Function]</a></div>
2490   <div class='signature'>
2491     <code class='name'>distributions-for-bucket</code>
2492     <span class='args'>
2493       <var>bucket-name</var>
2494     </span>
2495     <span class='result'>=> |</span>
2496   </div>
2497
2498   <blockquote class='description'>
2499     <p>Returns a list of distributions that
2500       have <var>bucket-name</var> as the origin bucket.
2501   </blockquote>
2502 </div>
2503
2504
2505 <div class='item'>
2506   <div class='type'><a name='distribution-error'>[Condition]</a></div>
2507   <div class='signature'>
2508     <code class='name'>distribution-error</code>
2509   </div>
2510
2511   <blockquote class='description'>
2512     <p>All errors signaled as a result of a CloudFront request error
2513       are subtypes of <tt>distribution-error</tt>.
2514   </blockquote>
2515 </div>
2516
2517
2518 <div class='item'>
2519   <div class='type'><a name='distribution-not-disabled'>[Condition]</a></div>
2520   <div class='signature'>
2521     <code class='name'>distribution-not-disabled</code>
2522   </div>
2523
2524   <blockquote class='description'>
2525     <p>Distributions must be fully disabled before they are
2526       deleted. If they have not been disabled, or the status of the
2527       distribution is still
2528       "InProgress", <tt>distribution-not-disabled</tt> is signaled.
2529   </blockquote>
2530 </div>
2531
2532
2533 <div class='item'>
2534   <div class='type'><a name='cname-already-exists'>[Condition]</a></div>
2535   <div class='signature'>
2536     <code class='name'>cname-already-exists</code>
2537   </div>
2538
2539   <blockquote class='description'>
2540     <p>A CNAME may only appear on one distribution. If you attempt to
2541       add a CNAME to a distribution that is already present on some
2542       other distribution, <tt>cname-already-exists</tt> is signaled.
2543   </blockquote>
2544 </div>
2545
2546
2547 <div class='item'>
2548   <div class='type'><a name='too-many-distributions'>[Condition]</a></div>
2549   <div class='signature'>
2550     <code class='name'>too-many-distributions</code>
2551   </div>
2552
2553   <blockquote class='description'>
2554     <p>If creating a new distribution
2555       via <a href='#create-distribution'><tt>CREATE-DISTRIBUTION</tt></a>
2556       would exceed the account limit of total distributions,
2557       <tt>too-many-distributions</tt> is signaled.
2558   </blockquote>
2559 </div>
2560
2561
2562 <div class='item'>
2563   <div class='type'><a name='status'>[Function]</a></div>
2564   <div class='signature'>
2565     <code class='name'>status</code>
2566     <span class='args'>
2567       <var>distribution</var>
2568     </span>
2569     <span class='result'>=> <var>status</var></span>
2570   </div>
2571
2572   <blockquote class='description'>
2573     <p>Returns a string describing the status
2574       of <var>distribution</var>. The status is either "InProgress",
2575       meaning that the distribution's configuration has not fully
2576       propagated through the CloudFront system, or "Deployed".
2577   </blockquote>
2578 </div>
2579
2580
2581 <div class='item'>
2582   <div class='type'><a name='origin-bucket'>[Function]</a></div>
2583   <div class='signature'>
2584     <code class='name'>origin-bucket</code>
2585     <span class='args'>
2586       <var>distribution</var>
2587     </span>
2588     <span class='result'>=> <var>origin-bucket</var></span>
2589   </div>
2590
2591   <blockquote class='description'>
2592     <p>Returns the origin bucket for <var>distribution</var>. It is
2593       different from a normal ZS3 bucket name, because it has
2594       ".s3.amazonaws.com" as a suffix.
2595   </blockquote>
2596 </div>
2597
2598
2599 <div class='item'>
2600   <div class='type'><a name='domain-name'>[Function]</a></div>
2601   <div class='signature'>
2602     <code class='name'>domain-name</code>
2603     <span class='args'>
2604       <var>distribution</var>
2605     </span>
2606     <span class='result'>=> <var>domain-name</var></span>
2607   </div>
2608
2609   <blockquote class='description'>
2610     <p>Returns the domain name through which CloudFront-enabled access
2611       to a resource may be made.
2612   </blockquote>
2613 </div>
2614
2615
2616 <div class='item'>
2617   <div class='type'><a name='cnames'>[Function]</a></div>
2618   <div class='signature'>
2619     <code class='name'>cnames</code>
2620     <span class='args'>
2621       <var>distribution</var>
2622     </span>
2623     <span class='result'>=> <var>cnames</var></span>
2624   </div>
2625
2626   <blockquote class='description'>
2627     Returns a list of CNAMEs associated with <var>distribution</var>.
2628   </blockquote>
2629 </div>
2630
2631
2632 <div class='item'>
2633   <div class='type'><a name='enabledp'>[Function]</a></div>
2634   <div class='signature'>
2635     <code class='name'>enabledp</code>
2636     <span class='args'>
2637       <var>distribution</var>
2638     </span>
2639     <span class='result'>=> <var>boolean</var></span>
2640   </div>
2641
2642   <blockquote class='description'>
2643     <p>Returns <i>true</i> if <var>distribution</var> is enabled, NIL
2644       otherwise.
2645   </blockquote>
2646 </div>
2647
2648
2649 <div class='item'>
2650   <div class='type'><a name='invalidate-paths'>[Function]</a></div>
2651   <div class='signature'>
2652     <code class='name'>invalidate-paths</code>
2653     <span class='args'>
2654       <var>distribution</var>
2655       <var>paths</var>
2656     </span>
2657     <span class='result'>=> <var>invalidation</var></span>
2658   </div>
2659
2660   <blockquote class='description'>
2661     <p>Initiates the invalidation of resources identified
2662       by <var>paths</var> in <var>distribution</var>. <var>paths</var>
2663       should consist of key names that correspond to objects in the
2664       distribution's S3 bucket.
2665
2666     <p>The <var>invalidation</var> object reports on the status of the
2667       invalidation request. It can be queried
2668       with <a href='#status'><tt>STATUS</tt></a> and refreshed
2669       with <a href='#refresh'><tt>REFRESH</tt></a>.
2670
2671 <pre class='code'>
2672 * <b>(invalidate-paths distribution '("/css/site.css" "/js/site.js"))</b>
2673 #&lt;INVALIDATION "I1HJC711OFAVKO" [InProgress]>
2674 * <b>(progn (sleep 300) (refresh *))</b>
2675 #&lt;INVALIDATION "I1HJC711OFAVKO" [Completed]>
2676 </pre>
2677   </blockquote>
2678 </div>
2679
2680
2681
2682
2683 <a name='references'><h2>References</h2></a>
2684
2685   <ul>
2686     <li> Amazon, <a href="http://developer.amazonwebservices.com/connect/entry.jspa?externalID=123&categoryID=48">Amazon
2687    S3 Technical Documentation</a>
2688     <li> Amazon, <a href="http://developer.amazonwebservices.com/connect/entry.jspa?externalID=1876&categoryID=213">Amazon CloudFront Technical Documentation</a>
2689   </ul>
2690
2691
2692
2693
2694 <a name='acknowledgements'><h2>Acknowledgements</h2>
2695
2696   <p>Several people on <a href='http://freenode.net/'>freenode</a>
2697     #lisp pointed out typos and glitches in this
2698     documentation. Special thanks to Bart "_3b" Botta for providing a
2699     detailed documentation review that pointed out glitches,
2700     omissions, and overly confusing passages.
2701
2702   <p>James Wright corrected a problem with computing the string to
2703     sign and URL encoding.
2704
2705 <a name='feedback'><h2>Feedback</h2></a>
2706
2707   <p>If you have any questions or comments about ZS3, please email
2708   me, <a href='mailto:xach@xach.com'>Zach Beane</a>
2709
2710   <p>For ZS3 announcements and development discussion, please see the
2711   <a href="http://groups.google.com/group/zs3-devel">zs3-devel</a>
2712   mailing list.
2713
2714   <p><i>2010-09-03</i>
2715
2716  <p class='copyright'>Copyright &copy; 2008-2010 Zachary Beane, All Rights Reserved
2717
2718
2719 </div>
2720 </body>
2721 </html>
2722