dnet_conn(3dn)
NAME
dnet_conn − connect to the target network object
SYNTAX
#include <sys/types.h>
#include <sys/socket.h>
#include <netdnet/dn.h>
s = int socket
(node,object,type,opt_out,opt_outl,opt_in,opt_inl)
char *node;
char *object;
u_char *opt_out, *opt_in,
int opt_outl, *opt_inl;
ARGUMENTS
node Specifies the address of the string that contains the remote node name and any optional access data. The node string can have one of the following formats:
nodename[/username/password/account]
or
a.n[/username/password/account]
where a is the area number and n is the node number. See the DECnet-ULTRIX User’s and Programmer’s Guide for information about sending access control data.
Node names are matched without regard to case and access control information is passed as supplied with regard to case.
Programs that use dnet_conn will prompt you for a password if you choose to omit the password field in an access control string. The password that you type after the prompt does not echo, which provides account security.
object Specifies the address of the string that contains the target network object. If the object number is zero, you must specify the object by name. If the object number is something other than zero, you can specify the object by name or number, but for remote non-ULTRIX nodes, it is recommended that you specify them by number. If you want to specify a non-zero object by name on a remote non-ULTRIX node, see the documentation for that operating system. The object name and number strings are as follows:
objectname EXAMPLE: "test"
#objectnumber EXAMPLE: "#17"
Case conversion is not performed on object names before they are sent to a destination program.
type Socket type. The DECnet domain currently supports the following socket types:
Stream socket (SOCK_STREAM)
Sequenced Packet socket (SOCK_SEQPACKET)
A value of 0 defaults to a sequenced packet socket (SOCK_SEQPACKET).
opt_out Specifies the address of the outgoing optional user data buffer. The message can be up to 16 bytes in length. If this argument is not required, supply a NULL pointer.
opt_outl Specifies the size of the optional outgoing message. The message can be up to 16 bytes in length. If this argument is not required, supply a NULL value.
opt_in Specifies the address of the buffer that will store the optional incoming message. The message can be up to 16 bytes in length. If this argument is not required, supply a NULL pointer.
opt_inl Specifies the size of the buffer that will store the optional incoming message. On return, this argument contains the actual size of the optional incoming message. If this argument is not required, supply a NULL pointer.
DESCRIPTION
The dnet_conn subroutine establishes a connection to a specified network object on a remote node. Default access control information is used to validate access privileges. You can override the default access control by supplying optional access control information. You can also supply optional connect data.
In addition to or instead of supplying access control information, you can request proxy access on the remote node. The Guide to Network Management contains a full description of proxy access.
The dnet_conn subroutine requests proxy by default. If you do not want outgoing requests to ask for proxy access at the remote systems, your program should set the global variable proxy_requested.
The dnet_conn subroutine creates a socket in the DECnet domain and binds a name to the socket. The bound socket name is the respective user’s log-in name converted to uppercase. This bound name is used as the source name for the outgoing connection only when a program is running as superuser; otherwise the UID in ASCII is used as the source name.
When you write a program that uses dnet_conn, you must subsequently call nerror in order to return any DECnet system errors that occur.
RETURN VALUE
If the subroutine completes successfully, a socket descriptor is returned. If an error occurs, a value of -1 is returned. Additional error detail will be contained in the external variable errno.
DIAGNOSTICS
Using dnet_conn requires you to call nerror, which maps the following standard ULTRIX errors to their equivalent DECnet error messages. The DECnet error text is then written to the standard error file.
Note: The ENOSPC error message is only returned if the client is an ULTRIX system.
errno Value Equivalent DECnet Error Message
[ECONNREFUSED] Connect failed, connection rejected by object
[ENOSPC] Connect failed, insufficient network resources
[EISCONN] Connect failed, insufficient network resources
[ENOBUFS] Connect failed, insufficient network resources
[EADDRINUSE] Connect failed, insufficient network resources
[EADDRNOTAVAIL] Connect failed, unrecognized node name
[ENETDOWN] Connect failed, remote node shutting down
[ESRCH] Connect failed, unrecognized object
[EINVAL] Connect failed, invalid object name format
[ETOOMANYREFS] Connect failed, object too busy
[ENAMETOOLONG] Connect failed, invalid node name format
[EHOSTDOWN] Connect failed, local node shutting down
[EACCES] Connect failed, access control rejected
[ETIMEDOUT] Connect failed, no response from object
[EHOSTUNREACH] Connect failed, node unreachable