bsd/man/man2/peeloff.2

   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 PEELOFF 2
  30 .Os Darwin
  31 .Sh NAME
  32 .Nm peeloff
  33 .Nd extracts an association from a socket
  34 .Sh SYNOPSIS
  35 .Fd #include <sys/socket.h>
  36 .Ft int
  37 .Fo peeloff
  38 .Fa "int socket"
  39 .Fa "associd_t associd"
  40 .Fc
  41 .Sh DESCRIPTION
  42 The parameter
  43 .Fa socket
  44 is a socket.  The communication domain of the socket determines the
  45 availability and behavior of
  46 .Fn peeloff .
  47 In general,
  48 .Fn peeloff
  49 attempts to extract the association specified by
  50 .Fa associd
  51 into its own separate socket.
  52 .Pp
  53 The parameter
  54 .Fa associd
  55 specifies the association identifier.  It may be set to
  56 .Dv ASSOCID_ANY
  57 when there is only one association present; or one of the identifiers
  58 returned from
  59 .Xr getassocids 3 .
  60 .Sh RETURN VALUES
  61 The
  62 .Fn peeloff
  63 function returns -1 on error and the global variable
  64 .Va errno
  65 is set to indicate the error.  If it succeeds, it returns a non-negative
  66 integer that is a descriptor for the extracted association.
  67 .Sh ERRORS
  68 The
  69 .Fn peeloff
  70 system call succeeds unless:
  71 .Bl -tag -width Er
  72 .\" ===========
  73 .It Bq Er EBADF
  74 .Fa Socket
  75 is not a valid descriptor.
  76 .\" ===========
  77 .It Bq Er EINVAL
  78 The
  79 .Fa associd
  80 argument is invalid; cannot be extracted; or the underlying protocol
  81 is no longer attached to
  82 .Fa socket .
  83 .\" ===========
  84 .It Bq Er ENOTSOCK
  85 .Fa Socket
  86 is a file, not a socket.
  87 .El
  88 .Sh SEE ALSO
  89 .Xr connectx 2 ,
  90 .Xr disconnectx 2 ,
  91 .Xr socket 2 ,
  92 .Xr getassocids 3 ,
  93 .Xr getconnids 3 ,
  94 .Xr getconninfo 3 ,
  95 .Xr compat 5
  96 .Sh HISTORY
  97 The
  98 .Fn peeloff
  99 function call appeared in Darwin 13.0.0