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.