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

.\" 
.\" Copyright (c) 2012 Apple Inc. All rights reserved.
.\" 
.\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
.\" 
.\" This file contains Original Code and/or Modifications of Original Code
.\" as defined in and that are subject to the Apple Public Source License
.\" Version 2.0 (the 'License'). You may not use this file except in
.\" compliance with the License. The rights granted to you under the License
.\" may not be used to create, or enable the creation or redistribution of,
.\" unlawful or unlicensed copies of an Apple operating system, or to
.\" circumvent, violate, or enable the circumvention or violation of, any
.\" terms of an Apple operating system software license agreement.
.\" 
.\" Please obtain a copy of the License at
.\" http://www.opensource.apple.com/apsl/ and read it before using this file.
.\" 
.\" The Original Code and all software distributed under the License are
.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
.\" Please see the License for the specific language governing rights and
.\" limitations under the License.
.\" 
.\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
.\"
.Dd November 14, 2012
.Dt DISCONNECTX 2
.Os Darwin
.Sh NAME
.Nm disconnectx
.Nd disconnects a connection on a socket
.Sh SYNOPSIS
.Fd #include <sys/socket.h>
.Ft int
.Fo disconnectx
.Fa "int socket"
.Fa "associd_t associd"
.Fa "connid_t connid"
.Fc
.Sh DESCRIPTION
The parameter
.Fa socket
is a socket.  The communication domain of the socket determines the
availability and behavior of
.Fn disconnectx .
In general,
.Fn disconnectx
is analogous to
.Xr shutdown 2
.Dv with SHUT_RDWR
issued on the connection identified by
.Fa connid ,
or on all connections associated with the
.Fa associd
association.
.Pp
The parameter
.Fa associd
specifies the association identifier.  It may be set to
.Dv ASSOCID_ANY
when there is only one association present;
.Dv ASSOCID_ALL
to specify all existing associations; or one of the identifiers returned from
.Xr getassocids 3 .
.Pp
The parameter
.Fa connid
specifies the connection identifier.  It may be set to
.Dv CONNID_ANY
or
.Dv CONNID_ALL ,
in which case the association represented by
.Fa associd
will be dissolved; or the value returned from
.Xr connectx 2
or
.Xr getconnids 3 ,
which indicates that the disconnection occurs only on that connection
while keeping the session association intact.  For the latter, the connection
associated with
.Fa connid
will no longer be valid upon success.
.Sh RETURN VALUES
The
.Fn disconnectx
function returns the value 0 if successful; otherwise the value of -1 is
returned and the global integer variable
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn disconnectx
system call succeeds unless:
.Bl -tag -width Er
.\" ===========
.It Bq Er EALREADY
Operation already in progress for the session association represented by
.Fa associd .
.\" ===========
.It Bq Er EBADF
.Fa Socket
is not a valid descriptor.
.\" ===========
.It Bq Er EINVAL
The
.Fa associd
or
.Fa connid
argument is invalid or the underlying protocol is no longer attached to
.Fa socket .
.\" ===========
.It Bq Er ENOTCONN
The session association repreresented by
.Fa associd
is not connected.
.\" ===========
.It Bq Er ENOTSOCK
.Fa Socket
is a file, not a socket.
.El
.Sh SEE ALSO
.Xr connectx 2 ,
.Xr socket 2 ,
.Xr getassocids 3 ,
.Xr getconnids 3 ,
.Xr getconninfo 3 ,
.Xr compat 5
.Sh HISTORY
The
.Fn disconnectx
function call appeared in Darwin 13.0.0
Commit	Line	Data
39236c6e A	1	.\"
	2	.\" Copyright (c) 2012 Apple Inc. All rights reserved.
	3	.\"
	4	.\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
	5	.\"
	6	.\" This file contains Original Code and/or Modifications of Original Code
	7	.\" as defined in and that are subject to the Apple Public Source License
	8	.\" Version 2.0 (the 'License'). You may not use this file except in
	9	.\" compliance with the License. The rights granted to you under the License
	10	.\" may not be used to create, or enable the creation or redistribution of,
	11	.\" unlawful or unlicensed copies of an Apple operating system, or to
	12	.\" circumvent, violate, or enable the circumvention or violation of, any
	13	.\" terms of an Apple operating system software license agreement.
	14	.\"
	15	.\" Please obtain a copy of the License at
	16	.\" http://www.opensource.apple.com/apsl/ and read it before using this file.
	17	.\"
	18	.\" The Original Code and all software distributed under the License are
	19	.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	20	.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	21	.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	22	.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	23	.\" Please see the License for the specific language governing rights and
	24	.\" limitations under the License.
	25	.\"
	26	.\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
	27	.\"
	28	.Dd November 14, 2012
	29	.Dt DISCONNECTX 2
	30	.Os Darwin
	31	.Sh NAME
	32	.Nm disconnectx
	33	.Nd disconnects a connection on a socket
	34	.Sh SYNOPSIS
	35	.Fd #include <sys/socket.h>
	36	.Ft int
	37	.Fo disconnectx
	38	.Fa "int socket"
	39	.Fa "associd_t associd"
	40	.Fa "connid_t connid"
	41	.Fc
	42	.Sh DESCRIPTION
	43	The parameter
	44	.Fa socket
	45	is a socket. The communication domain of the socket determines the
	46	availability and behavior of
	47	.Fn disconnectx .
	48	In general,
	49	.Fn disconnectx
	50	is analogous to
	51	.Xr shutdown 2
	52	.Dv with SHUT_RDWR
	53	issued on the connection identified by
	54	.Fa connid ,
	55	or on all connections associated with the
	56	.Fa associd
	57	association.
	58	.Pp
	59	The parameter
	60	.Fa associd
	61	specifies the association identifier. It may be set to
	62	.Dv ASSOCID_ANY
	63	when there is only one association present;
	64	.Dv ASSOCID_ALL
65	to specify all existing associations; or one of the identifiers returned from
66	.Xr getassocids 3 .
67	.Pp
68	The parameter
69	.Fa connid
70	specifies the connection identifier. It may be set to
71	.Dv CONNID_ANY
72	or
73	.Dv CONNID_ALL ,
74	in which case the association represented by
75	.Fa associd
76	will be dissolved; or the value returned from
77	.Xr connectx 2
78	or
79	.Xr getconnids 3 ,
80	which indicates that the disconnection occurs only on that connection
81	while keeping the session association intact. For the latter, the connection
82	associated with
83	.Fa connid
84	will no longer be valid upon success.
85	.Sh RETURN VALUES
86	The
87	.Fn disconnectx
88	function returns the value 0 if successful; otherwise the value of -1 is
89	returned and the global integer variable
90	.Va errno
91	is set to indicate the error.
92	.Sh ERRORS
93	The
94	.Fn disconnectx
95	system call succeeds unless:
96	.Bl -tag -width Er
97	.\" ===========
98	.It Bq Er EALREADY
99	Operation already in progress for the session association represented by
100	.Fa associd .
101	.\" ===========
102	.It Bq Er EBADF
103	.Fa Socket
104	is not a valid descriptor.
105	.\" ===========
106	.It Bq Er EINVAL
107	The
108	.Fa associd
109	or
110	.Fa connid
111	argument is invalid or the underlying protocol is no longer attached to
112	.Fa socket .
113	.\" ===========
114	.It Bq Er ENOTCONN
115	The session association repreresented by
116	.Fa associd
117	is not connected.
118	.\" ===========
119	.It Bq Er ENOTSOCK
120	.Fa Socket
121	is a file, not a socket.
122	.El
123	.Sh SEE ALSO
124	.Xr connectx 2 ,
125	.Xr socket 2 ,
126	.Xr getassocids 3 ,
127	.Xr getconnids 3 ,
128	.Xr getconninfo 3 ,
129	.Xr compat 5
130	.Sh HISTORY
131	The
132	.Fn disconnectx
133	function call appeared in Darwin 13.0.0