{
    "mode": "perldoc",
    "parameter": "Amazon::S3",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Amazon%3A%3AS3/json",
    "generated": "2026-06-12T07:22:43Z",
    "synopsis": "#!/usr/bin/perl\nuse warnings;\nuse strict;\nuse Amazon::S3;\nuse vars qw/$OWNERID $OWNERDISPLAYNAME/;\nmy $awsaccesskeyid     = \"Fill me in!\";\nmy $awssecretaccesskey = \"Fill me in too!\";\nmy $s3 = Amazon::S3->new(\n{   awsaccesskeyid     => $awsaccesskeyid,\nawssecretaccesskey => $awssecretaccesskey,\nretry                 => 1\n}\n);\nmy $response = $s3->buckets;\n# create a bucket\nmy $bucketname = $awsaccesskeyid . '-net-amazon-s3-test';\nmy $bucket = $s3->addbucket( { bucket => $bucketname } )\nor die $s3->err . \": \" . $s3->errstr;\n# store a key with a content-type and some optional metadata\nmy $keyname = 'testing.txt';\nmy $value   = 'T';\n$bucket->addkey(\n$keyname, $value,\n{   contenttype        => 'text/plain',\n'x-amz-meta-colour' => 'orange',\n}\n);\n# list keys in the bucket\n$response = $bucket->list\nor die $s3->err . \": \" . $s3->errstr;\nprint $response->{bucket}.\"\\n\";\nfor my $key (@{ $response->{keys} }) {\nprint \"\\t\".$key->{key}.\"\\n\";\n}\n# delete key from bucket\n$bucket->deletekey($keyname);\n# delete bucket\n$bucket->deletebucket;",
    "sections": {
        "NAME": {
            "content": "Amazon::S3 - A portable client library for working with and managing Amazon S3 buckets and keys.\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "#!/usr/bin/perl\nuse warnings;\nuse strict;\n\nuse Amazon::S3;\n\nuse vars qw/$OWNERID $OWNERDISPLAYNAME/;\n\nmy $awsaccesskeyid     = \"Fill me in!\";\nmy $awssecretaccesskey = \"Fill me in too!\";\n\nmy $s3 = Amazon::S3->new(\n{   awsaccesskeyid     => $awsaccesskeyid,\nawssecretaccesskey => $awssecretaccesskey,\nretry                 => 1\n}\n);\n\nmy $response = $s3->buckets;\n\n# create a bucket\nmy $bucketname = $awsaccesskeyid . '-net-amazon-s3-test';\nmy $bucket = $s3->addbucket( { bucket => $bucketname } )\nor die $s3->err . \": \" . $s3->errstr;\n\n# store a key with a content-type and some optional metadata\nmy $keyname = 'testing.txt';\nmy $value   = 'T';\n$bucket->addkey(\n$keyname, $value,\n{   contenttype        => 'text/plain',\n'x-amz-meta-colour' => 'orange',\n}\n);\n\n# list keys in the bucket\n$response = $bucket->list\nor die $s3->err . \": \" . $s3->errstr;\nprint $response->{bucket}.\"\\n\";\nfor my $key (@{ $response->{keys} }) {\nprint \"\\t\".$key->{key}.\"\\n\";\n}\n\n# delete key from bucket\n$bucket->deletekey($keyname);\n\n# delete bucket\n$bucket->deletebucket;\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Amazon::S3 provides a portable client interface to Amazon Simple Storage System (S3).\n\n\"Amazon S3 is storage for the Internet. It is designed to make web-scale computing easier for\ndevelopers. Amazon S3 provides a simple web services interface that can be used to store and\nretrieve any amount of data, at any time, from anywhere on the web. It gives any developer\naccess to the same highly scalable, reliable, fast, inexpensive data storage infrastructure that\nAmazon uses to run its own global network of web sites. The service aims to maximize benefits of\nscale and to pass those benefits on to developers\".\n\nTo sign up for an Amazon Web Services account, required to use this library and the S3 service,\nplease visit the Amazon Web Services web site at http://www.amazonaws.com/.\n\nYou will be billed accordingly by Amazon when you use this module and must be responsible for\nthese costs.\n\nTo learn more about Amazon's S3 service, please visit: http://s3.amazonaws.com/.\n\nThis need for this module arose from some work that needed to work with S3 and would be\ndistributed, installed and used on many various environments where compiled dependencies may not\nbe an option. Net::Amazon::S3 used XML::LibXML tying it to that specific and often difficult to\ninstall option. In order to remove this potential barrier to entry, this module is forked and\nthen modified to use XML::SAX via XML::Simple.\n\nAmazon::S3 is intended to be a drop-in replacement for <Net:Amazon::S3> that trades some\nperformance in return for portability.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "new\nCreate a new S3 client object. Takes some arguments:\n\nawsaccesskeyid\nUse your Access Key ID as the value of the AWSAccessKeyId parameter in requests you send to\nAmazon Web Services (when required). Your Access Key ID identifies you as the party\nresponsible for the request.\n\nawssecretaccesskey\nSince your Access Key ID is not encrypted in requests to AWS, it could be discovered and\nused by anyone. Services that are not free require you to provide additional information, a\nrequest signature, to verify that a request containing your unique Access Key ID could only\nhave come from you.\n\nDO NOT INCLUDE THIS IN SCRIPTS OR APPLICATIONS YOU DISTRIBUTE. YOU'LL BE SORRY.\n\nsecure\nSet this to 1 if you want to use SSL-encrypted connections when talking to S3. Defaults to\n0.\n\ntimeout\nDefines the time, in seconds, your script should wait or a response before bailing. Defaults\nis 30 seconds.\n\nretry\nEnables or disables the library to retry upon errors. This uses exponential backoff with\nretries after 1, 2, 4, 8, 16, 32 seconds, as recommended by Amazon. Defaults to off, no\nretries.\n\nhost\nDefines the S3 host endpoint to use. Defaults to 's3.amazonaws.com'.\n\nbuckets\nReturns \"undef\" on error, else HASHREF of results:\n\nownerid\nThe owner's ID of the buckets owner.\n\nownerdisplayname\nThe name of the owner account.\n\nbuckets\nAny ARRAYREF of Amazon::SimpleDB::Bucket objects for the account.\n\naddbucket\nTakes a HASHREF:\n\nbucket\nThe name of the bucket you want to add\n\naclshort (optional)\nSee the setacl subroutine for documentation on the aclshort options\n\nReturns 0 on failure or a Amazon::S3::Bucket object on success\n\nbucket BUCKET\nTakes a scalar argument, the name of the bucket you're creating\n\nReturns an (unverified) bucket object from an account. This method does not access the network.\n\ndeletebucket\nTakes either a Amazon::S3::Bucket object or a HASHREF containing\n\nbucket\nThe name of the bucket to remove\n\nReturns false (and fails) if the bucket isn't empty.\n\nReturns true if the bucket is successfully deleted.\n\nlistbucket\nList all keys in this bucket.\n\nTakes a HASHREF of arguments:\n\nbucket\nREQUIRED. The name of the bucket you want to list keys on.\n\nprefix\nRestricts the response to only contain results that begin with the specified prefix. If you\nomit this optional argument, the value of prefix for your query will be the empty string. In\nother words, the results will be not be restricted by prefix.\n\ndelimiter\nIf this optional, Unicode string parameter is included with your request, then keys that\ncontain the same string between the prefix and the first occurrence of the delimiter will be\nrolled up into a single result element in the CommonPrefixes collection. These rolled-up\nkeys are not returned elsewhere in the response. For example, with prefix=\"USA/\" and\ndelimiter=\"/\", the matching keys \"USA/Oregon/Salem\" and \"USA/Oregon/Portland\" would be\nsummarized in the response as a single \"USA/Oregon\" element in the CommonPrefixes\ncollection. If an otherwise matching key does not contain the delimiter after the prefix, it\nappears in the Contents collection.\n\nEach element in the CommonPrefixes collection counts as one against the MaxKeys limit. The\nrolled-up keys represented by each CommonPrefixes element do not. If the Delimiter parameter\nis not present in your request, keys in the result set will not be rolled-up and neither the\nCommonPrefixes collection nor the NextMarker element will be present in the response.\n\nNOTE: CommonPrefixes isn't currently supported by Amazon::S3.\n\nmax-keys\nThis optional argument limits the number of results returned in response to your query.\nAmazon S3 will return no more than this number of results, but possibly less. Even if\nmax-keys is not specified, Amazon S3 will limit the number of results in the response. Check\nthe IsTruncated flag to see if your results are incomplete. If so, use the Marker parameter\nto request the next page of results. For the purpose of counting max-keys, a 'result' is\neither a key in the 'Contents' collection, or a delimited prefix in the 'CommonPrefixes'\ncollection. So for delimiter requests, max-keys limits the total number of list results, not\njust the number of keys.\n\nmarker\nThis optional parameter enables pagination of large result sets. \"marker\" specifies where in\nthe result set to resume listing. It restricts the response to only contain results that\noccur alphabetically after the value of marker. To retrieve the next page of results, use\nthe last key from the current page of results as the marker in your next request.\n\nSee also \"nextmarker\", below.\n\nIf \"marker\" is omitted,the first page of results is returned.\n\nReturns \"undef\" on error and a HASHREF of data on success:\n\nThe HASHREF looks like this:\n\n{\nbucket       => $bucketname,\nprefix       => $bucketprefix,\nmarker       => $bucketmarker,\nnextmarker  => $bucketnextavailablemarker,\nmaxkeys     => $bucketmaxkeys,\nistruncated => $bucketistruncatedboolean\nkeys          => [$key1,$key2,...]\n}\n\nExplanation of bits of that:\n\nistruncated\nB flag that indicates whether or not all results of your query were returned in this\nresponse. If your results were truncated, you can make a follow-up paginated request using\nthe Marker parameter to retrieve the rest of the results.\n\nnextmarker\nA convenience element, useful when paginating with delimiters. The value of \"nextmarker\",\nif present, is the largest (alphabetically) of all key names and all CommonPrefixes prefixes\nin the response. If the \"istruncated\" flag is set, request the next page of results by\nsetting \"marker\" to the value of \"nextmarker\". This element is only present in the response\nif the \"delimiter\" parameter was sent with the request.\n\nEach key is a HASHREF that looks like this:\n\n{\nkey           => $key,\nlastmodified => $lastmoddate,\netag          => $etag, # An MD5 sum of the stored content.\nsize          => $size, # Bytes\nstorageclass => $storageclass # Doc?\nownerid      => $ownerid,\nownerdisplayname => $ownername\n}\n\nlistbucketall\nList all keys in this bucket without having to worry about 'marker'. This is a convenience\nmethod, but may make multiple requests to S3 under the hood.\n\nTakes the same arguments as listbucket.\n",
            "subsections": []
        },
        "ABOUT": {
            "content": "This module contains code modified from Amazon that contains the following notice:\n\n#  This software code is made available \"AS IS\" without warranties of any\n#  kind.  You may copy, display, modify and redistribute the software\n#  code either by itself or as incorporated into your code; provided that\n#  you do not remove any proprietary notices.  Your use of this software\n#  code is at your own risk and you waive any claim against Amazon\n#  Digital Services, Inc. or its affiliates with respect to your use of\n#  this software code. (c) 2006 Amazon Digital Services, Inc. or its\n#  affiliates.\n",
            "subsections": []
        },
        "TESTING": {
            "content": "Testing S3 is a tricky thing. Amazon wants to charge you a bit of money each time you use their\nservice. And yes, testing counts as using. Because of this, the application's test suite skips\nanything approaching a real test unless you set these three environment variables:\n\nAMAZONS3EXPENSIVETESTS\nDoesn't matter what you set it to. Just has to be set\n\nAWSACCESSKEYID\nYour AWS access key\n\nAWSACCESSKEYSECRET\nYour AWS sekkr1t passkey. Be forewarned that setting this environment variable on a shared\nsystem might leak that information to another user. Be careful.\n",
            "subsections": []
        },
        "TO DO": {
            "content": "Continued to improve and refine of documentation.\nReduce dependencies wherever possible.\nImplement debugging mode\nRefactor and consolidate request code in Amazon::S3\nRefactor URI creation code to make use of URI.\n",
            "subsections": []
        },
        "SUPPORT": {
            "content": "Bugs should be reported via the CPAN bug tracker at\n\n<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Amazon-S3>\n\nFor other issues, contact the author.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Timothy Appnel <tima@cpan.org>\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "Amazon::S3::Bucket, Net::Amazon::S3\n",
            "subsections": []
        },
        "COPYRIGHT AND LICENCE": {
            "content": "This module was initially based on Net::Amazon::S3 0.41, by Leon Brocard. Net::Amazon::S3 was\nbased on example code from Amazon with this notice:\n\n# This software code is made available \"AS IS\" without warranties of any # kind. You may copy,\ndisplay, modify and redistribute the software # code either by itself or as incorporated into\nyour code; provided that # you do not remove any proprietary notices. Your use of this software\n# code is at your own risk and you waive any claim against Amazon # Digital Services, Inc. or\nits affiliates with respect to your use of # this software code. (c) 2006 Amazon Digital\nServices, Inc. or its # affiliates.\n\nThe software is released under the Artistic License. The terms of the Artistic License are\ndescribed at http://www.perl.com/language/misc/Artistic.html. Except where otherwise noted,\nAmazon::S3 is Copyright 2008, Timothy Appnel, tima@cpan.org. All rights reserved.\n",
            "subsections": []
        }
    },
    "summary": "Amazon::S3 - A portable client library for working with and managing Amazon S3 buckets and keys.",
    "flags": [],
    "examples": [],
    "see_also": []
}