=head1 NAME

gspool_ptrfind - get the details of a printer from printer name

=head1 SYNOPSIS

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

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

B<int gspool_ptrfind(const int>
I<fd>B<, const unsigned>
I<flags>B<, const char *>I<name>B<, const netid_t>
I<nid>B<, slotno_t *>I<slot>B<, struct apispptr *>I<ptrd>B<)>

B<int gspool_ptrfindslot(const int>
I<fd>B<, const unsigned>
I<flags>B<, const char *>I<name>B<, const netid_t>
I<nid>B<, slotno_t *>I<slot>B<)>

=head1 DESCRIPTION

The B<gspool_ptrfind()> and B<gspool_ptrfindslot> functions may be used to
find a printer from a given printer name rather than by the slot
number. B<gspool_ptrfind> retrieves the printer description, B<gspool_ptrfindslot>
just retrieves the slot number.

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

I<flags> is zero, or C<GSPOOL_FLAG_LOCALONLY> to ignore remote
printers/hosts, i.e. not local to the server, not the client.

I<name> is the printer name to be searched for.

I<nid> is the network-byte order IP address of the host of the machine
whose printer is to be searched for. This should be correct even if
C<GSPOOL_FLAG_LOCALONLY> is specified.

I<slot> is a pointer to a location in which the slot number of the printer
is placed if the search is successfull. It may be C<NULL> if this is
not required (but this would be almost pointless for B<gspool_ptrfindslot>).

I<ptrd> is a pointer to a field to contain the printer name as defined in
F<gspool.h>.

=for html
<P>The fields in <CODE>struct apispptr</CODE> are defined in the
gspool_ptrread(3) <A HREF="#Apispptr_def">documentation</A>.</P>

=for man
The fields in \fBstruct apispptr\fR are defined in the documentation for
\fIgspool_ptrread\fR\|(3).

=head1 NOTES

If two or more printers on the same host have the same name, then it
is not defined which is returned by B<gspool_ptrfind> and
B<gspool_ptrfindslot>. In such cases, the whole printer list should be
read and the correct one selected.

=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 functions \fBgspool_ptrfind()\fR and \fBgspool_ptrfindslot\fR return 0 if
successful, otherwise one of the following codes:
.Ip "GSPOOL_UNKNOWN_PTR" 8
Printer not found
.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

=head1 SEE ALSO

gspool_ptrlist(3),
gspool_ptradd(3),
gspool_ptrdel(3),
gspool_ptrupd(3),
gspool_ptrread(3),
gspool_ptrmon(3),
gspool_ptrop(3).

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

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