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