.TH mtcp_close 3 2017-02-01 "Linux" "mOS Library Functions Manual"
.SH NAME
mtcp_close \- close an mTCP socket descriptor
.SH SYNOPSIS
.B #include <mtcp_api.h>
.sp
.BI "int mtcp_close(mctx_t " mctx ", int " sockid );

.SH DESCRIPTION
.BR mtcp_close () 
closes the socket associated with
.I "sockid"
descriptor. This call can be used to gracefully terminate 
the underlying connection for active endpoint (SOCK_STREAM) sockets. All the
underlying resources pertaining to the connection are also 
destroyed.
.BR "mtcp_close()"
can also be used to shut down a passive listening socket. For
monitoring socket types (MOS_SOCK_MONITOR_STREAM and MOS_SOCKET_MONITOR_RAW),
all flow events are deregistered from the socket.

In all cases, the socket ID is made available for re-use for a future
incoming connection request.
.\""""""after a mandatory 
.\"""""".BR "TCP_TIMEOUT"
.\""""""threshold period passes.
 
.BR mtcp_close ()
call takes an additional argument named 
.I "mctx"
that represents the per-core mTCP context in an application
(see
.BR mtcp_create_context()
for details).
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH RETURN VALUE
Returns 0 on success; -1 on failure and 
.I "errno"
is set appropriately. 
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH ERRORS
.TP 10
.B "EACCES"
.I "mctx"
is not valid.

.TP 10
.B "EAGAIN"
The request to close the connection was refused.

.TP 10
.B "EBADF"
.I "sockid"
is not a valid socket descriptor for closing.

.TP 10
.B "EINVAL"
The socket specific to
.I "sockid"
has invalid type.

.TP 10
.B "ENOTCONN"
The connection referred to by
.I "sockid"
is already terminated.

.TP 10
.B "ENOTSOCK"
The socket referred to by
.I "sockid"
is not valid.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\""""".SH CONFORMING TO
.\"""""POSIX.1-2001.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH NOTES
Please note that the same
.I "mctx"
context should be used to destroy the socket that created
the socket via
.BR "mtcp_socket ()"
call in the first place. The user may experience unpredictable
behavior if this practice is not followed.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH AUTHORS
mOS development team <mtcp-user@list.ndsl.kaist.edu>
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH SEE ALSO
.BR mtcp_socket ()
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH COLOPHON
This page is part of mOS release 0.3
.I "docs"
section. A description of the project, and information
about reporting bugs, can be found at
\%http://mos.kaist.edu/.
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""