From owner-svn-src-all@FreeBSD.ORG Fri Jun 19 19:16:36 2009 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 07F3A106564A; Fri, 19 Jun 2009 19:16:36 +0000 (UTC) (envelope-from brooks@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id D03EB8FC08; Fri, 19 Jun 2009 19:16:35 +0000 (UTC) (envelope-from brooks@FreeBSD.org) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id n5JJGZVr052989; Fri, 19 Jun 2009 19:16:35 GMT (envelope-from brooks@svn.freebsd.org) Received: (from brooks@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id n5JJGZng052987; Fri, 19 Jun 2009 19:16:35 GMT (envelope-from brooks@svn.freebsd.org) Message-Id: <200906191916.n5JJGZng052987@svn.freebsd.org> From: Brooks Davis Date: Fri, 19 Jun 2009 19:16:35 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r194507 - head/share/man/man9 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 19 Jun 2009 19:16:36 -0000 Author: brooks Date: Fri Jun 19 19:16:35 2009 New Revision: 194507 URL: http://svn.freebsd.org/changeset/base/194507 Log: Document crcopysafe() and crsetgroups(). Reminded by: julian Modified: head/share/man/man9/ucred.9 Modified: head/share/man/man9/ucred.9 ============================================================================== --- head/share/man/man9/ucred.9 Fri Jun 19 19:12:14 2009 (r194506) +++ head/share/man/man9/ucred.9 Fri Jun 19 19:16:35 2009 (r194507) @@ -26,7 +26,7 @@ .\" .\" $FreeBSD$ .\" -.Dd March 3, 2002 +.Dd June 19, 2009 .Dt UCRED 9 .Os .Sh NAME @@ -54,8 +54,12 @@ .Ft void .Fn crcopy "struct ucred *dest" "struct ucred *src" .Ft "struct ucred *" +.Fn crcopysafe "struct proc *p" "struct ucred *cr" +.Ft "struct ucred *" .Fn crdup "struct ucred *cr" .Ft void +.Fn crsetgroups "struct ucred *cr" "int ngrp" "gid_t *groups" +.Ft void .Fn cru2x "struct ucred *cr" "struct xucred *xcr" .Ft void .Fn cred_update_thread "struct thread *td" @@ -98,6 +102,18 @@ by calling .Xr uihold 9 . .Pp The +.Fn crcopysafe +function copies the current credential associated with the process +.Fa p +into the newly allocated credential +.Fa cr . +The process lock on +.Fa p +must be held and will be dropped and reacquired as needed to allocate +group storage space in +.Fa cr . +.Pp +The .Fn crdup function allocates memory for a new structure and copies the contents of @@ -107,6 +123,20 @@ The actual copying is performed by .Fn crcopy . .Pp The +.Fn crsetgroups +function sets the +.Va cr_groups +and +.Va cr_ngroups +variables and allocates space as needed. +It also truncates the group list to the current maximum number of +groups. +No other mechanism should be used to modify the +.Va cr_groups +array except for updating the primary group via assignment to +.Va cr_groups[0] . +.Pp +The .Fn cru2x function converts a .Vt ucred @@ -133,9 +163,10 @@ function sets the credentials of to that of its process, freeing its old credential if required. .Sh RETURN VALUES .Fn crget , -.Fn crhold +.Fn crhold , +.Fn crdup , and -.Fn crdup +.Fn crcopysafe all return a pointer to a .Vt ucred structure. @@ -152,9 +183,10 @@ 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 -.Fn crget +.Fn crget , +.Fn crcopy , and -.Fn crcopy . +.Fn crcopysafe . .Pp In the common case, credentials required for access control decisions are used in a read-only manner.