mcs/class/Mono.Posix/Documentation/en/Mono.Unix.Native/CdeclFunction.xml

   1 <Type Name="CdeclFunction" FullName="Mono.Unix.Native.CdeclFunction">
   2   <TypeSignature Language="C#" Value="public sealed class CdeclFunction" />
   3   <TypeSignature Language="ILAsm" Value=".class public auto ansi sealed beforefieldinit CdeclFunction extends System.Object" />
   4   <AssemblyInfo>
   5     <AssemblyName>Mono.Posix</AssemblyName>
   6     <AssemblyVersion>1.0.5000.0</AssemblyVersion>
   7     <AssemblyVersion>2.0.0.0</AssemblyVersion>
   8     <AssemblyVersion>4.0.0.0</AssemblyVersion>
   9   </AssemblyInfo>
  10   <ThreadingSafetyStatement>
  11   This type is safe for multithreaded operations.
  12   </ThreadingSafetyStatement>
  13   <Base>
  14     <BaseTypeName>System.Object</BaseTypeName>
  15   </Base>
  16   <Interfaces />
  17   <Docs>
  18     <summary>Permits calling a varargs (cdecl) function from a library.</summary>
  19     <remarks>
  20       <para>This class represents a single unmanaged function with "cdecl" calling convention -- that is, it can accept a variable number of arguments which are passed on the runtime stack.</para>
  21       <para>To use, create an instance, then call <see cref="M:Mono.Unix.Native.CdeclFunction.Invoke" /> with the appropriate number of arguments:</para>
  22       <example>
  23         <code lang="C#">
  24 CdeclFunction printf = new CdeclFunction (
  25         "libc",       // the libraary
  26         "printf",     // the function name
  27         typeof (int)  // optional; the function's return type
  28 );
  29 printf.Invoke (new object[]{"hello, %s\n", "world!"});
  30   </code>
  31       </example>
  32       <para>In the background a P/Invoke definition for the method with the requested argument types will be generated and invoked, invoking the unmanaged function.  The generated methods are cached, so that subsequent calls with the same argument list do not generate new code, speeding up the call sequence.</para>
  33       <para>Invoking Cdecl functions is not guaranteed to be portable across all platforms.  For example, AMD64 requires that the caller set EAX to the number of floating point arguments passed in the SSE registers.  This is only required for variable argument/cdecl functions; consequently, the overload technique used by this class wouldn't normally work. Mono's AMD64 JIT works around this by always setting EAX on P/Invoke invocations, allowing CdeclFunction to work properly, but it will not necessarily always work.  See also: http://lwn.net/Articles/5201/?format=printable
  34 </para>
  35       <para>Due to potential portability issues, cdecl functions should be avoided on most platforms.</para>
  36     </remarks>
  37   </Docs>
  38   <Members>
  39     <Member MemberName=".ctor">
  40       <MemberSignature Language="C#" Value="public CdeclFunction (string library, string method);" />
  41       <MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string library, string method) cil managed" />
  42       <MemberType>Constructor</MemberType>
  43       <AssemblyInfo>
  44         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
  45         <AssemblyVersion>2.0.0.0</AssemblyVersion>
  46         <AssemblyVersion>4.0.0.0</AssemblyVersion>
  47       </AssemblyInfo>
  48       <Parameters>
  49         <Parameter Name="library" Type="System.String" />
  50         <Parameter Name="method" Type="System.String" />
  51       </Parameters>
  52       <Docs>
  53         <param name="library">The library the cdecl function resides in.</param>
  54         <param name="method">The export to invoke from library.</param>
  55         <summary>Create a stub object to invoke a cdecl function.</summary>
  56         <remarks />
  57       </Docs>
  58     </Member>
  59     <Member MemberName=".ctor">
  60       <MemberSignature Language="C#" Value="public CdeclFunction (string library, string method, Type returnType);" />
  61       <MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(string library, string method, class System.Type returnType) cil managed" />
  62       <MemberType>Constructor</MemberType>
  63       <AssemblyInfo>
  64         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
  65         <AssemblyVersion>2.0.0.0</AssemblyVersion>
  66         <AssemblyVersion>4.0.0.0</AssemblyVersion>
  67       </AssemblyInfo>
  68       <Parameters>
  69         <Parameter Name="library" Type="System.String" />
  70         <Parameter Name="method" Type="System.String" />
  71         <Parameter Name="returnType" Type="System.Type" />
  72       </Parameters>
  73       <Docs>
  74         <param name="library">The library the cdecl function resides in.</param>
  75         <param name="method">The export to invoke from library.</param>
  76         <param name="returnType">The return type of the function to invoke.  The default return type is <see cref="T:System.Void" />.</param>
  77         <summary>Create a stub object to invoke a cdecl function.</summary>
  78         <remarks />
  79       </Docs>
  80     </Member>
  81     <Member MemberName="Invoke">
  82       <MemberSignature Language="C#" Value="public object Invoke (object[] parameters);" />
  83       <MemberSignature Language="ILAsm" Value=".method public hidebysig instance object Invoke(object[] parameters) cil managed" />
  84       <MemberType>Method</MemberType>
  85       <AssemblyInfo>
  86         <AssemblyVersion>1.0.5000.0</AssemblyVersion>
  87         <AssemblyVersion>2.0.0.0</AssemblyVersion>
  88         <AssemblyVersion>4.0.0.0</AssemblyVersion>
  89       </AssemblyInfo>
  90       <ReturnValue>
  91         <ReturnType>System.Object</ReturnType>
  92       </ReturnValue>
  93       <Parameters>
  94         <Parameter Name="parameters" Type="System.Object[]" />
  95       </Parameters>
  96       <Docs>
  97         <param name="parameters">The parameters to pass to the function.</param>
  98         <summary>Invoke the function specified in the constructor.</summary>
  99         <returns>The return value of the invoked cdecl function.</returns>
 100         <remarks>Invokes the specified function.</remarks>
 101       </Docs>
 102     </Member>
 103   </Members>
 104 </Type>