=head1 NAME

gspool_getspu - retrieve the permissions for a user

=head1 SYNOPSIS

=for man
\&\fB#include <gspool.h>\fR
.PP

=for html
<STRONG>#include &lt;gspool.h&gt;</STRONG>
<BR>

B<int getspu(const int >I<fd>, B<const char *>I<user>B<, struct apispdet *>I<res>B<)>

=head1 DESCRIPTION

The function B<gspool_getspu()> is used to retrieve the defaults for a particular user

I<fd> is a file descriptor previously returned by B<gspool_open>

I<user> is a pointer to the username of the user details being retrieved.

I<res> is a descriptor, which upon return will contain the details of
user. The structure C<apispdet> is defined in the file F<gsapi.h>, and
contains the following fields:

=for html
<A NAME="Apispdet_def"></a>
<div class=indtab>
<table border=0 cellpadding=1 cellspacing=0 summary="spdet">
<tr>
<th align=left class=dense>Type</th>
<th align=left class=dense>Field</th>
<th align=left class=dense>Description</th>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>spu_isvalid</span></td>
<td class=dense>Valid user ID</td>
</tr>
<tr>
<td class=dense><span class=FileName>char []</span></td>
<td class=dense><span class=FileName>spu_resvd1</span></td>
<td class=dense>Reserved</td>
</tr>
<tr>
<td class=dense><span class=FileName>int_ugid_t</span></td>
<td class=dense><span class=FileName>spu_user</span></td>
<td class=dense>User ID</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>spu_minp</span></td>
<td class=dense>Minimum priority</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>spu_maxp</span></td>
<td class=dense>Maximum priority</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>spu_defp</span></td>
<td class=dense>Default priority</td>
</tr>
<tr>
<td class=dense><span class=FileName>char []</span></td>
<td class=dense><span class=FileName>spu_form</span></td>
<td class=dense>Default form type</td>
</tr>
<tr>
<td class=dense><span class=FileName>char []</span></td>
<td class=dense><span class=FileName>spu_formallow</span></td>
<td class=dense>Allowed form type pattern</td>
</tr>
<tr>
<td class=dense><span class=FileName>char []</span></td>
<td class=dense><span class=FileName>spu_ptr</span></td>
<td class=dense>Default printer</td>
</tr>
<tr>
<td class=dense><span class=FileName>char []</span></td>
<td class=dense><span class=FileName>spu_ptrallow</span></td>
<td class=dense>Allowed printer pattern</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned long</span></td>
<td class=dense><span class=FileName>spu_flgs</span></td>
<td class=dense>Privilege flag</td>
</tr>
<tr>
<td class=dense><span class=FileName>classcode_t</span></td>
<td class=dense><span class=FileName>spu_class</span></td>
<td class=dense>Class of printers</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>spu_cps</span></td>
<td class=dense>Maximum copies allowed</td>
</tr>
<tr>
<td class=dense><span class=FileName>unsigned char</span></td>
<td class=dense><span class=FileName>spu_version</span></td>
<td class=dense>Release of GNUspool</td>
</tr>
</table>
</div>

=for man
.Ip "unsigned char spu_isvalid" 8
Valid user ID
.Ip "char spu_resvd1[]" 8
Reserved
.Ip "int_ugid_t spu_user" 8
User ID
Minimum priority
.Ip "unsigned char spu_maxp" 8
Maximum priority
.Ip "unsigned char spu_defp" 8
Default priority
.Ip "char spu_form[]" 8
Default form type
.Ip "char spu_formallow[]" 8
Allowed form type pattern
.Ip "char spu_ptr[]" 8
Default printer
.Ip "char spu_ptrallow[]" 8
Allowed printer pattern
.Ip "unsigned long spu_flgs" 8
Privilege flag
.Ip "classcode_t spu_class" 8
Class of printers
.Ip "unsigned char spu_cps" 8
Maximum copies allowed

The C<spu_flgs> field of I<res> will contain a combination of the
following:

=for html
<div class=indtab>
<table border=0 cellpadding=1 cellspacing=0 summary="spu_flgs">
<tr>
<td class=dense><span class=FileName>PV_ADMIN</span></td>
<td class=dense>Administrator (edit admin file)</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_SSTOP</span></td>
<td class=dense>Can run sstop (can stop scheduler)</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_FORMS</span></td>
<td class=dense>Can use other forms than default</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_CPRIO</span></td>
<td class=dense>Can change priority on queue</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_OTHERJ</span></td>
<td class=dense>Can change other users' jobs</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_PRINQ</span></td>
<td class=dense>Can move to printer queue</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_HALTGO</span></td>
<td class=dense>Can halt, restart printer</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_ANYPRIO</span></td>
<td class=dense>Can set any priority on queue</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_CDEFLT</span></td>
<td class=dense>Can change own default priority</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_ADDDEL</span></td>
<td class=dense>Can add/delete printers</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_COVER</span></td>
<td class=dense>Can override class</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_UNQUEUE</span></td>
<td class=dense>Can unqueue jobs</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_VOTHERJ</span></td>
<td class=dense>Can view other jobs not neccesarily edit</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_REMOTEJ</span></td>
<td class=dense>Can access remote jobs</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_REMOTEP</span></td>
<td class=dense>Can access remote printers</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_FREEZEOK</span></td>
<td class=dense>Can save default options</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_ACCESSOK</span></td>
<td class=dense>Can access sub-screens</td>
</tr>
<tr>
<td class=dense><span class=FileName>PV_OTHERP</span></td>
<td class=dense>Can use other printers from default</td>
</tr>
<tr>
<td class=dense><span class=FileName>ALLPRIVS</span></td>
<td class=dense>A combination of all of the above</td>
</tr>
</table>
</div>

=for man
.Ip "PV_ADMIN" 8
Administrator (edit admin file)
.Ip "PV_SSTOP" 8
Can run sstop (can stop scheduler)
.Ip "PV_FORMS" 8
Can use other forms than default
.Ip "PV_CPRIO" 8
Can change priority on queue
.Ip "PV_OTHERJ" 8
Can change other users' jobs
.Ip "PV_PRINQ" 8
Can move to printer queue
.Ip "PV_HALTGO" 8
Can halt, restart printer
.Ip "PV_ANYPRIO" 8
Can set any priority on queue
.Ip "PV_CDEFLT" 8
Can change own default priority
.Ip "PV_ADDDEL" 8
Can add/delete printers
.Ip "PV_COVER" 8
Can override class
.Ip "PV_UNQUEUE" 8
Can unqueue jobs
.Ip "PV_VOTHERJ" 8
Can view other jobs not neccesarily edit
.Ip "PV_REMOTEJ" 8
Can access remote jobs
.Ip "PV_REMOTEP" 8
Can access remote printers
.Ip "PV_FREEZEOK" 8
Can save default options
.Ip "PV_ACCESSOK" 8
Can access sub-screens
.Ip "PV_OTHERP" 8
Can use other printers from default
.IP "ALLPRIVS" 8
A combination of all of the above

=head1 RETURN VALUES

=for html
<P>The function returns 0 if successful otherwise one of the error codes
<A HREF="TxtAPI-3.html#Error_codes">listed in Chapter 3</A>.</P>

=for man
The function \fBgspool_getspu()\fR returns 0 if successful otherwise one
of the following codes:
.Ip "GSPOOL_UNKNOWN_USER" 8
Invalid user name
.Ip "GSPOOL_INVALID_FD" 8
Invalid File descriptor
.Ip "GSPOOL_BADWRITE" 8
failure writing to the network
.Ip "GSPOOL_BADREAD" 8
failure reading from the network
.Ip "GSPOOL_NOPERM" 8
The user does not have permission

=head1 EXAMPLE

An example to view the privileges of user C<mark>:

 int     fd, ret;
 struct apispdet res;

 fd = gspool_open("myhost", (char *)0, 0);
 if (fd < 0) { /* error handling */
     ...
 }

 ret = gspool_getspu(fd, "mark", &res);
 if (ret < 0) { /* error handling */
     ...
 }

 if (res.spu_flags & PV_HALTGO)
     printf("user mark cannot halt printers\n");
 printf("marks maximim priority is %d\n", res.spu_maxp);
 gspool_close(fd);

=head1 SEE ALSO

gspool_getspd(3),
gspool_putspu(3),
gspool_putspd(3).

=head1 COPYRIGHT

Copyright (c) 2009 Free Software Foundation, Inc.
This is free software. You may redistribute copies of it under the
terms of the GNU General Public License
<http://www.gnu.org/licenses/gpl.html>.
There is NO WARRANTY, to the extent permitted by law.

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

## Local Variables:
## mode: nroff
## End:
