]> git.wincent.com - mkdtemp.git/blob - ext/mkdtemp.c
Documentation tweaks to work better with YARD
[mkdtemp.git] / ext / mkdtemp.c
1 // Copyright 2007-2010 Wincent Colaiuta. All rights reserved.
2 //
3 // Redistribution and use in source and binary forms, with or without
4 // modification, are permitted provided that the following conditions are met:
5 //
6 // 1. Redistributions of source code must retain the above copyright notice,
7 //    this list of conditions and the following disclaimer.
8 // 2. Redistributions in binary form must reproduce the above copyright notice,
9 //    this list of conditions and the following disclaimer in the documentation
10 //    and/or other materials provided with the distribution.
11 //
12 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
13 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
14 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
15 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
16 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
17 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
18 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
19 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
20 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
21 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
22 // POSSIBILITY OF SUCH DAMAGE.
23
24 #include <ruby.h>
25 #include <errno.h>
26 #include <unistd.h>
27 #include "ruby_compat.h"
28
29 // helper function needed by rb_iterate; see:
30 //  http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/144100
31 VALUE call_chdir(VALUE dir)
32 {
33     return rb_funcall(rb_cDir, rb_intern("chdir"), 1, dir);
34 }
35
36 // helper function needed by rb_iterate
37 VALUE yield_block(VALUE ignored, VALUE block)
38 {
39     return rb_funcall(block, rb_intern("call"), 0);
40 }
41 /*
42  * Document-method: mkdtemp
43  * call-seq:
44  *     Dir.mkdtemp([string]) -> string
45  *     Dir.mkdtemp([string]) { ... } -> string
46  *
47  * This method securely creates temporary directories. It is a wrapper for the
48  * <code>mkdtemp()</code> function in the standard C library. It takes an
49  * optional String parameter as a template describing the desired form of the
50  * directory name and overwriting the template in-place; if no template is
51  * supplied then "/tmp/temp.XXXXXX" is used as a default.
52  *
53  * If supplied a block, performs a <code>Dir.chdir</code> into the created
54  * directory and yields to the block:
55  *
56  *      # this:            # is a shorthand for:
57  *      Dir.mkdtemp do     #   dir = Dir.mkdtemp
58  *        puts Dir.pwd     #   Dir.chdir dir do
59  *      end                #     puts Dir.pwd
60  *                         #   end
61  *
62  * Note that the exact implementation of <code>mkdtemp()</code> may vary
63  * depending on the target system. For example, on Mac OS X at the time of
64  * writing, the man page states that the template may contain "some number" of
65  * "Xs" on the end of the string, whereas on Red Hat Enterprise Linux it states
66  * that the template suffix "must be XXXXXX".
67  *
68  * @param [String] optional template string
69  * @return [String, nil] the filled-in template string, or nil in the event of
70  *   an error
71  */
72 static VALUE dir_mkdtemp_m(int argc, VALUE *argv, VALUE self)
73 {
74     VALUE template, block;
75     char *c_template;
76     char *path;
77
78     // process arguments
79     if (rb_scan_args(argc, argv, "01&", &template, &block) == 0)    // 0 mandatory, 1 optional, 1 block
80         template = Qnil;                                            // default to nil if no argument passed
81     if (NIL_P(template))
82         template = rb_str_new2("/tmp/temp.XXXXXX");                 // fallback to this template if passed nil
83     SafeStringValue(template);                                      // raises if template is tainted and SAFE level > 0
84     template = StringValue(template);                               // duck typing support
85
86     // create temporary storage
87     c_template = malloc(RSTRING_LEN(template) + 1);
88     if (!c_template)
89         rb_raise(rb_eNoMemError, "failed to allocate %ld bytes of template storage", RSTRING_LEN(template) + 1);
90     strncpy(c_template, RSTRING_PTR(template), RSTRING_LEN(template));
91     c_template[RSTRING_LEN(template)] = 0;              // NUL-terminate
92
93     // fill out template
94     path = mkdtemp(c_template);
95     if (path)
96         template = rb_str_new2(path);
97     free(c_template);
98     if (path == NULL)
99         rb_raise(rb_eSystemCallError, "mkdtemp failed (error #%d: %s)", errno, strerror(errno));
100
101     // yield to block if given, inside Dir.chdir
102     if (rb_block_given_p() == Qtrue)
103         rb_iterate(call_chdir, template, yield_block, block);
104     return template;
105 }
106
107 void Init_mkdtemp()
108 {
109 #if 0
110     // for YARD, need to fake this here
111     VALUE rb_cDir = rb_define_class("Dir", rb_cObject);
112 #endif
113     rb_define_singleton_method(rb_cDir, "mkdtemp", dir_mkdtemp_m, -1);
114 }