no SCCS file; new copyright; att/bsd/shared

[unix-history] / usr / src / lib / libc / sys / connect.2

diff --git a/usr/src/lib/libc/sys/connect.2 b/usr/src/lib/libc/sys/connect.2
index 868c3bb..b86c8e2 100644 (file)
--- a/usr/src/lib/libc/sys/connect.2
+++ b/usr/src/lib/libc/sys/connect.2
@@ -1,87 +1,121 @@
-.\" Copyright (c) 1983 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1983 The Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.\"    @(#)connect.2   6.1 (Berkeley) %G%
+.\" %sccs.include.redist.man%

 .\"
 .\"

-.TH CONNECT 2 ""
-.UC 5
-.SH NAME
-connect \- initiate a connection on a socket
-.SH SYNOPSIS
-.nf
-.ft B
-#include <sys/types.h>
-#include <sys/socket.h>
-.PP
-.ft B
-connect(s, name, namelen)
-int s;
-struct sockaddr *name;
-int namelen;
-.fi
-.SH DESCRIPTION
+.\"     @(#)connect.2  6.9 (Berkeley) %G%
+.\"
+.Dd 
+.Dt CONNECT 2
+.Os BSD 4.2
+.Sh NAME
+.Nm connect
+.Nd initiate a connection on a socket
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/socket.h>
+.Ft int
+.Fn connect "int s" "struct sockaddr *name" "int namelen"
+.Sh DESCRIPTION

 The parameter
 The parameter

-.I s
+.Fa s

 is a socket.
 is a socket.

-If it is of type SOCK_DGRAM,
-then this call permanently specifies the peer to which
-datagrams are to be sent;
-if it is of type SOCK_STREAM,
-then this call attempts to make a connection to
+If it is of type
+.Dv SOCK_DGRAM ,
+this call specifies the peer with which the socket is to be associated;
+this address is that to which datagrams are to be sent,
+and the only address from which datagrams are to be received.
+If the socket is of type
+.Dv SOCK_STREAM ,
+this call attempts to make a connection to

 another socket.
 The other socket is specified by
 another socket.
 The other socket is specified by

-.I name
+.Fa name ,

 which is an address in the communications space of the socket.
 Each communications space interprets the
 which is an address in the communications space of the socket.
 Each communications space interprets the

-.I name
+.Fa name

 parameter in its own way.
 parameter in its own way.

-.SH "RETURN VALUE
-If the connection or binding succeeds, then 0 is returned.
-Otherwise a \-1 is returned, and a more specific error
-code is stored in \fIerrno\fP.
-.SH "ERRORS
-The call fails if:
-.TP 20
-[EBADF]
-.I S
+Generally, stream sockets may successfully
+.Fn connect
+only once; datagram sockets may use
+.Fn connect
+multiple times to change their association.
+Datagram sockets may dissolve the association
+by connecting to an invalid address, such as a null address.
+.Sh RETURN VALUES
+If the connection or binding succeeds, 0 is returned.
+Otherwise a -1 is returned, and a more specific error
+code is stored in
+.Va errno .
+.Sh ERRORS
+The
+.Fn connect
+call fails if:
+.Bl -tag -width EADDRNOTAVAILABB
+.It Bq Er EBADF
+.Fa S

 is not a valid descriptor.
 is not a valid descriptor.

-.TP 20
-[ENOTSOCK]
-.I S
+.It Bq Er ENOTSOCK
+.Fa S

 is a descriptor for a file, not a socket.
 is a descriptor for a file, not a socket.

-.TP 20
-[EADDRNOTAVAIL]
+.It Bq Er EADDRNOTAVAIL

 The specified address is not available on this machine.
 The specified address is not available on this machine.

-.TP 20
-[EAFNOSUPPORT]
+.It Bq Er EAFNOSUPPORT

 Addresses in the specified address family cannot be used with this socket.
 Addresses in the specified address family cannot be used with this socket.

-.TP 20
-[EISCONN]
+.It Bq Er EISCONN

 The socket is already connected.
 The socket is already connected.

-.TP 20
-[ETIMEDOUT]
+.It Bq Er ETIMEDOUT

 Connection establishment timed out without establishing a connection.
 Connection establishment timed out without establishing a connection.

-.TP 20
-[ECONNREFUSED]
+.It Bq Er ECONNREFUSED

 The attempt to connect was forcefully rejected.
 The attempt to connect was forcefully rejected.

-.TP 20
-[ENETUNREACH]
+.It Bq Er ENETUNREACH

 The network isn't reachable from this host.
 The network isn't reachable from this host.

-.TP 20
-[EADDRINUSE]
+.It Bq Er EADDRINUSE

 The address is already in use.
 The address is already in use.

-.TP 20
-[EFAULT]
-The \fIname\fP parameter specifies an area outside
+.It Bq Er EFAULT
+The
+.Fa name
+parameter specifies an area outside

 the process address space.
 the process address space.

-.TP 20
-[EWOULDBLOCK]
-The socket is non-blocking and the
+.It Bq Er EINPROGRESS
+The socket is non-blocking 

 and the connection cannot
 be completed immediately.
 It is possible to
 and the connection cannot
 be completed immediately.
 It is possible to

-.IR select (2)
-the socket while it is connecting by selecting it for writing.
-.SH SEE ALSO
-accept(2), select(2), socket(2), getsockname(2)
+.Xr select 2
+for completion by selecting the socket for writing.
+.It Bq Er EALREADY
+The socket is non-blocking
+and a previous connection attempt
+has not yet been completed.
+.El
+.Pp
+The following errors are specific to connecting names in the UNIX domain.
+These errors may not apply in future versions of the UNIX IPC domain.
+.Bl -tag -width EADDRNOTAVAILABB
+.It Bq Er ENOTDIR
+A component of the path prefix is not a directory.
+.It Bq Er EINVAL
+The pathname contains a character with the high-order bit set.
+.It Bq Er ENAMETOOLONG
+A component of a pathname exceeded 255 characters,
+or an entire path name exceeded 1023 characters.
+.It Bq Er ENOENT
+The named socket does not exist.
+.It Bq Er EACCES
+Search permission is denied for a component of the path prefix.
+.It Bq Er EACCES
+Write access to the named socket is denied.
+.It Bq Er ELOOP
+Too many symbolic links were encountered in translating the pathname.
+.El
+.Sh SEE ALSO
+.Xr accept 2 ,
+.Xr select 2 ,
+.Xr socket 2 ,
+.Xr getsockname 2
+.Sh HISTORY
+The
+.Nm
+function call appeared in
+.Bx 4.2 .