doc/index.html

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