xnu-1228.7.58.tar.gz

[apple/xnu.git] / bsd / man / man2 / connect.2

diff --git a/bsd/man/man2/connect.2 b/bsd/man/man2/connect.2
index e06e59fc534607044127d903c878176c6baef1d4..8b32e6c2cd27df17512ad128666d8ce3a11f4c27 100644 (file)
--- a/bsd/man/man2/connect.2
+++ b/bsd/man/man2/connect.2
@@ -43,10 +43,14 @@
 .Fd #include <sys/types.h>
 .Fd #include <sys/socket.h>
 .Ft int
 .Fd #include <sys/types.h>
 .Fd #include <sys/socket.h>
 .Ft int

-.Fn connect "int s" "const struct sockaddr *name" "int namelen"
+.Fo connect
+.Fa "int socket"
+.Fa "const struct sockaddr *address"
+.Fa "socklen_t address_len"
+.Fc

 .Sh DESCRIPTION
 The parameter
 .Sh DESCRIPTION
 The parameter

-.Fa s
+.Fa socket

 is a socket.
 If it is of type
 .Dv SOCK_DGRAM ,
 is a socket.
 If it is of type
 .Dv SOCK_DGRAM ,


@@ -58,10 +62,11 @@ If the socket is of type
 this call attempts to make a connection to
 another socket.
 The other socket is specified by
 this call attempts to make a connection to
 another socket.
 The other socket is specified by

-.Fa name ,
+.Fa address ,

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

+.Pp

 Each communications space interprets the
 Each communications space interprets the

-.Fa name
+.Fa address

 parameter in its own way.
 Generally, stream sockets may successfully
 .Fn connect
 parameter in its own way.
 Generally, stream sockets may successfully
 .Fn connect


@@ -71,43 +76,60 @@ multiple times to change their association.
 Datagram sockets may dissolve the association
 by connecting to an invalid address, such as a null address 
 or an address with 
 Datagram sockets may dissolve the association
 by connecting to an invalid address, such as a null address 
 or an address with 

-the address family set to AF_UNPSEC (the error 
-EAFNOSUPPORT will be harmlessly returned).
+the address family set to 
+.Dv AF_UNSPEC 
+(the error 
+.Dv EAFNOSUPPORT 
+will be harmlessly returned).

 .Sh RETURN VALUES
 .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 .
+Upon successful completion, a value of 0 is returned.
+Otherwise, a value of -1 is returned and the global integer variable
+.Va errno
+is set to indicate the error.

 .Sh ERRORS
 The
 .Fn connect
 .Sh ERRORS
 The
 .Fn connect

-call fails if:
+system call will fail if:

 .Bl -tag -width Er
 .Bl -tag -width Er

-.It Bq Er EBADF
-.Fa S
-is not a valid descriptor.
-.It Bq Er ENOTSOCK
-.Fa S
-is a descriptor for a file, not a socket.
+.\" ==========
+.It Bq Er EACCES
+The destination address is a broadcast address and the 
+socket option 
+.Dv SO_BROADCAST 
+is not set.
+.\" ==========
+.It Bq Er EADDRINUSE
+The address is already in use.
+.\" ==========

 .It Bq Er EADDRNOTAVAIL
 The specified address is not available on this machine.
 .It Bq Er EADDRNOTAVAIL
 The specified address is not available on this machine.

+.\" ==========

 .It Bq Er EAFNOSUPPORT
 Addresses in the specified address family cannot be used with this socket.
 .It Bq Er EAFNOSUPPORT
 Addresses in the specified address family cannot be used with this socket.

-.It Bq Er EISCONN
-The socket is already connected.
-.It Bq Er ETIMEDOUT
-Connection establishment timed out without establishing a connection.
+.\" ==========
+.It Bq Er EALREADY
+The socket is non-blocking
+and a previous connection attempt
+has not yet been completed.
+.\" ==========
+.It Bq Er EBADF
+.Fa socket
+is not a valid descriptor.
+.\" ==========

 .It Bq Er ECONNREFUSED
 .It Bq Er ECONNREFUSED

-The attempt to connect was forcefully rejected.
-.It Bq Er ENETUNREACH
-The network isn't reachable from this host.
-.It Bq Er EADDRINUSE
-The address is already in use.
+The attempt to connect was ignored
+(because the target is not listening for connections)
+or explicitly rejected.
+.\" ==========

 .It Bq Er EFAULT
 The
 .It Bq Er EFAULT
 The

-.Fa name
+.Fa address

 parameter specifies an area outside
 the process address space.
 parameter specifies an area outside
 the process address space.

+.\" ==========
+.It Bq Er EHOSTUNREACH
+The target host cannot be reached (e.g., down, disconnected).
+.\" ==========

 .It Bq Er EINPROGRESS
 The socket is non-blocking 
 and the connection cannot
 .It Bq Er EINPROGRESS
 The socket is non-blocking 
 and the connection cannot


@@ -115,37 +137,90 @@ be completed immediately.
 It is possible to
 .Xr select 2
 for completion by selecting the socket for writing.
 It is possible to
 .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.
+.\" ==========
+.It Bq Er EINTR
+Its execution was interrupted by a signal.
+.\" ==========
+.It Bq Er EINVAL
+An invalid argument was detected
+(e.g.,
+.Fa address_len
+is not valid for the address family,
+the specified address family is invalid).
+.\" ==========
+.It Bq Er EISCONN
+The socket is already connected.
+.\" ==========
+.It Bq Er ENETDOWN
+The local network interface is not functioning.
+.\" ==========
+.It Bq Er ENETUNREACH
+The network isn't reachable from this host.
+.\" ==========
+.It Bq Er ENOBUFS
+The system call was unable to allocate a needed memory buffer.
+.\" ==========
+.It Bq Er ENOTSOCK
+.Fa socket
+is not a file descriptor for a socket.
+.\" ==========
+.It Bq Er EOPNOTSUPP
+Because
+.Fa socket
+is listening, no connection is allowed.
+.\" ==========
+.It Bq Er EPROTOTYPE
+.Fa address
+has a different type than the socket
+that is bound to the specified peer address.
+.\" ==========
+.It Bq Er ETIMEDOUT
+Connection establishment timed out without establishing a connection.

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

-.It Bq Er ENOTDIR
-A component of the path prefix is not a directory.
+.\" ==========
+.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 EIO
+An I/O error occurred while reading from or writing to the file system.
+.\" ==========
+.It Bq Er ELOOP
+Too many symbolic links were encountered in translating the pathname.
+This is taken to be indicative of a looping symbolic link.
+.\" ==========

 .It Bq Er ENAMETOOLONG
 A component of a pathname exceeded 
 .Dv {NAME_MAX}
 characters, or an entire path name exceeded 
 .Dv {PATH_MAX}
 characters.
 .It Bq Er ENAMETOOLONG
 A component of a pathname exceeded 
 .Dv {NAME_MAX}
 characters, or an entire path name exceeded 
 .Dv {PATH_MAX}
 characters.

+.\" ==========

 .It Bq Er ENOENT
 The named socket does not exist.
 .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.
+.\" ==========
+.It Bq Er ENOTDIR
+A component of the path prefix is not a directory.

 .El
 .El

+.Sh LEGACY SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/socket.h>
+.Pp
+The include file
+.In sys/types.h
+is necessary.

 .Sh SEE ALSO
 .Xr accept 2 ,
 .Sh SEE ALSO
 .Xr accept 2 ,

+.Xr getsockname 2 ,

 .Xr select 2 ,
 .Xr socket 2 ,
 .Xr select 2 ,
 .Xr socket 2 ,

-.Xr getsockname 2
+.Xr compat 5

 .Sh HISTORY
 The
 .Fn connect
 .Sh HISTORY
 The
 .Fn connect