=head1 NAME

gspool_ptradd - add a new printer

=head1 SYNOPSIS

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

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

B<int gspool_ptradd(const int>
I<fd>B<, struct apispptr *>I<ptrd>B<)>

=head1 DESCRIPTION

The function B<gspool_ptradd()> is used to create a printer.

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

I<ptrd> is a C<struct apispptr> describing the details of the
printer. It is defined in the file B<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).

Only values for the name, device, formtype, description, local flag, the minimun
and maximum job sizes, the network filter flag and the class code are
accepted. All other parameters are ignored. We suggest that you clear
all fields to zero before starting. Future releases with additional
fields will be guaranteed to default to the existing behaviour if the
additional fields are set to zero.

=head1 RETURN VALUES

B<Xt_ptradd> returns zero if successful, otherwise an error code will
be returned according to the reason for failure.

=for html
<p>Error codes are <A HREF="TxtAPI-3.html#Error_codes">listed in Chapter
3</a>,</p>

=for man
Error codes which might be returned are:
.Ip "GSPOOL_INVALID_FD" 8
Invalid file descriptor
.Ip "GSPOOL_BADWRITE" 8
failure writing to network
.Ip "GSPOOL_BADREAD" 8
failure reading from network
.Ip "GSPOOL_NOPERM" 8
User does not have permission to add printers
.Ip "GSPOOL_BAD_FORM" 8
invalid form type

=head1 EXAMPLE

An example to add a printer called C<hplj1> on device C</dev/tty12> with form type C<a4>

 int fd, ret;
 struct apispptr ptr;

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

 memset((void *) &ptr, '\0', sizeof(ptr));
 ptr.apispp_class = 0xffffffff;
 ptr.apispp_minsize = ptr.apispp_maxsize = 0;
 strcpy(ptr.apispp_ptr, "hplj1");
 strcpy(ptr.apispp_form, "a4");
 strcpy(ptr.apispp_dev, "tty12");
 strcpy(ptr.apispp_comment, "My new printer");
 ret = gspool_ptradd(fd, &ptr);
 if (ret < 0) { /* error handling */
     ...
 }

 gspool_close(fd);

=head1 SEE ALSO

gspool_ptrread(3),
gspool_ptrdel(3),
gspool_ptrfind(3),
gspool_ptrfindslot(3),
gspool_ptrupd(3),
gspool_ptrmon(3),
gspool_ptrop(3).

=head1 AUTHOR

John M Collins, Xi Software Ltd.

=cut

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