# C/C++ Library

# 说明

C/C++ Library、命令行工具。

# 源码

请从GitHub获取,https://github.com/SinaCloudStorage/libs3

# 依赖(debian)

  • libcurl
  • libcurl-devel
  • libxml2
  • libxml2-devel
apt-get install libcurl libcurl-devel libxml2 libxml2-devel

# 依赖(centos)

yum install wget unzip
yum install libcurl* libxml2*

# 编译安装

  1. Linux:使用make编译,编译后在build/目录下生成:
    1. 动态链接库(libs3.so)
    2. 静态链接库(libs3.a)
    3. 可执行命令行工具(s3)
  2. OSX:用XCode打开工程文件osx/s3.xcodeproj, 编译生成:
    1. 静态链接库(libs3.a)
    2. 可执行命令行工具(s3-cli)
  3. Windows:目前只支持MingW编译。

CentOS 6.6 系统为例:

mkdir -p /s3
cd /s3
yum install gcc
yum install wget unzip
yum install libcurl* libxml2*
wget https://github.com/SinaCloudStorage/libs3/archive/master.zip
unzip master.zip
cd libs3-master/
make

编译完成后,在 /s3/libs3-master/build/bin 目录下就可以找到s3的可执行文件:

[root@tests3 /s3/libs3-master/build/bin]# ls -al
total 124
drwxr-xr-x 2 root root     37 Sep  8 07:56 .
drwxr-xr-x 7 root root     65 Sep  8 07:56 ..
-rwxr-xr-x 1 root root 112906 Sep  8 07:56 s3
-rwxr-xr-x 1 root root  10542 Sep  8 07:56 testsimplexml

# 调用示例

请参考示例的源码:https://github.com/SinaCloudStorage/libs3/blob/master/src/s3.c

# 命令行工具

命令使用请参考

# 设置环境变量:
$ export S3_ACCESS_KEY_ID="您的access key"
$ export S3_SECRET_ACCESS_KEY="您的secret key"

# 使用命令行:
$ ./s3 help

This is a program for performing single requests to Sina Cloud Storage.

 Options:

   Command Line:

   -f/--force           : force operation despite warnings
   -h/--vhost-style     : use virtual-host-style URIs (default is path-style)
   -u/--unencrypted     : unencrypted (use HTTP instead of HTTPS)
   -s/--show-properties : show response properties on stdout
   -r/--retries         : retry retryable failures this number of times
                          (default is 5)

   Environment:

   S3_ACCESS_KEY_ID     : access key ID (required)
   S3_SECRET_ACCESS_KEY : secret access key (required)
   S3_HOSTNAME          : specify alternative host (optional)

 Commands (with <required parameters> and [optional parameters]) :

   (NOTE: all command parameters take a value and are specified using the
          pattern parameter=value)

   help                 : Prints this help text

   list                 : Lists owned buckets
     [allDetails]       : Show full details

   create               : Create a new bucket
     <bucket>           : Bucket to create
     [cannedAcl]        : Canned ACL for the bucket (see Canned ACLs)

   delete               : Delete a bucket or key
     <bucket>[/<key>]   : Bucket or bucket/key to delete

   list                 : List bucket contents
     <bucket>           : Bucket to list
     [prefix]           : Prefix for results set
     [marker]           : Where in results set to start listing
     [delimiter]        : Delimiter for rolling up results set
     [maxkeys]          : Maximum number of keys to return in results set
     [allDetails]       : Show full details for each key

   getacl               : Get the ACL of a bucket or key
     <bucket>[/<key>]   : Bucket or bucket/key to get the ACL of
     [filename]         : Output filename for ACL (default is stdout)

   setacl               : Set the ACL of a bucket or key
     <bucket>[/<key>]   : Bucket or bucket/key to set the ACL of
     [filename]         : Input filename for ACL (default is stdin)

   put                  : Puts an object
     <bucket>/<key>     : Bucket/key to put object to
     [filename]         : Filename to read source data from (default is stdin)
     [contentLength]    : How many bytes of source data to put (required if
                          source file is stdin)
     [cacheControl]     : Cache-Control HTTP header string to associate with
                          object
     [contentType]      : Content-Type HTTP header string to associate with
                          object
     [md5]              : MD5 for validating source data
     [contentDispositionFilename] : Content-Disposition filename string to
                          associate with object
     [contentEncoding]  : Content-Encoding HTTP header string to associate
                          with object
     [expires]          : Expiration date to associate with object
     [cannedAcl]        : Canned ACL for the object (see Canned ACLs)
     [x-amz-meta-...]]  : Metadata headers to associate with the object

   copy                 : Copies an object; if any options are set, the entire
                          metadata of the object is replaced
     <sourcebucket>/<sourcekey> : Source bucket/key
     <destbucket>/<destkey> : Destination bucket/key
     [cacheControl]     : Cache-Control HTTP header string to associate with
                          object
     [contentType]      : Content-Type HTTP header string to associate with
                          object
     [contentDispositionFilename] : Content-Disposition filename string to
                          associate with object
     [contentEncoding]  : Content-Encoding HTTP header string to associate
                          with object
     [expires]          : Expiration date to associate with object
     [cannedAcl]        : Canned ACL for the object (see Canned ACLs)
     [x-amz-meta-...]]  : Metadata headers to associate with the object

   get                  : Gets an object
     <buckey>/<key>     : Bucket/key of object to get
     [filename]         : Filename to write object data to (required if -s
                          command line parameter was used)
     [ifModifiedSince]  : Only return the object if it has been modified since
                          this date
     [ifNotmodifiedSince] : Only return the object if it has not been modified
                          since this date
     [ifMatch]          : Only return the object if its ETag header matches
                          this string
     [ifNotMatch]       : Only return the object if its ETag header does not
                          match this string
     [startByte]        : First byte of byte range to return
     [byteCount]        : Number of bytes of byte range to return

   head                 : Gets only the headers of an object, implies -s
     <bucket>/<key>     : Bucket/key of object to get headers of

   gqs                  : Generates an authenticated query string
     <bucket>[/<key>]   : Bucket or bucket/key to generate query string for
     [expires]          : Expiration date for query string
     [resource]         : Sub-resource of key for query string, without a
                          leading '?', for example, "meta"

 Canned ACLs:

  The following canned ACLs are supported:
    private (default), public-read, public-read-write, authenticated-read

 ACL Format:

  For the getacl and setacl commands, the format of the ACL list is:
  1) An initial line giving the owner id in this format:
       OwnerID <Owner ID> <Owner Display Name>
  2) Optional header lines, giving column headers, starting with the
     word "Type", or with some number of dashes
  3) Grant lines, of the form:
       <Grant Type> (whitespace) <Grantee> (whitespace) <Permission>
     where Grant Type is one of: UserID, or Group, and
     Grantee is the identification of the grantee based on this type,
     and Permission is one of: READ, WRITE, READ_ACP, or FULL_CONTROL.

  Examples:
    OwnerID  SINA0000001001HBK3UT        SINA0000001001HBK3UT
    Type     Grantee                     Display Name                Permission
    ------   ------------------------    -----------------------     --------------
    UserID   SINA0000001001LNL6CP        SINA0000001001LNL6CP        READ
    UserID   SINA0000001001LNL6CP        SINA0000001001LNL6CP        WRITE
    Group    Authenticated AWS Users                                 READ
    Group    All Users                                               READ

  Note that the easiest way to modify an ACL is to first get it, saving it
  into a file, then modifying the file, and then setting the modified file
  back as the new ACL for the bucket/object.

 Date Format:

  The format for dates used in parameters is as ISO 8601 dates, i.e.
  YYYY-MM-DDTHH:MM:SS[+/-dd:dd].  Examples:
      2008-07-29T20:36:14
      2008-07-29T20:36:14-06:00
      2008-07-29T20:36:14+11:30

# 列出所有的bucket

提示

在操作前需要限制两个环境变量,accesskey和secretkey的值请从云存储管理面板获取https://scs.sinacloud.com

  • export S3_ACCESS_KEY_ID="您的access key"
  • export S3_SECRET_ACCESS_KEY="您的secret key"

执行list命令就可以列出所有的bucket

[root@tests3 /s3/libs3-master/build/bin]# ./s3 list
                         Bucket                                 Created       
--------------------------------------------------------  --------------------
sinaappengine                                             2014-07-28T08:14:28Z
opensource                                                2015-01-16T02:46:21Z
opensource.changes.com.cn                                 2015-01-21T05:19:04Z
test.changes.com.cn                                       2016-06-15T10:34:17Z
cdn.changes.com.cn                                        2017-01-17T12:30:36Z
imgx.changes.com.cn                                       2017-03-28T02:05:04Z
cccccc.changes.com.cn                                     2017-04-14T08:40:33Z
show.changes.com.cn                                       2017-04-20T12:20:01Z
lazytools                                                 2017-12-17T12:19:41Z

# 列出bucket下的object列表

list指令后加上bucket的名称就可以列出bucket下的所有object。

[root@tests3 /s3/libs3-master/build/bin]# ./s3 list sinaappengine
                       Key                             Last Modified      Size 
--------------------------------------------------  --------------------  -----
005b面试评估表.doc                             2014-07-30T08:40:26Z  73216
Eclipse插件开发 原书第3版中文版.pdf      2017-04-11T12:39:19Z    53M
RELEASE_2012-04-04_V0.7.3.pdf                       2014-08-13T01:58:43Z  2.69M
aaa/1.txt                                           2018-09-07T05:18:51Z      1
aaa/2.txt                                           2018-09-07T05:18:40Z      1

# 获取bucket或者object ACL

[root@tests3 /s3/libs3-master/build/bin]# ./s3 getacl sinaappengine
OwnerID  SINA0000000000K7Y55F       SINA0000000000K7Y55F     
Type     Grantee                    Display Name               Permission  
-------  -------------------------  -------------------------  ------------------------------
Group    All Users                                             READ        
UserID   SINA000000000000IMGX       SINA000000000000IMGX       READ        
UserID   SINA0000000000K7Y55F       SINA0000000000K7Y55F       READ        
UserID   SINA0000000000K7Y55F       SINA0000000000K7Y55F       WRITE       
UserID   SINA0000000000K7Y55F       SINA0000000000K7Y55F       READ_ACP    
UserID   SINA0000000000K7Y55F       SINA0000000000K7Y55F       WRITE_ACP   
UserID   SINA0000001001HBK3UT       SINA0000001001HBK3UT       READ        
[root@tests3 /s3/libs3-master/build/bin]# ./s3 getacl sinaappengine/aaa/1.txt
OwnerID  SINA0000000000K7Y55F       SINA0000000000K7Y55F     
Type     Grantee                    Display Name               Permission  
-------  -------------------------  -------------------------  ------------------------------
Group    All Users                                             READ        
UserID   SINA0000000000K7Y55F       SINA0000000000K7Y55F       READ        
UserID   SINA0000000000K7Y55F       SINA0000000000K7Y55F       WRITE       
UserID   SINA0000000000K7Y55F       SINA0000000000K7Y55F       READ_ACP    
UserID   SINA0000000000K7Y55F       SINA0000000000K7Y55F       WRITE_ACP   

# 上传文件

将当前目录下的testsimplexml文件上传到sinaappenginebucket下的textsimplexmlobject。

[root@tests3 /s3/libs3-master/build/bin]# ./s3 put sinaappengine/textsimplexml <./testsimplexml 

# 删除文件

删除sinaappengine下的testsimplexml文件:

./s3 delete sinaappengine/textsimplexml

# 下载文件到本地

下载`sinaappengine下的testsimplexml文件到本地的/tmp/``目录。

./s3 get sinaappengine/textsimplexml >/tmp/testsimplexml

提示

更多实例和参数传递请参考 ./s3 help 输出的提示。