gbatch_open(3)

NAME
gbatch_open - open a connection to GNUbatch

gbatch_login - open a connection to GNUbatch with password

SYNOPSIS
#include <gbatch.h>

int gbatch_open(const char *hostname, const char *servname)

int gbatch_open(const char *hostname, const char *servname, const char *username)

int gbatch_login(const char *hostname, const char *servname, const char *username, char *passwd, const int rereg)

DESCRIPTION
The function gbatch_open is used to open a connection to the GNUbatch API. It has two slightly different variants on Windows clients.

The first format, with two arguments, applies to Unix and GNU/Linux applications. The username used is that of the effective userid at the time of the call.

The second format, with three arguments is used on Windows clients and specifies the Unix user name in the call. This may not be acceptable unless the user is on a static IP address client with a default user either matching the user name given or being a user with Write Admin File privilege. So if the /etc/ file has the following in:

 mypc  -  client(myuser)

then "myuser" can invoke this call from client "mypc", or some other user if "myuser" has write admin file privilege. The final privilege will be that of the user logged-in as.

The third format, which should probably be used if in any doubt, supplies a password.

In all cases, hostname is the name of the host being connected to. This may be in any format which can be recognised by the network library routine gethostbyname(3). "localhost" is acceptable if the local server is to be used.

servname may be "NULL" to use a standard service name, otherwise an alternative service may be specified.

username should be a valid user on the server.

passwd should be the Unix password on the server or an alternate interface password set up by gbch-passwd(8). If this is not required it may be nulls. Note that this is a non-"const" array; it will be deliberately filled with nulls as soon as possible after entering the routine to minimise the length of time during which clear-text passwords are on the stack.

rereg, if non-zero, only applies to DHCP clients, and denotes that the Unix host should register the user as the "primary" user for the given client. The main effect of this is to override the user permissions for operations being performed by a concurrent gbch-qw session.

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).

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

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

SEE ALSO
gbatch_close(3), gbatch_newgrp(3), gbatch_setqueue(3), gbatch_jobmon(3), gbatch_varmon(3).

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.