extattr 0.1.2 → 0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 53957e04a2ee7834088849a2f73415f363d24e23
+  data.tar.gz: 2f649f3e25c9b0a8a0278a5f928298d2719d061e
+SHA512:
+  metadata.gz: a2cff71bea005342d08ed40463d99a53259b88e2a2d421c9fae98719096f0fd6431e152159148750093813a30b1066ede5ea078e90798ef71d9ea1a4ad7e1fd9
+  data.tar.gz: cb69dfc4e4c68b2041694922917a35a56df7334d5a0c8c06c2def76bafe2a8e3c2e2c69d3105a3e9603b132ef2b8f46f24abc045c8e57142c6823488360c188f

data/{LICENSE.txt → LICENSE.md}

@@ -1,3 +1,5 @@
+#@markup markdown
+
 Copyright (c) 2012, dearblue. All rights reserved.
 
 Redistribution and use in source and binary forms, with or

data/README.md

@@ -0,0 +1,161 @@
+# @markup markdown
+
+# extattr
+
+extattr is filesystem extended attributes operation library for FreeBSD, GNU/Linux and Microsoft Windows.
+
+***END OF DOCUMENT IN ENGLISH***
+
+----
+
+***START OF DOCUMENT IN JAPANESE***
+
+extattr はファイルシステムの拡張属性を操作するライブラリで、FreeBSD、GNU/Linux、Windows に対応しています。
+
+サポートされる環境で、統一的なメソッドを提供します。
+
+実装については、以下のようになっています。
+
+- FreeBSD: extattr (`extattr_list`, `extattr_get`, `extattr_set`, `extattr_delete`)
+- GNU/Linux: xattr (`listxattr`, `getxattr`, `setxattr`, `removexattr`)
+- Microsoft Windows: NTFS ADS (代替データストリーム) / 拡張ファイル属性 (`NtQueryEaFile`, `NtSetEaFile`)
+
+
+## Support ruby version
+
+- ruby-1.9.3+
+- ruby-2.0+
+- ruby-2.1+
+
+
+## Tested system
+
+- PC-BSD/AMD64 10.0
+- lubuntu 13.10 (i386)
+- Microsoft Windows XP Professional SP3
+- Microsoft Windows 7 Professional SP1
+
+
+## 簡易リファレンスマニュアル
+
+クラスメソッドに『!』がついているものはシンボリックリンクに対する操作となります。
+
+キーワード引数の `namespace` を与えると、拡張属性の名前空間を指定できます。
+
+規定値は `File::EXTATTR_NAMESPACE_USER` で、ほかの値は `File::EXTATTR_NAMESPACE_SYSTEM` のみが指定できます。
+
+
+### 拡張属性の属性名を取得
+
+    File.extattr_list(path, namespace: File::EXTATTR_NAMESPACE_USER) -> array
+    File.extattr_list(path, namespace: File::EXTATTR_NAMESPACE_USER) { |name| ... } -> nil
+    File.extattr_list!(path, namespace: File::EXTATTR_NAMESPACE_USER) -> array
+    File.extattr_list!(path, namespace: File::EXTATTR_NAMESPACE_USER) { |name| ... } -> nil
+    File#extattr_list(namespace: File::EXTATTR_NAMESPACE_USER) -> array
+    File#extattr_list(namespace: File::EXTATTR_NAMESPACE_USER) { |name| ... } -> nil
+
+### 拡張属性の要素の大きさを取得
+
+    File.extattr_size(path, name, namespace: File::EXTATTR_NAMESPACE_USER) -> size
+    File.extattr_size!(path, name, namespace: File::EXTATTR_NAMESPACE_USER) -> size
+    File#extattr_size(name, namespace: File::EXTATTR_NAMESPACE_USER) -> size
+
+### 拡張属性の要素を取得
+
+    File.extattr_get(path, name, namespace: File::EXTATTR_NAMESPACE_USER) -> data (String)
+    File.extattr_get!(path, name, namespace: File::EXTATTR_NAMESPACE_USER) -> data (String)
+    File#extattr_get(name, namespace: File::EXTATTR_NAMESPACE_USER) -> data (String)
+
+### 拡張属性の要素を設定
+
+    File.extattr_set(path, name, data, namespace: File::EXTATTR_NAMESPACE_USER) -> nil
+    File.extattr_set!(path, name, data, namespace: File::EXTATTR_NAMESPACE_USER) -> nil
+    File#extattr_set(name, data, namespace: File::EXTATTR_NAMESPACE_USER) -> nil
+
+### 拡張属性の要素を削除
+
+    File.extattr_delete(path, name, namespace: File::EXTATTR_NAMESPACE_USER) -> nil
+    File.extattr_delete!(path, name, namespace: File::EXTATTR_NAMESPACE_USER) -> nil
+    File#extattr_delete(name, namespace: File::EXTATTR_NAMESPACE_USER) -> nil
+
+### 拡張属性の属性名と要素を列挙する
+
+    File.extattr_each(path, namespace: File::EXTATTR_NAMESPACE_USER) -> Enumerator
+    File.extattr_each(path, namespace: File::EXTATTR_NAMESPACE_USER) { |name, data| ... } -> nil
+    File.extattr_each!(path, namespace: File::EXTATTR_NAMESPACE_USER) -> Enumerator
+    File.extattr_each!(path, namespace: File::EXTATTR_NAMESPACE_USER) { |name, data| ... } -> nil
+    File#extattr_each(namespace: File::EXTATTR_NAMESPACE_USER) -> Enumerator
+    File#extattr_each(namespace: File::EXTATTR_NAMESPACE_USER) { |name, data| ... } -> file
+
+
+## GNU/Linux における特記事項
+
+- GNU/Linux で利用されている名前空間〈security〉〈trusted〉には未対応です。
+
+
+## Microsoft Windows における特記事項
+
+- Windows XP 以降を必要とします。Win2k でも動作するかもしれません (未検証)。  
+  Windows 9x シリーズでは `require "extattr"` の段階で例外が発生すると思われます (未検証)。
+- `File::EXTATTR_NAMESPACE_USER` は (比較的よく利用される) NTFS ADS に対する操作で、`File::EXTATTR_NAMESPACE_SYSTEM` が本来の (あまり利用されていない) 拡張ファイル属性に対する操作となります。
+- リパースポイント (ジャンクションやシンボリックリンク) に対する NTFS ADS は要素の取得や設定、削除は出来ません。  
+  必ずリンク先に対する操作となります (やり方がわかりません)。
+- 64 KiB を超える NTFS ADS は取得も設定も出来ません。  
+  これは『拡張属性』と捉えた場合、巨大なデータを扱えるべきではないという考えによるためです
+  (本当のところは FreeBSD の拡張属性が最大 64KiB 弱であることが由来です)。
+- 巨大な NTFS ADS を扱いたい場合は、`File.open` でファイルとして扱えるので自由に読み書きできます。  
+  これは ruby に限ったことではなく、Windows による仕様です。  
+  この場合の与えるファイル名は、`path + ":" + name` という形になります。
+
+        filepath = "sample.txt"
+        extattrname = "category"
+        ntfs_ads_name = filepath + ":" + extattrname
+        File.open(ntfs_ads_name, "r") do |file|
+          ...
+        end
+
+## 既知のバグ
+
+### `extattr_list` のブロック内で `extattr_set` `extattr_delete` を行うと思いがけない副作用が起こる場合がある
+
+解決方法: `extattr_set` か `extattr_delete` のどちらかを同時に利用したい場合、`extattr_list.each` を用いてください。
+
+
+## 変更履歴
+
+### 0.1
+
+はじめてのりりーす
+
+- 拡張ファイル属性の一覧、取得、設定、削除を行うことが出来ます
+- **セキュリティリスクあり**: `$SAFE` の確認や汚染状態の伝播を行ないません
+- Windows 版では、NTFS ADS に対する操作となります。`File::EXTATTR_NAMESPACE_USER` のみが有効です
+
+### 0.2
+
+- セーフレベルに関する改善
+  - `$SAFE` と汚染状態を確認するようになりました
+  - 汚染状態を伝播させるようになりました
+- バージョン情報と実装 API に関する情報の取得
+  - `File::EXTATTR_VERSION` 定数によって、バージョン情報が取得できるようになりました
+  - `File::EXTATTR_IMPLEMENT` 定数によって、実装に関する情報が取得できるようになりました
+- 機能の改善
+  - `File.extattr_each` / `File#extattr_each` によって、ファイル拡張属性の名前と値を繰り返し取得できるようになりました
+- Windows 版に関する改善
+  - `File::EXTATTR_NAMESPACE_SYSTEM` によって、本来の拡張ファイル属性の操作が行えるようになりました
+    (NtQueryEaFile / NtSetEaFile)
+
+
+## 参考資料
+
+- extattr
+  - <http://www.freebsd.org/cgi/man.cgi?query=extattr&sektion=2>
+- xattr
+  - <http://linuxjm.sourceforge.jp/html/LDP_man-pages/man2/listxattr.2.html>
+- windows
+  - <http://msdn.microsoft.com/en-us/library/cc232069.aspx>
+  - <http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/NT%20Objects/File/FILE_INFORMATION_CLASS.html>
+  - <http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/NT%20Objects/File/NtQueryInformationFile.html>
+  - <http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/NT%20Objects/File/NtQueryEaFile.html>
+  - <http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/NT%20Objects/File/NtSetEaFile.html>
+  - <http://www.zezula.net/en/fstools/filetest.html>

data/Rakefile

@@ -0,0 +1,105 @@
+#vim: set fileencoding:utf-8
+
+AUTHOR = "dearblue"
+EMAIL = "dearblue@users.sourceforge.jp"
+WEBSITE = "http://sourceforge.jp/projects/rutsubo/"
+LICENSE = "2-clause BSD License"
+PACKAGE = "extattr"
+VERSION = "0.2"
+PLATFORM_NATIVE = Gem::Platform.local.to_s
+GEMFILE = "#{PACKAGE}-#{VERSION}.gem"
+GEMFILE_NATIVE = "#{PACKAGE}-#{VERSION}-#{PLATFORM_NATIVE}.gem"
+GEMSPEC = "#{PACKAGE}.gemspec"
+GEMSPEC_NATIVE = "#{PACKAGE}-#{PLATFORM_NATIVE}.gemspec"
+SUMMARY = "extended attribute operation library for ruby"
+DESCRIPTION = <<EOS
+extattr is extended file attribute operation library for ruby.
+Supported for FreeBSD (extattr), GNU/Linux (xattr) and Microsoft Windows (NTFS ADS + Extended Attributes).
+EOS
+
+RUBY19 = ENV["RUBY19"]
+RUBY20 = ENV["RUBY20"]
+RUBY21 = ENV["RUBY21"]
+RUBYSET = [RUBY19, RUBY20, RUBY21].compact
+
+#RUBY_VERSIONS = [RUBY20].map { |ruby| [`#{ruby} -e "puts RUBY_VERSION"`.slice(/\d+\.\d+/), ruby] }
+RUBY_VERSIONS = RUBYSET.map { |ruby| [`#{ruby} -e "puts RbConfig::CONFIG['ruby_version']"`.chomp, ruby] }
+
+BINFILES = FileList["bin/*"]
+EXTFILES = FileList["ext/{*.h,*.c,*.cc}"]
+LIBFILES = FileList["lib/**/*.rb"]
+SOFILES_SET = RUBY_VERSIONS.map { |(ver, ruby)| ["lib/#{ver}/#{PACKAGE}.so", ruby] }
+SOFILES = SOFILES_SET.map { |(lib, ruby)| lib }
+EXTCONF = FileList["ext/extconf.rb"]
+
+SPECSTUB = Gem::Specification.new do |s|
+  s.name = PACKAGE
+  s.version = VERSION
+  s.summary = SUMMARY
+  s.description = DESCRIPTION
+  s.homepage = WEBSITE
+  s.license = LICENSE
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.executables = BINFILES.map { |n| File.basename n }
+  s.files = %w(LICENSE.md README.md Rakefile) + FileList["spec/*.rb"] + BINFILES + EXTCONF + EXTFILES + LIBFILES
+  s.rdoc_options = %w(--charset UTF-8 --main README.md)
+  #s.rdoc_options = %w(--charset UTF-8 --locale ja --main README.md)
+  s.has_rdoc = false
+  s.required_ruby_version = ">= 1.9.3"
+  s.add_development_dependency "rspec", "~> 2.14"
+  s.add_development_dependency "rake", "~> 10.0"
+end
+
+
+task :default => :gem
+task :gem => [GEMFILE_NATIVE, GEMFILE]
+task :gemspec => GEMSPEC
+task :gemspec_native => GEMSPEC_NATIVE
+task :gemfile => GEMFILE
+task :gemfile_native => GEMFILE_NATIVE
+
+task :rdoc do
+  sh "yardoc --charset UTF-8 --locale ja --main README.md README.md LICENSE.md #{(EXTFILES + LIBFILES).join(" ")}"
+end
+
+
+file GEMFILE => [GEMSPEC] + BINFILES + EXTFILES + LIBFILES do
+  sh "gem build #{GEMSPEC}"
+end
+
+file GEMFILE_NATIVE => [GEMSPEC_NATIVE] + BINFILES + EXTFILES + LIBFILES + SOFILES do
+  sh "gem build #{GEMSPEC_NATIVE}"
+end
+
+file GEMSPEC => __FILE__ do
+  s = SPECSTUB.dup
+  s.extensions += EXTCONF
+  File.write(GEMSPEC, s.to_ruby, mode: "wb")
+end
+
+file GEMSPEC_NATIVE => __FILE__ do
+  s = SPECSTUB.dup
+  s.files += SOFILES
+  s.platform = PLATFORM_NATIVE
+  File.write(GEMSPEC_NATIVE, s.to_ruby, mode: "wb")
+end
+
+SOFILES_SET.each do |(soname, ruby)|
+  sodir = File.dirname(soname)
+  makefile = File.join(sodir, "Makefile")
+
+  directory sodir
+
+  file soname => [makefile] + EXTFILES do
+    cd sodir do
+      sh "make"
+    end
+  end
+
+  file makefile => [sodir] + EXTCONF do
+    cd sodir do
+      sh "#{ruby} ../../ext/extconf.rb"
+    end
+  end
+end

data/ext/extattr-extattr.h

@@ -0,0 +1,192 @@
+#include <sys/types.h>
+#include <sys/extattr.h>
+
+
+static void
+extattr_list_name(const char list[], size_t size, VALUE infection_source, void (*func)(void *, VALUE), void *userdata)
+{
+    // Each list entry consists of a single byte containing the length of
+    // the attribute name, followed by the attribute name.
+    // The attribute name is not terminated by ASCII 0 (nul).
+    const char *ptr = list;
+    const char *end = list + size;
+
+    while (ptr < end) {
+        size_t len = (uint8_t)*ptr ++;
+        if (ptr + len > end) { return; }
+        VALUE v = rb_str_new(ptr, len);
+        OBJ_INFECT(v, infection_source);
+        func(userdata, v);
+        ptr += len;
+    }
+}
+
+static int
+get_extattr_list_size(int (*extattr_list)(), intptr_t d, int namespace1)
+{
+    int size = extattr_list(d, namespace1, NULL, 0);
+    if (size < 0) { rb_sys_fail("extattr_list call error"); }
+    return size;
+}
+
+static VALUE
+extattr_list_common(int (*extattr_list)(), intptr_t d, VALUE infection_source, int namespace1)
+{
+    size_t size = get_extattr_list_size(extattr_list, d, namespace1);
+    VALUE buf;
+    char *ptr = ALLOCV(buf, size);
+
+    ssize_t size1 = extattr_list(d, namespace1, ptr, size);
+    if (size1 < 0) { rb_sys_fail("extattr_list call error"); }
+
+    VALUE list = Qnil;
+    if (rb_block_given_p()) {
+        extattr_list_name(ptr, size1, infection_source,
+                          (void (*)(void *, VALUE))rb_yield_values, (void *)(1));
+    } else {
+        list = rb_ary_new();
+        OBJ_INFECT(list, infection_source);
+        extattr_list_name(ptr, size1, infection_source,
+                          (void (*)(void *, VALUE))rb_ary_push, (void *)list);
+    }
+    ALLOCV_END(buf);
+
+    return list;
+}
+
+static VALUE
+file_extattr_list_main(VALUE file, int fd, int namespace1)
+{
+    return extattr_list_common(extattr_list_fd, fd, file, namespace1);
+}
+
+static VALUE
+file_s_extattr_list_main(VALUE path, int namespace1)
+{
+    return extattr_list_common(extattr_list_file, (intptr_t)StringValueCStr(path), path, namespace1);
+}
+
+static VALUE
+file_s_extattr_list_link_main(VALUE path, int namespace1)
+{
+    return extattr_list_common(extattr_list_link, (intptr_t)StringValueCStr(path), path, namespace1);
+}
+
+
+static VALUE
+extattr_size_common(int (*extattr_get)(), intptr_t d, int namespace1, VALUE name)
+{
+    ssize_t size = extattr_get(d, namespace1, RSTRING_PTR(name), NULL, 0);
+    if (size < 0) { rb_sys_fail("extattr_get call error"); }
+    return SIZET2NUM(size);
+}
+
+static VALUE
+file_extattr_size_main(VALUE file, int fd, int namespace1, VALUE name)
+{
+    return extattr_size_common(extattr_get_fd, fd, namespace1, name);
+}
+
+static VALUE
+file_s_extattr_size_main(VALUE path, int namespace1, VALUE name)
+{
+    return extattr_size_common(extattr_get_file, (intptr_t)StringValueCStr(path), namespace1, name);
+}
+
+static VALUE
+file_s_extattr_size_link_main(VALUE path, int namespace1, VALUE name)
+{
+    return extattr_size_common(extattr_get_link, (intptr_t)StringValueCStr(path), namespace1, name);
+}
+
+
+static VALUE
+extattr_get_common(int (*extattr_get)(), intptr_t d, VALUE path, int namespace1, VALUE name)
+{
+    ssize_t size = extattr_get(d, namespace1, RSTRING_PTR(name), NULL, 0);
+    if (size < 0) { rb_sys_fail(StringValueCStr(path)); }
+    VALUE buf = rb_str_buf_new(size);
+    size = extattr_get(d, namespace1, RSTRING_PTR(name), RSTRING_PTR(buf), size);
+    if (size < 0) { rb_sys_fail(StringValueCStr(path)); }
+    rb_str_set_len(buf, size);
+    return buf;
+}
+
+static VALUE
+file_extattr_get_main(VALUE file, int fd, int namespace1, VALUE name)
+{
+    return extattr_get_common(extattr_get_fd, fd, RFILE(file)->fptr->pathv, namespace1, name);
+}
+
+static VALUE
+file_s_extattr_get_main(VALUE path, int namespace1, VALUE name)
+{
+    return extattr_get_common(extattr_get_file, (intptr_t)StringValueCStr(path), path, namespace1, name);
+}
+
+static VALUE
+file_s_extattr_get_link_main(VALUE path, int namespace1, VALUE name)
+{
+    return extattr_get_common(extattr_get_link, (intptr_t)StringValueCStr(path), path, namespace1, name);
+}
+
+
+static VALUE
+extattr_set_common(int (*extattr_set)(), intptr_t d, int namespace1, VALUE name, VALUE data)
+{
+    int status = extattr_set(d, namespace1, RSTRING_PTR(name), RSTRING_PTR(data), RSTRING_LEN(data));
+    if (status < 0) { rb_sys_fail("extattr_set call error"); }
+    return Qnil;
+}
+
+static VALUE
+file_extattr_set_main(VALUE file, int fd, int namespace1, VALUE name, VALUE data)
+{
+    return extattr_set_common(extattr_set_fd, fd, namespace1, name, data);
+}
+
+static VALUE
+file_s_extattr_set_main(VALUE path, int namespace1, VALUE name, VALUE data)
+{
+    return extattr_set_common(extattr_set_file, (intptr_t)StringValueCStr(path), namespace1, name, data);
+}
+
+static VALUE
+file_s_extattr_set_link_main(VALUE path, int namespace1, VALUE name, VALUE data)
+{
+    return extattr_set_common(extattr_set_link, (intptr_t)StringValueCStr(path), namespace1, name, data);
+}
+
+
+static VALUE
+extattr_delete_common(int (*extattr_delete)(), intptr_t d, int namespace1, VALUE name)
+{
+    int status = extattr_delete(d, namespace1, RSTRING_PTR(name), NULL, 0);
+    if (status < 0) { rb_sys_fail("extattr_delete call error"); }
+    return Qnil;
+}
+
+static VALUE
+file_extattr_delete_main(VALUE file, int fd, int namespace1, VALUE name)
+{
+    return extattr_delete_common(extattr_delete_fd, fd, namespace1, name);
+}
+
+static VALUE
+file_s_extattr_delete_main(VALUE path, int namespace1, VALUE name)
+{
+    return extattr_delete_common(extattr_delete_file, (intptr_t)StringValueCStr(path), namespace1, name);
+}
+
+static VALUE
+file_s_extattr_delete_link_main(VALUE path, int namespace1, VALUE name)
+{
+    return extattr_delete_common(extattr_delete_link, (intptr_t)StringValueCStr(path), namespace1, name);
+}
+
+
+static void
+ext_init_implement(void)
+{
+    rb_define_const(rb_cFile, "EXTATTR_IMPLEMANT", rb_str_freeze(rb_str_new_cstr("extattr")));
+}