← Back to branch summary

~ubuntu-branches/ubuntu/utopic/gridengine/utopic

« back to all changes in this revision

Viewing changes to doc/htmlman/htmlman3/drmaa_wifsignaled.html

  • Committer: Bazaar Package Importer
  • Author(s): Mark Hymers
  • Date: 2008-06-25 22:36:13 UTC
  • Revision ID: james.westby@ubuntu.com-20080625223613-tvd9xlhuoct9kyhm
Tags: upstream-6.2~beta2
Import upstream version 6.2~beta2

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/htmlman/htmlman3/drmaa_wifsignaled.html
 
1
<HTML>
 
2
<BODY BGCOLOR=white>
 
3
<PRE>
 
4
<!-- Manpage converted by man2html 3.0.1 -->
 
5
NAME
 
6
     drmaa_synchronize,       drmaa_wait,        drmaa_wifexited,
 
7
     drmaa_wexitstatus,     drmaa_wifsignaled,    drmaa_wtermsig,
 
8
     drmaa_wcoredump, drmaa_wifaborted - Waiting for jobs to fin-
 
9
     ish
 
10
 
 
11
SYNOPSIS
 
12
     #include "drmaa.h"
 
13
 
 
14
     int drmaa_synchronize(
 
15
          const char *job_ids[],
 
16
          signed long timeout,
 
17
          int dispose,
 
18
          char *error_diagnosis,
 
19
          size_t error_diag_len
 
20
     );
 
21
 
 
22
     int drmaa_wait(
 
23
          const char *job_id,
 
24
          char *job_id_out,
 
25
          size_t job_id_out_len,
 
26
          int *stat,
 
27
          signed long timeout,
 
28
          drmaa_attr_values_t **rusage,
 
29
          char *error_diagnosis,
 
30
          size_t error_diagnois_len
 
31
     );
 
32
 
 
33
     int drmaa_wifaborted(
 
34
          int *aborted,
 
35
          int stat,
 
36
          char *error_diagnosis,
 
37
          size_t error_diag_len
 
38
     );
 
39
 
 
40
     int drmaa_wifexited(
 
41
          int *exited,
 
42
          int stat,
 
43
          char *error_diagnosis,
 
44
          size_t error_diag_len
 
45
     );
 
46
 
 
47
     int drmaa_wifsignaled(
 
48
          int *signaled,
 
49
          int stat,
 
50
          char *error_diagnosis,
 
51
          size_t error_diag_len
 
52
     );
 
53
 
 
54
     int drmaa_wcoredump(
 
55
          int *core_dumped,
 
56
          int stat,
 
57
          char *error_diagnosis,
 
58
          size_t error_diag_len
 
59
     );
 
60
 
 
61
     int drmaa_wexitstatus(
 
62
          int *exit_status,
 
63
          int stat,
 
64
          char *error_diagnosis,
 
65
          size_t error_diag_len
 
66
     );
 
67
 
 
68
     int drmaa_wtermsig(
 
69
          char *signal,
 
70
          size_t signal_len,
 
71
          int stat,
 
72
          char *error_diagnosis,
 
73
          size_t error_diag_len
 
74
     );
 
75
 
 
76
DESCRIPTION
 
77
     The drmaa_synchronize() function blocks the  calling  thread
 
78
     until  all jobs specified in <I>job</I>_<I>ids</I> have failed or finished
 
79
     execution. If <I>job</I>_<I>ids</I> contains  'DRMAA_JOB_IDS_SESSION_ALL',
 
80
     then  this function waits for all jobs submitted during this
 
81
     DRMAA session. The <I>job</I>_<I>ids</I> pointer array must be  <I>NULL</I>  ter-
 
82
     minated.
 
83
 
 
84
     To prevent blocking indefinitely in this  call,  the  caller
 
85
     may use the <I>timeout</I>, specifying how many seconds to wait for
 
86
     this call to complete before timing out. The  special  value
 
87
     DRMAA_TIMEOUT_WAIT_FOREVER  can be used to wait indefinitely
 
88
     for a result. The special value DRMAA_TIMEOUT_NO_WAIT can be
 
89
     used to return immediately. If the call exits before <I>timeout</I>
 
90
     seconds, all the specified jobs have completed or  the  cal-
 
91
     ling  thread  received  an  interrupt.   In  both cases, the
 
92
     return code is DRMAA_ERRNO_EXIT_TIMEOUT.
 
93
 
 
94
     The <I>dispose</I> parameter specifies how to treat reaping  infor-
 
95
     mation.  If  '0'  is  passed  to  this parameter, job finish
 
96
     information will still be available  when  <B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B>  is
 
97
     used.  If  '1'  is  passed,  <B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B> will be unable to
 
98
     access this job's finish information.
 
99
 
 
100
  drmaa_wait()
 
101
     The drmaa_wait() function blocks the calling thread until  a
 
102
     job fails or finishes execution.  This routine is modeled on
 
103
     the   <B><A HREF="../htmlman3/wait4.html">wait4(3)</A></B>    routine.    If    the    special    string
 
104
     'DRMAA_JOB_IDS_SESSION_ANY'  is  passed as <I>job</I>_<I>id</I>, this rou-
 
105
     tine will wait for any job from the session.  Otherwise  the
 
106
     <I>job</I>_<I>id</I> must be the job identifier of a job or array job task
 
107
     that was submitted during the session.
 
108
 
 
109
     To prevent blocking indefinitely in this  call,  the  caller
 
110
     may  use  <I>timeout</I>,  specifying  how many seconds to wait for
 
111
     this call to complete before timing out. The  special  value
 
112
     DRMAA_TIMEOUT_WAIT_FOREVER can be to wait indefinitely for a
 
113
     result. The special value DRMAA_TIMEOUT_NO_WAIT can be  used
 
114
     to  return  immediately.  If  the  call exits before <I>timeout</I>
 
115
     seconds have passed, all the specified jobs  have  completed
 
116
     or the calling thread received an interrupt.  In both cases,
 
117
     the return code is DRMAA_ERRNO_EXIT_TIMEOUT.
 
118
 
 
119
     The routine reaps jobs on a successful call, so  any  subse-
 
120
     quent   calls   to   <B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B>  will  fail  returning  a
 
121
     DRMAA_ERRNO_INVALID_JOB error,  meaning  that  the  job  has
 
122
     already  been  reaped.  This error is the same as if the job
 
123
     were unknown. Returning due to  an  elapsed  timeout  or  an
 
124
     interrupt  does  not cause the job information to be reaped.
 
125
     This means that, in this  case,  it  is  possible  to  issue
 
126
     <B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B> multiple times for the same <I>job</I>_<I>id</I>.
 
127
 
 
128
     If <I>job</I>_<I>id</I>_<I>out</I> is not a null pointer, then on return  from  a
 
129
     successful  <B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B> call, up to <I>job</I>_<I>id</I>_<I>out</I>_<I>len</I> charac-
 
130
     ters from the job id of  the  failed  or  finished  job  are
 
131
     returned.
 
132
 
 
133
     If <I>stat</I> is not a null pointer, then on return  from  a  suc-
 
134
     cessful  <B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B> call, the status of the job is stored
 
135
     in the integer pointed to by <I>stat</I>.  <I>stat</I>  indicates  whether
 
136
     job  failed  or finished and other information. The informa-
 
137
     tion encoded in  the  integer  value  can  be  accessed  via
 
138
     <B><A HREF="../htmlman3/drmaa_wifaborted.html">drmaa_wifaborted(3)</A></B>  <B><A HREF="../htmlman3/drmaa_wifexited.html">drmaa_wifexited(3)</A></B> <B><A HREF="../htmlman3/drmaa_wifsignaled.html">drmaa_wifsignaled(3)</A></B>
 
139
     <B><A HREF="../htmlman3/drmaa_wcoredump.html">drmaa_wcoredump(3)</A></B> <B><A HREF="../htmlman3/drmaa_wexitstatus.html">drmaa_wexitstatus(3)</A></B> <B><A HREF="../htmlman3/drmaa_wtermsig.html">drmaa_wtermsig(3)</A></B>.
 
140
 
 
141
     If <I>rusage</I> is not a null pointer, then on return from a  suc-
 
142
     cessful <B><A HREF="../htmlman3/drmaa_wait.html">drmaa_wait(3)</A></B> call, a summary of the  resources used
 
143
     by the terminated job is returned in form of a DRMAA  values
 
144
     string   vector. The entries in the DRMAA values string vec-
 
145
     tor can  be  extracted  using  <B><A HREF="../htmlman3/drmaa_get_next_attr_value.html">drmaa_get_next_attr_value(3)</A></B>.
 
146
     Each string returned by <B><A HREF="../htmlman3/drmaa_get_next_attr_value.html">drmaa_get_next_attr_value(3)</A></B> will be
 
147
     of the  format  &lt;name&gt;=&lt;value&gt;,  where  &lt;name&gt;  and  &lt;value&gt;
 
148
     specify  name  and  amount of resources consumed by the job,
 
149
     respectively.  See <B><A HREF="../htmlman5/accounting.html">accounting(5)</A></B> for an explanation  of  the
 
150
     resource information.
 
151
 
 
152
  drmaa_wifaborted()
 
153
     The drmaa_wifaborted() function evaluates into  the  integer
 
154
     pointed  to by <I>aborted</I> a non-zero value if <I>stat</I> was returned
 
155
     from a job that ended before entering the running state.
 
156
 
 
157
  drmaa_wifexited()
 
158
     The drmaa_wifexited() function evaluates  into  the  integer
 
159
     pointed  to  by <I>exited</I> a non-zero value if <I>stat</I> was returned
 
160
     from a job that terminated normally. A zero value  can  also
 
161
     indicate  that  although the job has terminated normally, an
 
162
     exit status is not  available,  or  that  it  is  not  known
 
163
     whether   the   job   terminated  normally.  In  both  cases
 
164
     <B><A HREF="../htmlman3/drmaa_wexitstatus.html">drmaa_wexitstatus(3)</A></B> will not provide exit  status  informa-
 
165
     tion.  A  non-zero  value  returned in <I>exited</I> indicates more
 
166
     detailed   diagnosis   can   be   provided   by   means   of
 
167
     <B><A HREF="../htmlman3/drmaa_wifsignaled.html">drmaa_wifsignaled(3)</A></B>,          <B><A HREF="../htmlman3/drmaa_wtermsig.html">drmaa_wtermsig(3)</A></B>         and
 
168
     <B><A HREF="../htmlman3/drmaa_wcoredump.html">drmaa_wcoredump(3)</A></B>.
 
169
 
 
170
  drmaa_wifsignaled()
 
171
     The drmaa_wifsignaled() function evaluates into the  integer
 
172
     pointed to by <I>signaled</I> a non-zero value if <I>stat</I> was returned
 
173
     for a job that terminated due to the receipt of a signal.  A
 
174
     zero  value can also indicate that although the job has ter-
 
175
     minated due to the receipt of a signal, the  signal  is  not
 
176
     available, or it is not known whether the job terminated due
 
177
     to the receipt of a signal. In both cases  <B><A HREF="../htmlman3/drmaa_wtermsig.html">drmaa_wtermsig(3)</A></B>
 
178
     will  not  provide  signal  information.  A  non-zero  value
 
179
     returned in <I>signaled</I> indicates  signal  information  can  be
 
180
     retrieved by means of <B><A HREF="../htmlman3/drmaa_wtermsig.html">drmaa_wtermsig(3)</A></B>.
 
181
 
 
182
  drmaa_wcoredump()
 
183
     If <B><A HREF="../htmlman3/drmaa_wifsignaled.html">drmaa_wifsignaled(3)</A></B> returned a  non-zero  value  in  the
 
184
     <I>signaled</I> parameter, the drmaa_wcoredump() function evaluates
 
185
     into the integer pointed to by <I>core</I>_<I>dumped</I> a non-zero  value
 
186
     if a core image of the terminated job was created.
 
187
 
 
188
  drmaa_wexitstatus()
 
189
     If <B><A HREF="../htmlman3/drmaa_wifexited.html">drmaa_wifexited(3)</A></B>  returned  a  non-zero  value  in  the
 
190
     <I>exited</I> parameter, the drmaa_wexitstatus() function evaluates
 
191
     into the integer pointed to by <I>exit</I>_<I>code</I> the exit code  that
 
192
     the  job  passed to <B><A HREF="../htmlman2/exit.html">exit(2)</A></B> or the value that the child pro-
 
193
     cess returned from main.
 
194
 
 
195
  drmaa_wtermsig()
 
196
     If <B><A HREF="../htmlman3/drmaa_wifsignaled.html">drmaa_wifsignaled(3)</A></B> returned a  non-zero  value  in  the
 
197
     <I>signaled</I>  parameter, the drmaa_wtermsig() function evaluates
 
198
     into  <I>signal</I>  up  to  <I>signal</I>_<I>len</I>  characters  of  a   string
 
199
     representation  of the signal that caused the termination of
 
200
     the job. For signals declared by POSIX.1, the symbolic names
 
201
     are  returned  (e.g.,  SIGABRT,  SIGALRM).  For  signals not
 
202
     declared by POSIX, any other string may be returned.
 
203
 
 
204
ENVIRONMENTAL VARIABLES
 
205
     SGE_ROOT       Specifies the location  of  the  Grid  Engine
 
206
                    standard configuration files.
 
207
 
 
208
     SGE_CELL       If set, specifies  the  default  Grid  Engine
 
209
                    cell  to  be  used.  To address a Grid Engine
 
210
                    cell Grid Engine uses (in the order  of  pre-
 
211
                    cedence):
 
212
 
 
213
                         The name of the cell  specified  in  the
 
214
                         environment  variable SGE_CELL, if it is
 
215
                         set.
 
216
 
 
217
                         The  name  of  the  default  cell,  i.e.
 
218
                         default.
 
219
 
 
220
 
 
221
     SGE_DEBUG_LEVEL
 
222
                    If  set,  specifies  that  debug  information
 
223
                    should  be written to stderr. In addition the
 
224
                    level of detail in which debug information is
 
225
                    generated is defined.
 
226
 
 
227
     SGE_QMASTER_PORT
 
228
                    If set,  specifies  the  tcp  port  on  which
 
229
                    <B><A HREF="../htmlman8/sge_qmaster.html">sge_qmaster(8)</A></B> is expected to listen for com-
 
230
                    munication requests.  Most installations will
 
231
                    use  a  services  map entry instead to define
 
232
                    that port.
 
233
 
 
234
RETURN VALUES
 
235
     Upon      successful      completion,       drmaa_run_job(),
 
236
     drmaa_run_bulk_jobs(),  and  drmaa_get_next_job_id()  return
 
237
     DRMAA_ERRNO_SUCCESS. Other values indicate an error.  Up  to
 
238
     <I>error</I>_<I>diag</I>_<I>len</I>  characters of error related diagnosis infor-
 
239
     mation is then provided in the buffer <I>error</I>_<I>diagnosis</I>.
 
240
 
 
241
ERRORS
 
242
     The  drmaa_synchronize(),  drmaa_wait(),  drmaa_wifexited(),
 
243
     drmaa_wexitstatus(),  drmaa_wifsignaled(), drmaa_wtermsig(),
 
244
     drmaa_wcoredump(), and drmaa_wifaborted() will fail if:
 
245
 
 
246
  DRMAA_ERRNO_INTERNAL_ERROR
 
247
     Unexpected  or  internal  DRMAA  error,  like  system   call
 
248
     failure, etc.
 
249
 
 
250
  DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE
 
251
     Could not contact DRM system for this request.
 
252
 
 
253
  DRMAA_ERRNO_AUTH_FAILURE
 
254
     The specified request is not processed successfully  due  to
 
255
     authorization failure.
 
256
 
 
257
  DRMAA_ERRNO_INVALID_ARGUMENT
 
258
     The input value for an argument is invalid.
 
259
 
 
260
  DRMAA_ERRNO_NO_ACTIVE_SESSION
 
261
     Failed because there is no active session.
 
262
 
 
263
  DRMAA_ERRNO_NO_MEMORY
 
264
     Failed allocating memory.
 
265
     The drmaa_synchronize() and drmaa_wait() functions will fail
 
266
     if:
 
267
 
 
268
  DRMAA_ERRNO_EXIT_TIMEOUT
 
269
     Time-out condition.
 
270
 
 
271
  DRMAA_ERRNO_INVALID_JOB
 
272
     The job specified by the does not exist.
 
273
 
 
274
     The drmaa_wait() will fail if:
 
275
 
 
276
  DRMAA_ERRNO_NO_RUSAGE
 
277
     This error code is returned by drmaa_wait() when a  job  has
 
278
     finished but no rusage and stat data could be provided.
 
279
 
 
280
SEE ALSO
 
281
     <B><A HREF="../htmlman3/drmaa_submit.html">drmaa_submit(3)</A></B>.
 
282
 
 
283
 
 
284
 
 
285
 
 
286
 
 
287
 
 
288
 
 
289
 
 
290
 
 
291
 
 
292
 
 
293
 
 
294
 
 
295
 
 
296
 
 
297
 
 
298
 
 
299
 
 
300
 
 
301
 
 
302
 
 
303
 
 
304
 
 
305
 
 
306
 
 
307
 
 
308
 
 
309
 
 
310
 
 
311
 
 
312
 
 
313
 
 
314
 
 
315
 
 
316
 
 
317
</PRE>
 
318
<HR>
 
319
<ADDRESS>
 
320
Man(1) output converted with
 
321
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 
322
</ADDRESS>
 
323
</BODY>
 
324
</HTML>