Skip to content
Snippets Groups Projects
Commit 47c3deff authored by Moe Jette's avatar Moe Jette
Browse files

Add Jay's plugin descriptions.

parent 29786c2a
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/html/authplugins.html 0 → 100644
+ 313
− 0
View file @ 47c3deff
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<!-- ================================================================================ -->
<!-- This HTML file was created by AbiWord. -->
<!-- AbiWord is a free, Open Source word processor. -->
<!-- You may obtain more information about AbiWord at www.abisource.com -->
<!-- ================================================================================ -->
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" >
<title>/home/jwindley/slurm/docs/authplugins.html</title>
<style type="text/css">
body
{
font-family: "Nimbus Roman";
font-style: normal;
text-indent: 0in;
font-weight: normal;
font-variant: normal;
color: #000000;
text-decoration: none;
text-align: left;
font-size: 12pt;
widows: 2;
font-stretch: normal;
background-color: #ffffff;
}
@media print
{
body
{
padding-top: 1in; padding-bottom: 1in;
padding-left: 1in; padding-right: 1in;
}
}
blockquote, .BlockText
{
margin-bottom: 0.0813in;
margin-left: 1.0000in;
margin-right: 1.0000in;
}
h1, .Heading1
{
font-size: 17pt;
margin-bottom: 0.0417in;
font-weight: bold;
font-family: "Nimbus Sans";
margin-top: 0.3056in;
}
h2, .Heading2
{
font-size: 14pt;
margin-bottom: 0.0417in;
font-weight: bold;
font-family: "Nimbus Sans";
margin-top: 0.3056in;
}
p, .Normal
{
font-family: "Nimbus Roman";
font-style: normal;
margin-left: 0pt;
text-indent: 0in;
margin-top: 0pt;
font-weight: normal;
font-variant: normal;
color: #000000;
text-decoration: none;
margin-bottom: 0.1667in;
text-align: left;
margin-right: 0pt;
font-size: 12pt;
widows: 2;
font-stretch: normal;
}
</style>
</head>
<body><div>
<h1>SLURM Authentication Plugin API</h1>
<h2>Overview</h2>
<p>This document describes SLURM authentication plugins and the API which defines them.&nbsp; It is intended as a resource to programmers wishing to write their own SLURM authentication plugins.&nbsp; This is version 0 of the API.</p>
<p>SLURM authentication plugins are SLURM plugins which implement the SLURM authentication API described herein.&nbsp; They must conform to the SLURM Plugin API with the following specifications:</p>
<p><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">const char plugin_type[]</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">- The major type must be "auth".&nbsp; The minor type can be any recognizable abbreviation for the type of authentication.&nbsp; We recommend, for example:</span></p>
<ul class="Normal">
<li style="margin-bottom: 0pt"><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> "none" - A plugin which implements the API without providing any actual authentication service.</span></li>
<li style="margin-bottom: 0pt"><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> "authd" - Brett Chun's Linux authd.</span></li>
<li style="margin-bottom: 0pt"><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> "munged" - LLNL's munge protocol.</span></li>
<li><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> </span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">"krb5" - Keberos 5</span></li>
</ul>
<p style="margin-left: 0pt; text-indent: 0in"><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">The </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">plugin_name</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> and </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">plugin_version</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> symbols required by the SLURM Plugin API require no specialization for authentication, except note carefully the versioning discussion below.</span></p>
<blockquote><span style="text-position: ">The programmer is urged to study </span><span style="text-position: ; font-family: 'Courier'">src/plugins/auth/auth_none.c</span><span style="text-position: "> for an example implementation of a SLURM authentication plugin.</span></blockquote>
<h2>Data objects</h2>
<p>The implementation must support an opaque class, which it defines, to be used as an authentication <span style="font-style: italic">credential</span>.&nbsp; This class must encapsulate all user-specific information necessary for the operation of the API specification below.&nbsp; The <span style="font-style: italic">credential</span> is referred to in SLURM code by an anonymous pointer (void *).</p>
<blockquote>The implementation must maintain (though not necessarily directly export) an enumerated <span style="font-style: italic">errno</span> to allow SLURM to discover as practically as possible the reason for any failed API call.&nbsp; The following enumerated integer values (declared in <span style="font-family: 'Courier'">src/common/slurm_auth.h</span>) must be used when appropriate.</blockquote>
<blockquote>SLURM_AUTH_MEMORY - a request could not be satisfied because memory for it could not be allocated.<br>SLURM_AUTH_NOUSER - a <span style="font-style: italic">credential</span> is improper because it refers to an unknown user.</blockquote>
<blockquote>SLURM_AUTH_EXPIRED - a <span style="font-style: italic">credential</span> is no longer acceptable because it has expired.&nbsp; This does not imply that it is otherwise valid.<br>SLURM_AUTH_INVALID - a <span style="font-style: italic">credential</span> is improper because the validation of it has failed.&nbsp; This is specifically distinct from the expiration of a <span style="font-style: italic">credential</span>.<br>SLURM_AUTH_MISMATCH - a <span style="font-style: italic">credential</span> could not be properly unpacked because it is of an incompatible type or version.</blockquote>
<blockquote>These values must not be used as return values in integer-valued functions in the API.&nbsp; The proper error return value from integer-valued functions is SLURM_ERROR.&nbsp; While it is most practical to associate a different <span style="font-style: italic">errno</span> with each instance of a <span style="font-style: italic">credential</span>, this is not necessarily enforced by the API.&nbsp; The implementation should endeavor to provide useful and pertinent information by whatever means is practical.&nbsp; In most cases this means an errno for each <span style="font-style: italic">credential</span>, since plugins must be re-entrant.&nbsp; If a plugin maintains a global <span style="font-style: italic">errno</span> in place of or in addition to a per-<span style="font-style: italic">credential</span> <span style="font-style: italic">errno</span>, it is not required to enforce mutual exclusion on it.&nbsp; Successful API calls are not required to reset any <span style="font-style: italic">errno</span> to a known value.&nbsp; However, the initial value of any <span style="font-style: italic">errno</span>, prior to any error condition arising, should be SLURM_SUCCESS.</blockquote>
<blockquote>Plugins may assign implementation-specific values to <span style="font-style: italic">errno</span> so long as they do not conflict with the values assigned above.&nbsp; This is done programmatically by assigning plugin-specific <span style="font-style: italic">errno</span> values which are arithmetically greater than or equal to the symbol SLURM_AUTH_FIRST_LOCAL_ERROR.</blockquote>
<h2>API functions</h2>
<p><span style="font-family: 'Courier'">void *slurm_auth_alloc (void);</span></p>
<p style="margin-left: 36pt"><span style="font-weight: bold">Description<br></span>Allocates from the free store an anonymous <span style="font-style: italic">credential</span> object and returns a pointer to it.&nbsp; The pointer should be valid until passed to <span style="font-family: 'Courier'">slurm_auth_free()</span> for disposal.&nbsp; The credential is not expected to be in a usable state until it is activated by <span style="font-family: 'Courier'">slurm_auth_activate()</span>.&nbsp; SLURM will not pass <span style="font-style: italic">credentials</span> to the API which have not been allocated by this function.</p>
<p style="margin-left: 36pt"><span style="font-weight: bold">Arguments<br></span>None.</p>
<p style="margin-left: 36pt"><span style="font-weight: bold">Returns<br></span>A pointer to a newly allocated credential if successful.&nbsp; On failure the plugin should return NULL and set its <span style="font-style: italic">errno</span> to an appropriate value to indicate the reason for failure.</p>
<blockquote><span style="font-family: 'Courier'">void slurm_auth_free (void *cr);</span></blockquote>
<p style="margin-left: 36pt"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Description<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Deallocates a </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> that was allocated with </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">slurm_auth_alloc()</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> and any associated storage that has been allocated for it during its use.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Arguments<br></span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">cr</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> - (input) pointer to the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> which is to be deallocated.&nbsp; Cannot be NULL.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 12pt; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Returns<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">None.</span></p>
<blockquote><span style="text-position: ; font-family: 'Courier'">int slurm_auth_activate (void *cr, int secs);</span></blockquote>
<p dir="ltr" style="text-align: left; margin-bottom: 12pt; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Description<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Prepares a </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> for verification, usually by some "signing" process.&nbsp; </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">slurm_auth_activate() </span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">and </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">slurm_auth_verify()</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> are strictly sequential operations.&nbsp; A </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> which has been successfully activated should be successfully verified without any further processing, provided it has not expired.&nbsp; A </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> must be activated before it can be successfully verified.&nbsp; The return values of </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">slurm_auth_get_uid()</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> and </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">slurm_auth_get_gid()</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> may be meaningful after activation (depending on plugin preference), but are not considered trustworthy by SLURM until verification.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 12pt; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Arguments<br></span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">cr</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> - (input) pointer to the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> which is to be activated.&nbsp; Cannot be NULL.<br></span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">secs</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> - (input) number of seconds of wallclock time for which the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> is to be considered valid following the call to this function.&nbsp; Must be a positive.&nbsp; Negative and zero values are reserved for future use.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 12pt; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Returns<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">SLURM_SUCCESS if successful.&nbsp; On failure the function should return SLURM_ERROR and set its </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">errno</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> to an appropriate value to indicate the reason for failure.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.0000in; margin-top: 0.0000in; margin-right: 0.0000in"><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">int slurm_auth_verify (void *cr );</span></p>
<blockquote><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Description<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Verifies that a </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> is in order and correctly identifies the associated user.&nbsp; It also verifies that the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> has not expired.&nbsp; If verification is successful, the return values of </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">slurm_auth_get_uid()</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> and </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">slurm_auth_get_gid()</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> in subsequent calls must correspond to the actual verified system UID and GID of the user associated with the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">.&nbsp; Verification must fail if the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> has not previously been activated, even if a </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> implementation cannot exist in an unactivated state.&nbsp; A </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">'s valid term is defined at activation and verification must fail if the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> has expired, even if it would otherwise be valid.</span></blockquote>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Arguments<br></span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">cr</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> - (input) pointer to the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> which is to be verified.&nbsp; Cannot be NULL.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 12pt; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Returns<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">SLURM_SUCCESS if the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> is verified to be in order and has not expired.&nbsp; If the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> cannot be verified, or if the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> has expired, the function should return SLURM_ERROR and set its </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">errno</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> to an appropriate value to indicate the reason for failure.</span></p>
<blockquote><span style="text-position: ; font-family: 'Courier'">uid_t slurm_auth_get_uid (void *cr);<br>gid_t slurm_auth_get_gid (void *cr);</span></blockquote>
<blockquote><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Description<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Extracts the numerical UID (GID) of the user corresponding to the given </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">.&nbsp; SLURM considers this value trustworthy only if the credential has been successfully verified using</span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt"> slurm_auth_verify()</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">.&nbsp; An unverified </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> does not immediately give rise to an error condition in these functions, since this would require a plugin to distinguish between a verified and an unverified </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">, which may be computationally expensive.&nbsp; A plugin may consider the lack of verification as an error.</span></blockquote>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Arguments<br></span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">cr</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> - (input) pointer to the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> containing the desired identification.&nbsp; Cannot be NULL.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 12pt; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Returns<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">If successful, the Linux UID (GID) associated with the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">.&nbsp; In case of error, SLURM_AUTH_NOBODY should be returned and </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">errno</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> set appropriately to indicate the cause of the failure.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.0000in; margin-top: 0.0000in; margin-right: 0.0000in"><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">void slurm_auth_pack (void *cr, Buf buf);</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Description<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Marshals a </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> into a buffer for transmission according to the SLURM packing protocol.&nbsp; All authentication plugins must first pack the </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">plugin_type</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> and then the </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">plugin_version</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> data before any plugin-specific data elements are packed.&nbsp; </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">slurm_auth_pack()</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> and </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">slurm_auth_pack()</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> are strictly reciprocal.&nbsp; The result of a packing followed by an unpacking must be a functionally equivalent </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">.&nbsp; A </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> is deemed appropriate for marshalling at any time after its allocation and before its destruction.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Arguments<br></span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">cr</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> - (input) pointer to the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> to pack.<br></span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">buf</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> - (input/output) the buffer into which the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> should be packed.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 12pt; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Returns<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">None.</span></p>
<blockquote><span style="text-position: ; font-family: 'Courier'">int slurm_auth_unpack (void *cr, Buf buf);</span></blockquote>
<p dir="ltr" style="text-align: left; margin-bottom: 12pt; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Description<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Unmarshals a </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> from a buffer according to the SLURM packing protocol into a supplied (and presumed empty) </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> object.&nbsp; The unmarshalled credential is not assumed to be activated or verified.&nbsp; The </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">plugin_type</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> and </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">plugin_version</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> data should first be unpacked from the buffer and verified for applicability.&nbsp; The API does not enforce that they must be equivalent, merely compatible.&nbsp; Compatibility is implementation-dependent.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Arguments<br></span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">cr</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> - (output) pointer to the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> to pack.<br></span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">buf</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> - (input/output) the buffer from which the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> should be unpacked.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 12pt; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Returns<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">SLURM_SUCCESS if the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> was successfully unpacked.&nbsp; In case of failure, the function should return SLURM_ERROR and set </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">errno</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> appropriately to indicate the cause of the failure.&nbsp; If the function fails, no assumptions are made about the state of the credential except its suitability for destruction via </span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">slurm_auth_free()</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">.</span></p>
<blockquote><span style="text-position: ; font-family: 'Courier'">void slurm_auth_print (void *cr, FILE *fp);</span></blockquote>
<p dir="ltr" style="text-align: left; margin-bottom: 12pt; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Description<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Writes a human-readable representation of the credential to a standard I/O stream.&nbsp; There are no strict API constraints on the behavior of this function, however it is recommended that the information be as complete and as concise as possible.&nbsp; For example, lengthy digital "signatures" need not be printed bitwise, but may be represented by their checksum.&nbsp; The intent is to provide a depiction of the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> for debugging purposes.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Arguments<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">None.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 12pt; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Returns<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">None.</span></p>
<blockquote><span style="text-position: ; font-family: 'Courier'">int slurm_auth_errno (void *cr);</span></blockquote>
<blockquote><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Description<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Returns the current value of </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">errno</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">.&nbsp; Whether the value is associated with the given </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> or with the plugin as a whole is implementation-dependent.&nbsp; Because this function can be used to discover the reason why a credential allocation has failed, the argument is advisory. </span></blockquote>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Arguments<br></span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">cr</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> - (input) pointer to the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">credential</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">, the status of whose most recently executed API function is to be returned.&nbsp; This value may be NULL, indicating that the most recent </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">errno</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> value applicable to the plugin as a whole is to be returned.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Returns<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">The current value of </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">errno</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> or SLURM_SUCCESS if there is no error to report.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.0000in; margin-top: 0.0000in; margin-right: 0.0000in"><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">const char *slurm_auth_errstr (int errno);</span></p>
<blockquote><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Description<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Provides a human-readable string associated with the given </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">errno</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">.&nbsp; The plugin need only supply error strings for the </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">errno</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> values it defines and not for </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">errno</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> values listed above that are required by the API.</span></blockquote>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Arguments<br></span><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt">errno</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> - (input) the plugin-specific </span><span style="font-style: italic; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">errno</span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> for which a corresponding error message is desired.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.0000in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Returns<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">A pointer to a static error message.&nbsp; This function must always return a pointer to a string, even if the string is ambiguous such as "unknown error".</span></p>
<h2 dir="ltr"><span style="text-position: ">Versioning</span></h2>
<p dir="ltr"><span style="text-position: ">This document describes version 0 of the SLURM Authentication API.&nbsp; Future releases of SLURM may revise this API.&nbsp; An authentication plugin conveys its ability to implement a particular API version using the mechanism outlined for SLURM plugins.&nbsp; In addition, the </span><span style="font-style: italic; text-position: ">credential</span><span style="text-position: "> is transmitted along with the version number of the plugin that transmitted it.&nbsp; It is at the discretion of the plugin author whether to maintain data format compatibility across different versions of the plugin.</span></p>
</div>
</body>
</html>
doc/html/plugins.html 0 → 100644
+ 261
− 0
View file @ 47c3deff
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<!-- ================================================================================ -->
<!-- This HTML file was created by AbiWord. -->
<!-- AbiWord is a free, Open Source word processor. -->
<!-- You may obtain more information about AbiWord at www.abisource.com -->
<!-- ================================================================================ -->
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" >
<title>/home/jwindley/slurm/docs/plugins.html</title>
<style type="text/css">
body
{
font-family: "Nimbus Roman";
font-style: normal;
text-indent: 0in;
font-weight: normal;
font-variant: normal;
color: #000000;
text-decoration: none;
text-align: left;
font-size: 12pt;
widows: 2;
font-stretch: normal;
background-color: #ffffff;
}
@media print
{
body
{
padding-top: 1in; padding-bottom: 1in;
padding-left: 1in; padding-right: 1in;
}
}
h1, .Heading1
{
font-size: 17pt;
margin-bottom: 0.0417in;
font-weight: bold;
font-family: "Nimbus Sans";
margin-top: 0.3056in;
}
h2, .Heading2
{
font-size: 14pt;
margin-bottom: 0.0417in;
font-weight: bold;
font-family: "Nimbus Sans";
margin-top: 0.3056in;
}
p, .Normal
{
font-family: "Nimbus Roman";
font-style: normal;
margin-left: 0pt;
text-indent: 0in;
margin-top: 0pt;
font-weight: normal;
font-variant: normal;
color: #000000;
text-decoration: none;
margin-bottom: 0.1667in;
text-align: left;
margin-right: 0pt;
font-size: 12pt;
widows: 2;
font-stretch: normal;
}
</style>
</head>
<body><div>
<h1>SLURM Plugin API</h1>
<h2>Overview</h2>
<p>A SLURM plugin is a dynamically linked code object which is loaded explicitly at runtime by the SLURM libraries.&nbsp; A plugin provides a customized implementation of a well-defined API connected to tasks such as authentication, interconnect fabric, and task scheduling.</p>
<h2>Identification</h2>
<p>A SLURM plugin identifies itself by a short character string formatted similarly to a MIME type: <span style="font-style: italic">&lt;major&gt;/&lt;minor&gt;</span>.&nbsp; The major type identifies which API the plugin implements.&nbsp; The minor type uniquely distinguishes a plugin from other plugins that implement that same API, by such means as the intended platform or the internal algorithm.&nbsp; For example, a plugin to interface to the Maui scheduler would give its type as "sched/maui".&nbsp; It would implement the SLURM Scheduler API.</p>
<h2>Versioning</h2>
<p dir="ltr" style="text-align: left; margin-bottom: 0.0000in; margin-top: 0.0000in; margin-right: 0.0000in"><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">SLURM plugin version numbers comprise a major and minor revision number.&nbsp;&nbsp; As SLURM evolves, changes to the individual plugin APIs may be necessary to implement new features.&nbsp; The major number identifies the version of the applicable API that the plugin implements.&nbsp; Incrementing the major version number denotes that the API has changed significantly and possibly incompatibly over prior versions.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.0000in; margin-top: 0.0000in; margin-right: 0.0000in"><br>
</p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.0000in; margin-top: 0.0000in; margin-right: 0.0000in"><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Because plugins are separate code objects and perhaps under the control of third parties, version skew may occur in a SLURM installation.&nbsp; SLURM may support multiple versions of each API in a backward-compatible fashion to provide time for plugin authors to update their plugins.&nbsp; Conversely the plugin may support multiple versions of the API in order to be transparently portable across different SLURM installations.&nbsp; The version of the API spoken in an installation will be the highest-numbered version which is common to both SLURM and the plugin.&nbsp; Each SLURM release will document which API versions it supports.&nbsp; From time to time ancient API versions will be deprecated.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.0000in; margin-top: 0.0000in; margin-right: 0.0000in"><br>
</p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.0000in; margin-top: 0.0000in; margin-right: 0.0000in"><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">The minor version number is incremented at the discretion of the plugin author and denotes revisions or upgrades particular to that implementation.&nbsp; If two or more plugins of the same type are provided in an installation, the plugin with the highest minor revision will be selected.</span></p>
<h2>Data objects</h2>
<p>A plugin must define and export the following symbols:</p>
<ul class="Normal">
<li><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt"> </span><span style="font-family: 'Courier'">const char plugin_type[]</span> - a unique, short, formatted string to identify the plugin's purpose as described above.&nbsp; A "null" plugin (i.e., one which implements the desired API as stubs) should have a minor type of "none".</li>
<li><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt"> </span><span style="font-family: 'Courier'">const char plugin_name[] </span>- a free-form string which identifies the plugin in human-readable terms, such as "Kerberos authentication".&nbsp; SLURM will use this string to identify the plugin to end users.</li>
<li><span style="text-position: ; color:#000000; font-family: 'Courier'; font-size: 12.000000pt"> </span><span style="font-family: 'Courier'">const uint32_t plugin_version</span> - a 32-bit unsigned integer giving the version of the plugin as described above.&nbsp; The major revision number is multiplied by 1,000 and added to the minor revision number to produce the integer value.&nbsp; Thus a plugin with a major revision number of 2 and a minor revision number of 35 will have a <span style="font-family: 'Courier'">plugin_version</span> value of 2035.</li>
</ul>
<p style="margin-left: 0pt; text-indent: 0in">A plugin may optionally define and export the following symbols:</p>
<ul class="Normal">
<li><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt"> </span><span style="font-family: 'Courier'">const uint32_t plugin_legacy</span> - a 32-bit unsigned integer formatted the same as <span style="font-family: 'Courier'">plugin_version</span> giving the lowest API version number with which this plugin is compatible.&nbsp; If this symbol is omitted its value is assumed to be equivalent to the <span style="font-family: 'Courier'">plugin_version</span><span style="font-family: 'Nimbus Roman'"> rounded to the next lowest 1,000.</span>&nbsp; Only the major version number of this symbol is significant.</li>
</ul>
<h2>API functions</h2>
<p><span style="font-family: 'Courier'">int init (void);</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Description<br></span><span style="text-position: ; font-family: 'Nimbus Roman'; font-size: 12.000000pt">If present, this function is called just after the plugin is loaded.&nbsp; This allows the plugin to perform any global initialization prior to any actual API calls.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Arguments<br></span><span style="text-position: ; font-family: 'Nimbus Roman'; font-size: 12.000000pt">None.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Returns<br></span><span style="text-position: ; font-family: 'Nimbus Roman'; font-size: 12.000000pt">SLURM_SUCCESS if the plugin's initialization was successful.&nbsp; Any other return value indicates to SLURM that the plugin should be unloaded and not used.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in"><span style="font-family: 'Courier'">void fini (void);</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Description<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">If present, this function is called just before the plugin is unloaded.&nbsp; This allows the plugin to do any finalization after the last plugin-specific API call is made.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Arguments<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">None.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in; margin-left: 0.5000in"><span style="font-weight: bold; text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">Returns<br></span><span style="text-position: ; color:#000000; font-family: 'Nimbus Roman'; font-size: 12.000000pt">None.</span></p>
<p dir="ltr" style="text-align: left; margin-bottom: 0.1667in; margin-top: 0.0000in; margin-right: 0.0000in">N.B. these functions are not the same as those described in the <span style="font-family: 'Courier'">dlopen(3)</span> system library.&nbsp; The C runtime system co-opts those symbols for its own initialization.&nbsp; The system <span style="font-family: 'Courier'">init()</span> is called before the SLURM plugin <span style="font-family: 'Courier'">init()</span>, and the <span style="font-family: 'Courier'">SLURM fini()</span> is called before the system's <span style="font-family: 'Courier'">fini()</span>.</p>
<p style="margin-left: 0pt">The functions need not appear.&nbsp; The plugin may provide either <span style="font-family: 'Courier'">init()</span> or <span style="font-family: 'Courier'">fini()</span> or both.</p>
<h2>Thread safety</h2>
<p>SLURM is a multithreaded application.&nbsp; The SLURM plugin library may exercise the plugin functions in a re-entrant fashion.&nbsp; It is the responsibility of the plugin author to provide the necessarily mutual exclusion and synchronization in order to avoid the pitfalls of re-entrant code.</p>
<h2>Runtime support</h2>
<p>The standard system libraries are available to the plugin.&nbsp; The SLURM libraries are also available and plugin authors are encouraged to make use of them rather than develop their own substitutes.&nbsp; Plugins should use the SLURM log to print error messages.</p>
<p>The plugin author is responsible for specifying any specific non-standard libraries needed for correct operation.&nbsp; Plugins will not load if their dependent libraries are not available, so it is the installer's job to make sure the specified libraries are available.</p>
</div>
</body>
</html>
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
Nutzungsbedingungen | Datenschutzerklärung | Barrierefreiheitserklärung