Date: Sat, 05 May 2001 17:12:07 -0700 From: Dima Dorfman <dima@unixfreak.org> To: hackers@freebsd.org Subject: Man page for struct ucred/xucred Message-ID: <20010506001207.3A4903E0B@bazooka.unixfreak.org>
next in thread | raw e-mail | index | archive | help
I wrote a rather short manual page about struct ucred, struct xucred, and the routines used to manipulate the former. There really isn't all that much to write about, but I thought it'd be useful to have something that describes the cr* functions even though the code isn't hard to find or particularly difficult to understand. In addition it mentions that struct ucred shouldn't be exported to the userland; it may seem obvious, but implicit traditions are rarely a good thing. While writing this I also noticed that there's no routine to make a struct xucred from a struct ucred. Should there be one? I think so. Perhaps something with an API of void crxucred(struct ucred *cr, struct xucred *xcr); would be useful. Diff against /dev/null for the man page attached. Comments? Suggestions? Thanks, Dima Dorfman dima@unixfreak.org --- /dev/null Sat May 5 16:12:17 2001 +++ ucred.9 Sat May 5 16:49:03 2001 @@ -0,0 +1,108 @@ +.\" +.\" Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 5, 2001 +.Dt UCRED 9 +.Os +.Sh NAME +.Nm ucred , +.Nm xucred +.Nd structures to describe user credentials in the kernel and userland +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/ucred.h> +.Ft struct ucred * +.Fn crget "void" +.Ft void +.Fn crhold "struct ucred *cr" +.Ft void +.Fn crfree "struct ucred *cr" +.Ft struct ucred * +.Fn crcopy "struct ucred *cr" +.Ft struct ucred * +.Fn crdup "struct ucred *cr" +.Sh DESCRIPTION +The +.Ft ucred +structure describes the user credentials within the kernel. +The +.Ft xucred +structure describes the same user credentials in the userland. +A +.Ft struct ucred +should never be exported to the userland; +instead, it should be converted into a +.Ft struct xucred . +.Pp +The following kernel functions exist to facilitate the maintenance of +user credentials structures within the kernel. +.Pp +.Bl -tag -width crcopy +.It Fn crget +Allocate the memory for and return a zeroed structure. +The reference count is set to 1. +.It Fn crhold +Increment the reference count of +.Fa cr . +.It Fn crfree +Decrement the reference count of +.Fa cr . +If the reference count drops to 0, +the memory for the structure is deallocated. +.It Fn crcopy +Make a copy and subsequently free +.Fa cr . +If the reference count was 1, +this is equivilent to just assigning the address of +.Fa cr +to the new variable. +Otherwise, it is equivilent to calling +.Fn crdup +and +.Fn crfree . +.It Fn crdup +Allocate memory for a new structure and populate its contents with +those from +.Fa cr . +The reference count of the new structure is set to 1. +.El +.Sh NOTES +The +.Dv cr_uid +member of +.Ft struct ucred +should never be inspected directly to determine whether the user +associated with this credentials structure should have superuser +privileges. +Instead, one of the +.Xr suser 9 +functions should be used. +.Sh BUGS +There is no routine to convert a +.Ft struct ucred +into a +.Ft struct xucred . To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-hackers" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010506001207.3A4903E0B>