=head1 NAME

gbatch_open - open a connection to GNUbatch

gbatch_login - open a connection to GNUbatch with password

gbatch_wlogin - open a connection to GBUbatch with a password mapping user

gbatch_locallogin - open a connection on the local host

gbatch_locallogin_byid - open a connection on the local host, specifying user id

=head1 SYNOPSIS

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

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

B<int gbatch_open(const char *>I<hostname>B<, const char *>I<servname>B<)>

B<int gbatch_open(const char *>I<hostname>B<, const char *>I<servname>B<,
const char *>I<username>B<)>

B<int gbatch_login(const char *>I<hostname>B<, const char *>I<servname>B<,
const char *>I<username>B<, const char *>I<passwd>)>

B<int gbatch_wlogin(const char *>I<hostname>B<, const char *>I<servname>B<,
const char *>I<username>B<, const char *>I<passwd>)>

B<int gbatch_locallogin(const char *>I<servname>B<, const char *>I<username>B)>

B<int gbatch_locallogin_byid(const char *>I<servname>B<, const int_ugid_t>I<uid>B)>

=head1 DESCRIPTION

B<gbatch_open> opens a connection from a a Unix host to the specified server, or from a
predefined windows host set up in the hosts file, with the given user name, which must
be mapped to the correct Unix user name.

B<gbatch_login> logs in with the given user name (mapped to a user name on the server
unless from a registered Unix host) and password.

B<gbatch_wlogin> is as for B<gbatch_login>, but the given user name is always mapped
even if the caller is a Unix server.

B<gbatch_locallogin> logs in on the local host. If the user name is non-null, then this
will be used (if permitted) other than the effective uid.

B<gbatch_locallogin_byid> takes a user id rather than a user name.

In all cases, I<hostname> is the name of the host being connected to or null if the
local server is to be used.

I<servname> may be C<NULL> to use a standard service name, otherwise
an alternative service may be specified.

I<passwd> should be the Unix password on the server or an alternate
I<interface password> set up by gbch-passwd(8).
If this is not required it may be nulls.

Note that more than one connection can be open at
any time with various combinations of user names and hosts.

When finished, close the conection with a call to gbatch_close(3).

=head1 RETURN VALUES

The function a non-negative value if successful, which is the I<file
descriptor> used in various other calls, otherwise an error code as
defined in the include file F<gbatch.h>.

=head1 EXAMPLE

 int fd;
 fd = gbatch_open("myhost", (char *) 0);
 if (fd < 0)  { /* handle error */
 ...
 }
 ...
 gbatch_close(fd)

=head1 SEE ALSO

gbatch_close(3),
gbatch_newgrp(3),
gbatch_setqueue(3),
gbatch_jobmon(3),
gbatch_varmon(3),
gbch-passwd(8).

=head1 COPYRIGHT

Copyright (c) 2012 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:
