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