File: C:/Ruby27-x64/share/doc/ruby/html/Process/GID.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>module Process::GID - RDoc Documentation</title>
<script type="text/javascript">
var rdoc_rel_prefix = "../";
var index_rel_prefix = "../";
</script>
<script src="../js/navigation.js" defer></script>
<script src="../js/search.js" defer></script>
<script src="../js/search_index.js" defer></script>
<script src="../js/searcher.js" defer></script>
<script src="../js/darkfish.js" defer></script>
<link href="../css/fonts.css" rel="stylesheet">
<link href="../css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="module">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="../index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="../table_of_contents.html#pages">Pages</a>
<a href="../table_of_contents.html#classes">Classes</a>
<a href="../table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div id="class-metadata">
<!-- Method Quickref -->
<div id="method-list-section" class="nav-section">
<h3>Methods</h3>
<ul class="link-list" role="directory">
<li ><a href="#method-c-change_privilege">::change_privilege</a>
<li ><a href="#method-c-eid">::eid</a>
<li ><a href="#method-c-from_name">::from_name</a>
<li ><a href="#method-c-grant_privilege">::grant_privilege</a>
<li ><a href="#method-c-re_exchange">::re_exchange</a>
<li ><a href="#method-c-re_exchangeable-3F">::re_exchangeable?</a>
<li ><a href="#method-c-rid">::rid</a>
<li ><a href="#method-c-sid_available-3F">::sid_available?</a>
<li ><a href="#method-c-switch">::switch</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-labelledby="module-Process::GID">
<h1 id="module-Process::GID" class="module">
module Process::GID
</h1>
<section class="description">
<p>The <a href="GID.html"><code>Process::GID</code></a> module contains a collection of module functions which can be used to portably get, set, and switch the current process's real, effective, and saved group IDs.</p>
</section>
<section id="5Buntitled-5D" class="documentation-section">
<section id="public-class-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Class Methods</h3>
</header>
<div id="method-c-change_privilege" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
Process::GID.change_privilege(group) → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Change the current process's real and effective group ID to that specified by <em>group</em>. Returns the new group ID. Not available on all platforms.</p>
<pre class="ruby">[<span class="ruby-constant">Process</span>.<span class="ruby-identifier">gid</span>, <span class="ruby-constant">Process</span>.<span class="ruby-identifier">egid</span>] <span class="ruby-comment">#=> [0, 0]</span>
<span class="ruby-constant">Process</span><span class="ruby-operator">::</span><span class="ruby-constant">GID</span>.<span class="ruby-identifier">change_privilege</span>(<span class="ruby-value">33</span>) <span class="ruby-comment">#=> 33</span>
[<span class="ruby-constant">Process</span>.<span class="ruby-identifier">gid</span>, <span class="ruby-constant">Process</span>.<span class="ruby-identifier">egid</span>] <span class="ruby-comment">#=> [33, 33]</span>
</pre>
<div class="method-source-code" id="change_privilege-source">
<pre>static VALUE
p_gid_change_privilege(VALUE obj, VALUE id)
{
rb_gid_t gid;
check_gid_switch();
gid = OBJ2GID(id);
if (geteuid() == 0) { /* root-user */
#if defined(HAVE_SETRESGID)
if (setresgid(gid, gid, gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
#elif defined HAVE_SETGID
if (setgid(gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
#elif defined(HAVE_SETREGID) && !defined(OBSOLETE_SETREGID)
if (getgid() == gid) {
if (SAVED_GROUP_ID == gid) {
if (setregid(-1, gid) < 0) rb_sys_fail(0);
}
else {
if (gid == 0) { /* (r,e,s) == (root, y, x) */
if (setregid(-1, SAVED_GROUP_ID) < 0) rb_sys_fail(0);
if (setregid(SAVED_GROUP_ID, 0) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = 0; /* (r,e,s) == (x, root, root) */
if (setregid(gid, gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
}
else { /* (r,e,s) == (z, y, x) */
if (setregid(0, 0) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = 0;
if (setregid(gid, gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
}
}
}
else {
if (setregid(gid, gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
}
#elif defined(HAVE_SETRGID) && defined (HAVE_SETEGID)
if (getgid() == gid) {
if (SAVED_GROUP_ID == gid) {
if (setegid(gid) < 0) rb_sys_fail(0);
}
else {
if (gid == 0) {
if (setegid(gid) < 0) rb_sys_fail(0);
if (setrgid(SAVED_GROUP_ID) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = 0;
if (setrgid(0) < 0) rb_sys_fail(0);
}
else {
if (setrgid(0) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = 0;
if (setegid(gid) < 0) rb_sys_fail(0);
if (setrgid(gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
}
}
}
else {
if (setegid(gid) < 0) rb_sys_fail(0);
if (setrgid(gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
}
#else
rb_notimplement();
#endif
}
else { /* unprivileged user */
#if defined(HAVE_SETRESGID)
if (setresgid((getgid() == gid)? (rb_gid_t)-1: gid,
(getegid() == gid)? (rb_gid_t)-1: gid,
(SAVED_GROUP_ID == gid)? (rb_gid_t)-1: gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
#elif defined(HAVE_SETREGID) && !defined(OBSOLETE_SETREGID)
if (SAVED_GROUP_ID == gid) {
if (setregid((getgid() == gid)? (rb_uid_t)-1: gid,
(getegid() == gid)? (rb_uid_t)-1: gid) < 0)
rb_sys_fail(0);
}
else if (getgid() != gid) {
if (setregid(gid, (getegid() == gid)? (rb_uid_t)-1: gid) < 0)
rb_sys_fail(0);
SAVED_GROUP_ID = gid;
}
else if (/* getgid() == gid && */ getegid() != gid) {
if (setregid(getegid(), gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
if (setregid(gid, -1) < 0) rb_sys_fail(0);
}
else { /* getgid() == gid && getegid() == gid */
if (setregid(-1, SAVED_GROUP_ID) < 0) rb_sys_fail(0);
if (setregid(SAVED_GROUP_ID, gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
if (setregid(gid, -1) < 0) rb_sys_fail(0);
}
#elif defined(HAVE_SETRGID) && defined(HAVE_SETEGID)
if (SAVED_GROUP_ID == gid) {
if (getegid() != gid && setegid(gid) < 0) rb_sys_fail(0);
if (getgid() != gid && setrgid(gid) < 0) rb_sys_fail(0);
}
else if (/* SAVED_GROUP_ID != gid && */ getegid() == gid) {
if (getgid() != gid) {
if (setrgid(gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
}
else {
if (setrgid(SAVED_GROUP_ID) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
if (setrgid(gid) < 0) rb_sys_fail(0);
}
}
else if (/* getegid() != gid && */ getgid() == gid) {
if (setegid(gid) < 0) rb_sys_fail(0);
if (setrgid(SAVED_GROUP_ID) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
if (setrgid(gid) < 0) rb_sys_fail(0);
}
else {
rb_syserr_fail(EPERM, 0);
}
#elif defined HAVE_44BSD_SETGID
if (getgid() == gid) {
/* (r,e,s)==(gid,?,?) ==> (gid,gid,gid) */
if (setgid(gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
}
else {
rb_syserr_fail(EPERM, 0);
}
#elif defined HAVE_SETEGID
if (getgid() == gid && SAVED_GROUP_ID == gid) {
if (setegid(gid) < 0) rb_sys_fail(0);
}
else {
rb_syserr_fail(EPERM, 0);
}
#elif defined HAVE_SETGID
if (getgid() == gid && SAVED_GROUP_ID == gid) {
if (setgid(gid) < 0) rb_sys_fail(0);
}
else {
rb_syserr_fail(EPERM, 0);
}
#else
(void)gid;
rb_notimplement();
#endif
}
return id;
}</pre>
</div>
</div>
</div>
<div id="method-c-eid" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
egid → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
Process::GID.eid → integer
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
Process::Sys.geteid → integer
</span>
</div>
<div class="method-description">
<p>Returns the effective group ID for this process. Not available on all platforms.</p>
<pre class="ruby"><span class="ruby-constant">Process</span>.<span class="ruby-identifier">egid</span> <span class="ruby-comment">#=> 500</span>
</pre>
<div class="method-source-code" id="eid-source">
<pre>static VALUE
proc_getegid(VALUE obj)
{
rb_gid_t egid = getegid();
return GIDT2NUM(egid);
}</pre>
</div>
</div>
</div>
<div id="method-c-from_name" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
Process::GID.from_name(name) → gid
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Get the group ID by the <em>name</em>. If the group is not found, <code>ArgumentError</code> will be raised.</p>
<pre class="ruby"><span class="ruby-constant">Process</span><span class="ruby-operator">::</span><span class="ruby-constant">GID</span>.<span class="ruby-identifier">from_name</span>(<span class="ruby-string">"wheel"</span>) <span class="ruby-comment">#=> 0</span>
<span class="ruby-constant">Process</span><span class="ruby-operator">::</span><span class="ruby-constant">GID</span>.<span class="ruby-identifier">from_name</span>(<span class="ruby-string">"nosuchgroup"</span>) <span class="ruby-comment">#=> can't find group for nosuchgroup (ArgumentError)</span>
</pre>
<div class="method-source-code" id="from_name-source">
<pre>static VALUE
p_gid_from_name(VALUE self, VALUE id)
{
return GIDT2NUM(OBJ2GID(id));
}</pre>
</div>
</div>
</div>
<div id="method-c-grant_privilege" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
Process::GID.grant_privilege(group) → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
Process::GID.eid = group → integer
</span>
</div>
<div class="method-description">
<p><a href="../Set.html"><code>Set</code></a> the effective group ID, and if possible, the saved group ID of the process to the given <em>group</em>. Returns the new effective group ID. Not available on all platforms.</p>
<pre class="ruby">[<span class="ruby-constant">Process</span>.<span class="ruby-identifier">gid</span>, <span class="ruby-constant">Process</span>.<span class="ruby-identifier">egid</span>] <span class="ruby-comment">#=> [0, 0]</span>
<span class="ruby-constant">Process</span><span class="ruby-operator">::</span><span class="ruby-constant">GID</span>.<span class="ruby-identifier">grant_privilege</span>(<span class="ruby-value">31</span>) <span class="ruby-comment">#=> 33</span>
[<span class="ruby-constant">Process</span>.<span class="ruby-identifier">gid</span>, <span class="ruby-constant">Process</span>.<span class="ruby-identifier">egid</span>] <span class="ruby-comment">#=> [0, 33]</span>
</pre>
<div class="method-source-code" id="grant_privilege-source">
<pre>static VALUE
p_gid_grant_privilege(VALUE obj, VALUE id)
{
rb_setegid_core(OBJ2GID(id));
return id;
}</pre>
</div>
</div>
</div>
<div id="method-c-re_exchange" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
Process::GID.re_exchange → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Exchange real and effective group IDs and return the new effective group ID. Not available on all platforms.</p>
<pre class="ruby">[<span class="ruby-constant">Process</span>.<span class="ruby-identifier">gid</span>, <span class="ruby-constant">Process</span>.<span class="ruby-identifier">egid</span>] <span class="ruby-comment">#=> [0, 33]</span>
<span class="ruby-constant">Process</span><span class="ruby-operator">::</span><span class="ruby-constant">GID</span>.<span class="ruby-identifier">re_exchange</span> <span class="ruby-comment">#=> 0</span>
[<span class="ruby-constant">Process</span>.<span class="ruby-identifier">gid</span>, <span class="ruby-constant">Process</span>.<span class="ruby-identifier">egid</span>] <span class="ruby-comment">#=> [33, 0]</span>
</pre>
<div class="method-source-code" id="re_exchange-source">
<pre>static VALUE
p_gid_exchange(VALUE obj)
{
rb_gid_t gid;
#if defined(HAVE_SETRESGID) || (defined(HAVE_SETREGID) && !defined(OBSOLETE_SETREGID))
rb_gid_t egid;
#endif
check_gid_switch();
gid = getgid();
#if defined(HAVE_SETRESGID) || (defined(HAVE_SETREGID) && !defined(OBSOLETE_SETREGID))
egid = getegid();
#endif
#if defined(HAVE_SETRESGID)
if (setresgid(egid, gid, gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
#elif defined(HAVE_SETREGID) && !defined(OBSOLETE_SETREGID)
if (setregid(egid,gid) < 0) rb_sys_fail(0);
SAVED_GROUP_ID = gid;
#else
rb_notimplement();
#endif
return GIDT2NUM(gid);
}</pre>
</div>
</div>
</div>
<div id="method-c-re_exchangeable-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
Process::GID.re_exchangeable? → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if the real and effective group IDs of a process may be exchanged on the current platform.</p>
<div class="method-source-code" id="re_exchangeable-3F-source">
<pre>static VALUE
p_gid_exchangeable(VALUE _)
{
#if defined(HAVE_SETRESGID)
return Qtrue;
#elif defined(HAVE_SETREGID) && !defined(OBSOLETE_SETREGID)
return Qtrue;
#else
return Qfalse;
#endif
}</pre>
</div>
</div>
</div>
<div id="method-c-rid" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
gid → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
Process::GID.rid → integer
</span>
</div>
<div class="method-heading">
<span class="method-callseq">
Process::Sys.getgid → integer
</span>
</div>
<div class="method-description">
<p>Returns the (real) group ID for this process.</p>
<pre class="ruby"><span class="ruby-constant">Process</span>.<span class="ruby-identifier">gid</span> <span class="ruby-comment">#=> 500</span>
</pre>
<div class="method-source-code" id="rid-source">
<pre>static VALUE
proc_getgid(VALUE obj)
{
rb_gid_t gid = getgid();
return GIDT2NUM(gid);
}</pre>
</div>
</div>
</div>
<div id="method-c-sid_available-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
Process::GID.sid_available? → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <code>true</code> if the current platform has saved group ID functionality.</p>
<div class="method-source-code" id="sid_available-3F-source">
<pre>static VALUE
p_gid_have_saved_id(VALUE _)
{
#if defined(HAVE_SETRESGID) || defined(HAVE_SETEGID) || defined(_POSIX_SAVED_IDS)
return Qtrue;
#else
return Qfalse;
#endif
}</pre>
</div>
</div>
</div>
<div id="method-c-switch" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
Process::GID.switch → integer
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
Process::GID.switch {|| block} → object
</span>
</div>
<div class="method-description">
<p>Switch the effective and real group IDs of the current process. If a <em>block</em> is given, the group IDs will be switched back after the block is executed. Returns the new effective group ID if called without a block, and the return value of the block if one is given.</p>
<div class="method-source-code" id="switch-source">
<pre>static VALUE
p_gid_switch(VALUE obj)
{
rb_gid_t gid, egid;
check_gid_switch();
gid = getgid();
egid = getegid();
if (gid != egid) {
proc_setegid(obj, GIDT2NUM(gid));
if (rb_block_given_p()) {
under_gid_switch = 1;
return rb_ensure(rb_yield, Qnil, p_gid_sw_ensure, SAVED_GROUP_ID);
}
else {
return GIDT2NUM(egid);
}
}
else if (egid != SAVED_GROUP_ID) {
proc_setegid(obj, GIDT2NUM(SAVED_GROUP_ID));
if (rb_block_given_p()) {
under_gid_switch = 1;
return rb_ensure(rb_yield, Qnil, p_gid_sw_ensure, egid);
}
else {
return GIDT2NUM(gid);
}
}
else {
rb_syserr_fail(EPERM, 0);
}
UNREACHABLE_RETURN(Qnil);
}</pre>
</div>
</div>
</div>
</section>
</section>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.2.1.1.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>