SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
  Suspends the task.
copyrights:
- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR)
definition:
  default:
    attributes: null
    body: null
    params:
    - ${../../type/if/id:/name} ${.:/params[0]/name}
    return: ${../../status/if/code:/name}
  variants: []
description: |
  This directive suspends the task specified by ${.:/params[0]/name} from
  further execution by placing it in the suspended state.  This state is
  additive to any other blocked state that the task may already be in.  The
  task will not execute again until another task issues the ${resume:/name}
  directive for this task and any blocked state has been removed.  The
  ${restart:/name} directive will also remove the suspended state.
enabled-by: true
index-entries:
- suspending a task
interface-type: function
links:
- role: interface-placement
  uid: header
- role: interface-ingroup
  uid: group
- role: constraint
  uid: /constraint/directive-ctx-isr
- role: constraint
  uid: /constraint/directive-ctx-devinit
- role: constraint
  uid: /constraint/directive-ctx-task
- role: constraint
  uid: /constraint/directive-remote
name: rtems_task_suspend
notes: |
  The requesting task can suspend itself for example by specifying
  ${self-define:/name} as ${.:/params[0]/name}.  In this case, the task will be
  suspended and a successful return code will be returned when the task is
  resumed.
params:
- description: |
    is the task identifier.  The constant ${self-define:/name} may be used to
    specify the calling task.
  dir: null
  name: id
return:
  return: null
  return-values:
  - description: |
      The requested operation was successful.
    value: ${../../status/if/successful:/name}
  - description: |
      There was no task associated with the identifier specified by
      ${.:/params[0]/name}.
    value: ${../../status/if/invalid-id:/name}
  - description: |
      The task was already suspended.
    value: ${../../status/if/already-suspended:/name}
  - description: |
      The task resided on a remote node.
    value: ${../../status/if/illegal-on-remote-object:/name}
type: interface