diff options
Diffstat (limited to 'static/freebsd/man9/ucred.9 4.html')
| -rw-r--r-- | static/freebsd/man9/ucred.9 4.html | 188 |
1 files changed, 0 insertions, 188 deletions
diff --git a/static/freebsd/man9/ucred.9 4.html b/static/freebsd/man9/ucred.9 4.html deleted file mode 100644 index 81a93db8..00000000 --- a/static/freebsd/man9/ucred.9 4.html +++ /dev/null @@ -1,188 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">UCRED(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">UCRED(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">ucred</code>, <code class="Nm">crget</code>, - <code class="Nm">crhold</code>, <code class="Nm">crfree</code>, - <code class="Nm">crcopy</code>, <code class="Nm">crdup</code>, - <code class="Nm">cru2x</code> — <span class="Nd">functions related to - user credentials</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/param.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/ucred.h</a>></code></p> -<p class="Pp"><var class="Ft">struct ucred *</var> - <br/> - <code class="Fn">crget</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> -<p class="Pp"><var class="Ft">struct ucred *</var> - <br/> - <code class="Fn">crhold</code>(<var class="Fa" style="white-space: nowrap;">struct - ucred *cr</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">crfree</code>(<var class="Fa" style="white-space: nowrap;">struct - ucred *cr</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">crcopy</code>(<var class="Fa" style="white-space: nowrap;">struct - ucred *dest</var>, <var class="Fa" style="white-space: nowrap;">struct ucred - *src</var>);</p> -<p class="Pp"><var class="Ft">struct ucred *</var> - <br/> - <code class="Fn">crcopysafe</code>(<var class="Fa" style="white-space: nowrap;">struct - proc *p</var>, <var class="Fa" style="white-space: nowrap;">struct ucred - *cr</var>);</p> -<p class="Pp"><var class="Ft">struct ucred *</var> - <br/> - <code class="Fn">crdup</code>(<var class="Fa" style="white-space: nowrap;">struct - ucred *cr</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">crsetgroups</code>(<var class="Fa" style="white-space: nowrap;">struct - ucred *cr</var>, <var class="Fa" style="white-space: nowrap;">int - ngrp</var>, <var class="Fa" style="white-space: nowrap;">gid_t - *groups</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">crsetgroups_and_egid</code>(<var class="Fa" style="white-space: nowrap;">struct - ucred *cr</var>, <var class="Fa" style="white-space: nowrap;">int - ngrp</var>, <var class="Fa" style="white-space: nowrap;">gid_t - *groups</var>, <var class="Fa" style="white-space: nowrap;">gid_t - default_egid</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">cru2x</code>(<var class="Fa" style="white-space: nowrap;">struct - ucred *cr</var>, <var class="Fa" style="white-space: nowrap;">struct xucred - *xcr</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">ucred</code> family of functions is used to - manage user credential structures (<var class="Vt">struct ucred</var>) - within the kernel.</p> -<p class="Pp" id="crget">The - <a class="permalink" href="#crget"><code class="Fn">crget</code></a>() - function allocates memory for a new structure, sets its reference count to - 1, and initializes its lock.</p> -<p class="Pp" id="crhold">The - <a class="permalink" href="#crhold"><code class="Fn">crhold</code></a>() - function increases the reference count on the credential.</p> -<p class="Pp" id="crfree">The - <a class="permalink" href="#crfree"><code class="Fn">crfree</code></a>() - function decreases the reference count on the credential. If the count drops - to 0, the storage for the structure is freed.</p> -<p class="Pp" id="crcopy">The - <a class="permalink" href="#crcopy"><code class="Fn">crcopy</code></a>() - function copies the contents of the source (template) credential into the - destination template. The <var class="Vt">uidinfo</var> structure within the - destination is referenced by calling <a class="Xr">uihold(9)</a>.</p> -<p class="Pp" id="crcopysafe">The - <a class="permalink" href="#crcopysafe"><code class="Fn">crcopysafe</code></a>() - function copies the current credential associated with the process - <var class="Fa">p</var> into the newly allocated credential - <var class="Fa">cr</var>. The process lock on <var class="Fa">p</var> must - be held and will be dropped and reacquired as needed to allocate group - storage space in <var class="Fa">cr</var>.</p> -<p class="Pp" id="crdup">The - <a class="permalink" href="#crdup"><code class="Fn">crdup</code></a>() - function allocates memory for a new structure and copies the contents of - <var class="Fa">cr</var> into it. The actual copying is performed by - <code class="Fn">crcopy</code>().</p> -<p class="Pp" id="crsetgroups">The - <a class="permalink" href="#crsetgroups"><code class="Fn">crsetgroups</code></a>() - function sets the <var class="Va">cr_groups</var> and - <var class="Va">cr_ngroups</var> variables representing the supplementary - groups, allocating space as needed. It also truncates the group list to the - current maximum number of groups. The - <a class="permalink" href="#crsetgroups_and_egid"><code class="Fn" id="crsetgroups_and_egid">crsetgroups_and_egid</code></a>() - function is similar, but interprets separately the first group of - <var class="Va">groups</var> as the effective GID to set, only setting the - subsequent groups as supplementary ones. It will use - <var class="Va">default_egid</var> as the new effective GID if - <var class="Va">groups</var> is empty. No other mechanism should be used to - modify the <var class="Va">cr_groups</var> array.</p> -<p class="Pp" id="cru2x">The - <a class="permalink" href="#cru2x"><code class="Fn">cru2x</code></a>() - function converts a <var class="Vt">ucred</var> structure to an - <var class="Vt">xucred</var> structure. That is, it copies data from - <var class="Fa">cr</var> to <var class="Fa">xcr</var>; it ignores fields in - the former that are not present in the latter (e.g., - <var class="Va">cr_uidinfo</var>), and appropriately sets fields in the - latter that are not present in the former (e.g., - <var class="Va">cr_version</var>).</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN - VALUES</a></h1> -<p class="Pp"><code class="Fn">crget</code>(), <code class="Fn">crhold</code>(), - <code class="Fn">crdup</code>(), and <code class="Fn">crcopysafe</code>() - all return a pointer to a <var class="Vt">ucred</var> structure.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="USAGE_NOTES"><a class="permalink" href="#USAGE_NOTES">USAGE - NOTES</a></h1> -<p class="Pp">As of <span class="Ux">FreeBSD 5.0</span>, the - <var class="Vt">ucred</var> structure contains extensible fields. This means - that the correct protocol must always be followed to create a fresh and - writable credential structure: new credentials must always be derived from - existing credentials using <code class="Fn">crget</code>(), - <code class="Fn">crcopy</code>(), and - <code class="Fn">crcopysafe</code>().</p> -<p class="Pp">In the common case, credentials required for access control - decisions are used in a read-only manner. In these circumstances, the thread - credential <var class="Va">td_ucred</var> should be used, as it requires no - locking to access safely, and remains stable for the duration of the call - even in the face of a multi-threaded application changing the process - credentials from another thread.</p> -<p class="Pp">During a process credential update, the process lock must be held - across check and update, to prevent race conditions. The process credential, - <var class="Va">td->td_proc->p_ucred</var>, must be used both for - check and update. If a process credential is updated during a system call - and checks against the thread credential are to be made later during the - same system call, the thread credential must also be refreshed from the - process credential so as to prevent use of a stale value. To avoid this - scenario, it is recommended that system calls updating the process - credential be designed to avoid other authorization functions.</p> -<p class="Pp" id="crget~2">If temporarily elevated privileges are required for a - thread, the thread credential can be replaced for the duration of an - activity, or for the remainder of the system call. However, as a thread - credential is often shared, appropriate care should be taken to make sure - modifications are made to a writable credential through the use of - <a class="permalink" href="#crget~2"><code class="Fn">crget</code></a>() and - <code class="Fn">crcopy</code>().</p> -<p class="Pp" id="never">Caution should be exercised when checking authorization - for a thread or process perform an operation on another thread or process. - As a result of temporary elevation, the target thread credential should - <a class="permalink" href="#never"><i class="Em">never</i></a> be used as - the target credential in an access control decision: the process credential - associated with the thread, - <var class="Va">td->td_proc->p_ucred</var>, should be used instead. - For example, <a class="Xr">p_candebug(9)</a> accepts a target process, not a - target thread, for access control purposes.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">uihold(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">This manual page was written by <span class="An">Chad David</span> - <<a class="Mt" href="mailto:davidc@acns.ab.ca">davidc@acns.ab.ca</a>>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">August 29, 2025</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |