doc/index.html

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