pthread_create man page on Archlinux

Man page or keyword search:  
man Server   11224 pages
apropos Keyword Search (all sections)
Output format
Archlinux logo
[printable version]

PTHREAD_CREATE(3P)	   POSIX Programmer's Manual	    PTHREAD_CREATE(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

NAME
       pthread_create — thread creation

SYNOPSIS
       #include <pthread.h>

       int pthread_create(pthread_t *restrict thread,
	   const pthread_attr_t *restrict attr,
	   void *(*start_routine)(void*), void *restrict arg);

DESCRIPTION
       The  pthread_create()  function	shall  create  a  new	thread,	  with
       attributes  specified  by  attr, within a process. If attr is NULL, the
       default attributes shall be used. If the attributes specified  by  attr
       are  modified  later,  the  thread's  attributes shall not be affected.
       Upon successful completion, pthread_create() shall store the ID of  the
       created thread in the location referenced by thread.

       The  thread  is	created	 executing  start_routine with arg as its sole
       argument. If the start_routine returns, the effect shall be as if there
       was  an	implicit  call	to  pthread_exit()  using  the return value of
       start_routine as the exit status. Note that the thread in which	main()
       was  originally invoked differs from this. When it returns from main(),
       the effect shall be as if there was an implicit call  to	 exit()	 using
       the return value of main() as the exit status.

       The signal state of the new thread shall be initialized as follows:

	*  The signal mask shall be inherited from the creating thread.

	*  The set of signals pending for the new thread shall be empty.

       The  thread-local  current  locale and the alternate stack shall not be
       inherited.

       The floating-point environment shall be	inherited  from	 the  creating
       thread.

       If pthread_create() fails, no new thread is created and the contents of
       the location referenced by thread are undefined.

       If _POSIX_THREAD_CPUTIME is defined, the new thread shall have  a  CPU-
       time clock accessible, and the initial value of this clock shall be set
       to zero.

       The behavior is undefined if the value specified by the	attr  argument
       to  pthread_create() does not refer to an initialized thread attributes
       object.

RETURN VALUE
       If successful, the pthread_create() function shall return zero;	other‐
       wise, an error number shall be returned to indicate the error.

ERRORS
       The pthread_create() function shall fail if:

       EAGAIN The  system  lacked  the	necessary  resources to create another
	      thread, or the system-imposed  limit  on	the  total  number  of
	      threads in a process {PTHREAD_THREADS_MAX} would be exceeded.

       EPERM  The  caller  does	 not  have  appropriate	 privileges to set the
	      required scheduling parameters or scheduling policy.

       The pthread_create()  function  shall  not  return  an  error  code  of
       [EINTR].

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       There  is  no requirement on the implementation that the ID of the cre‐
       ated thread be available before the newly created thread starts execut‐
       ing. The calling thread can obtain the ID of the created thread through
       the return value of the pthread_create() function, and the  newly  cre‐
       ated thread can obtain its ID by a call to pthread_self().

RATIONALE
       A suggested alternative to pthread_create() would be to define two sep‐
       arate operations: create and start. Some applications would  find  such
       behavior	 more  natural. Ada, in particular, separates the ``creation''
       of a task from its ``activation''.

       Splitting the operation was rejected by	the  standard  developers  for
       many reasons:

	*  The	number of calls required to start a thread would increase from
	   one to two and thus place an additional burden on applications that
	   do  not  require  the  additional synchronization. The second call,
	   however, could be avoided  by  the  additional  complication	 of  a
	   start-up state attribute.

	*  An  extra  state  would be introduced: ``created but not started''.
	   This would require the standard to  specify	the  behavior  of  the
	   thread operations when the target has not yet started executing.

	*  For	those  applications that require such behavior, it is possible
	   to simulate the two separate steps with  the	 facilities  that  are
	   currently  provided. The start_routine() can synchronize by waiting
	   on a condition variable that is signaled by the start operation.

       An Ada implementor can choose to create the thread  at  either  of  two
       points in the Ada program: when the task object is created, or when the
       task is activated (generally at a ``begin''). If the first approach  is
       adopted,	 the  start_routine() needs to wait on a condition variable to
       receive the order to begin ``activation''. The second approach requires
       no   such  condition  variable  or  extra  synchronization.  In	either
       approach, a separate Ada task control block would need  to  be  created
       when the task object is created to hold rendezvous queues, and so on.

       An  extension of the preceding model would be to allow the state of the
       thread to be modified between the create and start.  This  would	 allow
       the  thread  attributes object to be eliminated. This has been rejected
       because:

	*  All state in the thread attributes object has to be able to be  set
	   for	the  thread. This would require the definition of functions to
	   modify thread attributes. There would be no reduction in the number
	   of  function	 calls	required to set up the thread. In fact, for an
	   application that creates all threads	 using	identical  attributes,
	   the	number	of function calls required to set up the threads would
	   be dramatically increased. Use of a thread attributes  object  per‐
	   mits	 the application to make one set of attribute setting function
	   calls.  Otherwise, the set  of  attribute  setting  function	 calls
	   needs to be made for each thread creation.

	*  Depending  on  the  implementation  architecture,  functions to set
	   thread state would require kernel calls, or for  other  implementa‐
	   tion reasons would not be able to be implemented as macros, thereby
	   increasing the cost of thread creation.

	*  The ability for applications to segregate threads by class would be
	   lost.

       Another	suggested alternative uses a model similar to that for process
       creation, such as ``thread fork''. The  fork  semantics	would  provide
       more  flexibility and the ``create'' function can be implemented simply
       by doing a thread fork followed immediately by a call  to  the  desired
       ``start routine'' for the thread. This alternative has these problems:

	*  For	many  implementations,	the entire stack of the calling thread
	   would need to be duplicated, since in many architectures  there  is
	   no way to determine the size of the calling frame.

	*  Efficiency  is reduced since at least some part of the stack has to
	   be copied, even though in most cases the  thread  never  needs  the
	   copied context, since it merely calls the desired start routine.

       If an implementation detects that the value specified by the attr argu‐
       ment to pthread_create()	 does  not  refer  to  an  initialized	thread
       attributes  object, it is recommended that the function should fail and
       report an [EINVAL] error.

FUTURE DIRECTIONS
       None.

SEE ALSO
       fork(), pthread_exit(), pthread_join()

       The Base Definitions volume of POSIX.1‐2008, Section 4.11, Memory  Syn‐
       chronization, <pthread.h>

COPYRIGHT
       Portions	 of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       --  Portable  Operating	System	Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
       cal  and	 Electronics  Engineers,  Inc  and  The	 Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum	 1  applied.)  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the	referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear  in  this  page  are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors,	 see  https://www.ker‐
       nel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group		     2013		    PTHREAD_CREATE(3P)
[top]

List of man pages available for Archlinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net